# FieldHydro — Verification & Validation Report

> **Auto-generated** by `scripts/gen-validation-report.js` from `tests/vv-cases.js`.
> Do not edit by hand — run `npm run validate` to regenerate. The same benchmark
> records are asserted by the CI gate `tests/field-vv.test.js`, so this report cannot
> drift from the code it documents.

## Purpose

This report is the traceable evidence that FieldHydro's core hydraulic and geodetic
computations are (a) **verified** — the code solves the governing equations correctly
against analytical/exact oracles — and (b) **validated** — the models reproduce
real observed event data. It is intended for review by dam-safety regulators, FEMA
floodplain professionals, and SBIR technical reviewers, and follows the
Verification & Validation vocabulary of ASME V&V 10 / USACE modeling guidance.

- **Verification** — "Are we solving the equations right?" Code output vs. a closed-form
  or exact numerical oracle. No field data involved.
- **Validation** — "Are we solving the right equations?" Model output vs. independent
  real-world observations (here, the USGS 03451500 Hurricane Helene peak record).
- **Data Integrity** — self-consistency and provenance checks of the demo data against its
  **own** source (e.g. the demo peak equals the RAS extract it was drawn from). These are
  honest guards against fabrication and datum/label drift, but they are **not** validation —
  they don't test the engine against outside truth — so they are counted separately.

## Summary

| Category | Passed | Total |
|----------|--------|-------|
| Verification | 12 | 12 |
| Validation | 5 | 5 |
| Data Integrity | 6 | 6 |
| **Overall** | **23** | **23** |

**Result: ✅ ALL PASS** — 23 of 23 benchmarks within tolerance.

Each case declares an **acceptance tolerance** up front (absolute or relative); a case
passes only if its residual is at or below that tolerance. Tolerances are tight
(1e-6 to 1e-12) for pure code verification and physically meaningful for real-data
validation.

## 1. Verification — governing equations vs. exact oracles

The conveyance code exercised here is the **exact shipping implementation**
(`field/fieldhydro-hydraulics.js`, the single source of truth loaded by
`ar-cross-section.html`) — not a re-derivation. Verification therefore guards the
code path a user actually runs.

| ID | Benchmark | Quantity | Reference | Computed | Residual | Tol | Result |
|----|-----------|----------|-----------|----------|----------|-----|--------|
| V-HYD-1 | Manning Q — rectangular channel (10 m × 2 m, n=0.013, S=0.001) | Discharge Q (m³/s) | 61.709868 | 61.709868 | 3.196e-11 (rel) | 1.000e-6 | ✅ PASS |
| V-HYD-2 | Conveyance engine reproduces closed-form trapezoid Q (b=6, y=1.5, z=2) | Discharge Q (m³/s) | 22.488137 | 22.488137 | 0 (rel) | 1.000e-9 | ✅ PASS |
| V-HYD-3 | Conveyance subdivision with equal n reduces to single-n section | Conveyance K (m³/s·√S) | 468.50286 | 468.50286 | 0 (abs) | 1.000e-12 | ✅ PASS |
| V-HYD-4 | Conveyance roughness scaling K(2n) = K(n)/2 | K(2n) / K(n) (—) | 0.5 | 0.5 | 0 (abs) | 1.000e-12 | ✅ PASS |
| V-HYD-5 | Capacity ratio Q_now/Q_ref invariant to absolute roughness n | ratio(n=0.09) − ratio(n=0.03) (—) | 0 | 0 | 0 (abs) | 1.000e-12 | ✅ PASS |
| V-GEO-1 | ENU east distance matches WGS84 prime-vertical radius (per 1000 m) | East-distance relative error ((fraction)) | 0 | 4.875e-13 | 4.875e-13 (abs) | 1.000e-9 | ✅ PASS |
| V-GEO-2 | ENU north distance matches WGS84 meridian radius (per 1000 m) | North-distance relative error ((fraction)) | 0 | 3.703e-13 | 3.703e-13 (abs) | 1.000e-9 | ✅ PASS |
| V-GEO-5 | Local-tangent ENU vs rigorous ECEF→ENU, horizontal, ~1.9 km baseline | Horizontal disagreement (m) | 0 | 0.20634509 | 0.20634509 (abs) | 0.3 | ✅ PASS |
| V-GEO-6 | Ellipsoidal→orthometric (NAVD88) datum conversion, H = h − N | Orthometric height (m) | 601.86 | 601.86 | 0 (abs) | 1.000e-9 | ✅ PASS |
| V-GEO-7 | NGVD29→NAVD88 applies the VERTCON offset and fails loud (NaN) when it is omitted | Correct behavior (bool) | 1 | 1 | 0 (abs) | 0 | ✅ PASS |
| V-GEO-3 | geoToEnu → enuToGeo round-trip identity (~2–3 km offset) | Position residual (deg) | 0 | 0 | 0 (abs) | 1.000e-9 | ✅ PASS |
| V-GEO-4 | Bilinear DEM interpolation exact on a linear surface | Sampled elevation (m) | 104.675 | 104.675 | 1.421e-14 (abs) | 1.000e-9 | ✅ PASS |

### Geodesy: bias removed (was +0.33 % / −0.11 %)

Earlier revisions used the WGS84 semi-major axis `a` as the local radius, biasing ENU
distances by **+0.332 % N–S (≈ +3.32 m/km)** and **−0.113 % E–W (≈ −1.13 m/km)** at the
Asheville demo latitude (35.59° N). `geoToEnu` now uses the ellipsoidal **radii of
curvature** M(φ)/N(φ), so cases **V-GEO-1/2** — measured against an independent ellipsoidal
oracle — show a **numerically zero** residual (≤ 1e-9): the systematic bias is gone.

Case **V-GEO-5** bounds the remaining cost of the fast local-tangent method against the
rigorous geodetic→ECEF→ENU transform (`geoToEnuEcef`): they agree to **< 0.3 m over a
~1.9 km baseline** (~1e-4 relative), far below the field uncertainty bands. A rigorous
ECEF→ENU path and explicit vertical-datum helpers (GEOID18 ellipsoidal→orthometric,
NGVD29→NAVD88, case **V-GEO-6**) are now available for validation and datum-critical work.

## 2. Validation — models vs. real observed data

Validation compares model/demo output against **independent real-world observations**:

1. **Hurricane Helene** peak at **USGS 03451500, French Broad River at Asheville, NC**
   (2024-09-27) — a gauged flood-of-record. The absolute peak WSEL is checked against the
   gauge datum + recorded peak stage, and the event is confirmed to exceed the prior
   period-of-record peak (1916), as documented.
2. The project's own **overlap-metric instrument** (`approxPolygonJaccard`, V-VAL-5) is
   validated against a closed-form Intersection-over-Union so the tool used to score
   AR-rendered vs. reference extents is itself trustworthy.
3. **Anson County WWTP breach** demo WSELs are confirmed to fall inside the independently
   RAS-computed water-surface envelope and to map to the real RAS plan titles (V-VAL-10/11).

| ID | Benchmark | Quantity | Reference | Computed | Residual | Tol | Result |
|----|-----------|----------|-----------|----------|----------|-----|--------|
| V-VAL-1 | Helene peak WSEL = gauge datum + recorded peak stage | Peak WSEL (ft NAVD88) | 1974.6 | 1974.6 | 2.274e-13 (abs) | 0.01 | ✅ PASS |
| V-VAL-4 | Helene peak stage exceeds previous record of record (1916) | Peak − previous record (ft) | 1.57 | 1.57 | 2.220e-16 (abs) | 1.000e-9 | ✅ PASS |
| V-VAL-5 | Validation instrument: approx-Jaccard vs closed-form IoU (offset 0.3) | Jaccard / IoU (—) | 0.53846154 | 0.54 | 0.0015384615 (abs) | 0.02 | ✅ PASS |
| V-VAL-10 | All demo WSELs within the HEC-RAS computed water-surface envelope | WSELs outside RAS envelope (count) | 0 | 0 | 0 (abs) | 0 | ✅ PASS |
| V-VAL-11 | Demo scenario labels match the real HEC-RAS plan titles (p15–p19) | Scenario/plan-title mismatches (count) | 0 | 0 | 0 (abs) | 0 | ✅ PASS |

## 3. Data integrity — provenance & self-consistency (not validation)

These guard against fabrication and datum/label drift by checking the demo data against its
**own** source. They are deliberately **not** counted as validation — a demo value equal to
the extract it was drawn from is a closed loop, not evidence the engine reproduces reality.

- **Anson County WWTP lagoon breach** — a genuine **HEC-RAS 2D breach analysis submitted to
  NC Dam Safety** (public record, ANSON-056/057 JD-HC Reclassification), reprojected from
  EPSG:6543 (NC State Plane) to WGS84. Ingest fidelity: reprojection lands inside Anson
  County, HEC-RAS attributes survive intact, no fabricated annual return periods, and
  depths/geometry are physically valid (V-VAL-6/7/8). Closed-loop provenance: the demo
  geojson's **peak water surface (452.59 ft NAVD88) equals the HEC-RAS 2D-computed Maximum
  Water Surface to the hundredth of a foot** (V-VAL-9) — a *self-consistency* check on the
  extract, from `tests/fixtures/anson-ras-reference.json`.
- Helene demo internal consistency: ft→m datum conversion and bathtub-fill vertex WSEL
  (V-VAL-2/3).

| ID | Benchmark | Quantity | Reference | Computed | Residual | Tol | Result |
|----|-----------|----------|-----------|----------|----------|-----|--------|
| V-VAL-2 | Helene peak WSEL ft→m conversion consistency | Peak WSEL (m NAVD88) | 601.858 | 601.85808 | 8.000e-5 (abs) | 0.001 | ✅ PASS |
| V-VAL-3 | Bathtub inundation vertices all at modeled WSEL (1983 vertices) | Max vertex elevation deviation from WSEL (m) | 0 | 8.000e-5 | 8.000e-5 (abs) | 0.01 | ✅ PASS |
| V-VAL-6 | Anson HEC-RAS reprojection (EPSG:6543→WGS84) lands in Anson County, NC | All vertices within county bbox (bool) | 1 | 1 | 0 (abs) | 0 | ✅ PASS |
| V-VAL-7 | Anson breach integrity: no fabricated return periods; scenario_id ↔ breach-mode label | Fabricated-RP + label mismatches (count) | 0 | 0 | 0 (abs) | 0 | ✅ PASS |
| V-VAL-8 | Anson depths physical & rings closed (21 parcels, 4 scenarios) | Invalid features (neg depth, >50 ft, or open ring) (count) | 0 | 0 | 0 (abs) | 0 | ✅ PASS |
| V-VAL-9 | Demo geojson peak WSEL matches HEC-RAS 2D computed maximum water surface | Peak WSEL (ft NAVD88) | 452.59 | 452.59 | 0 (abs) | 0.05 | ✅ PASS |

## Scope & limitations

- Verification covers the **conveyance / Manning** engine, the **geodetic transform**,
  **bilinear DEM sampling**, and the **overlap-metric** harness. It does **not** yet cover
  the LSPIV discharge pipeline, AR camera-pose projection, or DSM occlusion — those
  require the uncertainty-propagation and image-based validation tracks.
- Validation currently rests on the gauged Hurricane Helene peak (USGS 03451500) and the
  overlap-metric instrument check; the Anson HEC-RAS material is treated as **data-integrity /
  provenance** evidence (self-consistency against the same RAS extract), not validation, since a
  demo-vs-own-source match is a closed loop. The strongest missing rung is a **model-vs-independent
  -observation** comparison for the breach (e.g. surveyed high-water marks); additional gauged
  events and independent HWM datasets can be added with the same pattern.
- Nothing here constitutes site-specific engineering certification. FieldHydro outputs
  remain screening/field-verification aids unless independently checked against
  RTK/LiDAR/HEC-RAS reference data for the specific site.

## Reproduce

```bash
npm test                              # runs the V&V gate (tests/field-vv.test.js) with everything else
npm run validate                      # regenerate this report
node scripts/gen-validation-report.js --check   # CI: fail if this file is stale
```

## Reference sources

- Longhand Q = (1/n)·A·R^(2/3)·S^(1/2) (Chow 1959, Eq. 5-7)
- Closed-form trapezoid geometry + Manning (Henderson 1966, §2)
- HEC-RAS Hydraulic Reference Manual — conveyance subdivision limit
- Manning K = (1/n)·A·R^(2/3) is exactly ∝ 1/n
- Equal-n cancels in K_now/K_ref (tool methodology §8)
- True east dist = N(φ)·cosφ·Δλ, N(35.59°)=6,385,379 m
- True north dist = M(φ)·Δφ, M(35.59°)=6,357,046 m
- Geodetic→ECEF→ENU (exact ellipsoidal, no distance approximation)
- GEOID18 separation ≈ −31.86 m (western NC); H = h − N
- NGS VERTCON offset is site-specific and mandatory; missing ⇒ NaN, not a silent datum mislabel
- Exact inverse of the planar map (self-consistency)
- Bilinear interpolation is exact for affine fields
- USGS 03451500 French Broad at Asheville — 2024-09-27 peak stage 24.67 ft
- Exact international foot (0.3048 m)
- Bathtub method holds a single horizontal water surface
- USGS 03451500 period of record; prior record 23.1 ft (1916)
- Exact IoU of unit squares offset 0.3 = (1−d)/(1+d) = 0.53846…
- NC State Plane FIPS 3200 → WGS84; Anson County ≈ 34.6–35.1° N, 80.1–79.7° W
- p15–p19 are HEC-RAS breach FAILURE MODES (Cascade/Piping/Overtopping), not annual recurrence intervals
- Breach depths 2.6–23.2 ft NAVD88; closed polygon rings
- Anson HEC-RAS 6.6 2D results HDF — Maximum Water Surface (NCDS public record)
- RAS envelope 300.04–452.59 ft NAVD88
- RAS plan titles: Lower/Combined × Piping/Overtopping, Cascade

---

*Generated from `tests/vv-cases.js`. FieldHydro — "real algorithms, no fakes." Maintained by Michael Flynn, PE.*