[FEATURE] Mixed-flow pressurization: TPA closure + unsteady friction (both solvers) + comparison study

[cbuahin]

Summary

Implement two literature-backed extensions to the mixed-flow (open-channel ↔ pressurized)
capability, in both the finite-volume solver (src/engine/hydraulics/fv/) and the classical
dynamic wave solver (src/engine/hydraulics/DynamicWave.cpp), plus a shareable validation
study comparing all closure/friction combinations against published laboratory experiments.

1. Two-Component Pressure Approach (TPA) — Vasconcelos, Wright & Roe (2006), J. Hydraul.
   Eng. 132(6): a pressurization closure that, unlike the Preissmann slot, sustains
   sub-atmospheric full-pipe flow (ΔA < 0) with a physically governed venting rule.
   • FV: FV_PRESSURE_CLOSURE SLOT|TPA (default SLOT — parity-preserving)
   • DW: SURCHARGE_METHOD TPA (4th enum value, experimental) + TPA_CELERITY
2. Unsteady friction (UF) — Pinto, Vasconcelos & Soares (2025), J. Hydraul. Eng.
   152(1) "SVUF": modified Vítkovský et al. (2000) source term
   S_fu = (k3/g)(∂V/∂t + c·SGN(V)|∂V/∂x|) with regime-dependent celerity. Implemented as
   an orthogonal option combinable with any closure in both solvers:
   UNSTEADY_FRICTION NONE|VITKOVSKY + UF_K3 (default NONE — inert).
   The paper's SVUF configuration ≡ {FV, TPA, UF on}.

Motivation

• ROADMAP.md names TPA as the documented extension path for sub-atmospheric transients,
  which the slot closure cannot represent (spurious free-surface reversion on downsurge).
• Steady-friction-only mixed-flow models require unphysical Manning n to reproduce observed
  transient damping (Pinto et al. 2025); the UF term fixes damping without inflating n.
• The slot-storage program (R2a landed: FV_PRESSURIZED_IMPLICIT) resolved the slot's
  head-loss/runtime pathologies; TPA extends the same linear closure below the crown.

Plan of record

• plans/MIXED_FLOW_CLOSURES_TPA_UF_PLAN_2026-08-29.md (this issue's parent plan:
  feasibility, deltas vs the code post-R2a, gates, study design)
• plans/TPA_TWO_COMPONENT_PRESSURE_PLAN.md (governing TPA implementation plan)

Scope / phases

• Phase 0 — Study scaffold studies/mixed_flow_closures/ (untracked via
  .git/info/exclude): E1–E4 lab decks (+ VJ-spliced variants), E6 fixture copies,
  matrix.yaml runner, NSE/RMSE metrics, digitized observed data
• Phase 1 — UF options plumbing, inert (7 touchpoints: SimulationOptions,
  OptionsHandler, InpWriter, C API get/set, report echo, Routing wiring, Python keys)
• Phase 2 — UF in FV (semi-implicit ∂V/∂t fold + explicit gradient source + clamp);
  gates U-G1…U-G5
• Phase 3 — UF in DW (dq/denominator extension + consistent dqdh); gates U-G6/U-G7
• Phase 4 — TPA in FV per TPA plan §3 (closure branch, regime flag, venting sweep),
  amended per parent plan §2.2 (PressurizedHeadSolver membership, VJ splice gates);
  gates A-G1…A-G6
• Phase 5 — TPA in DW per TPA plan §4 (constant-width slot arm + sealed latch);
  gates B-G1…B-G5
• Phase 6 — Full comparison matrix run (11 configurations × 6 experiments + sweeps);
  results memo to docs/analysis/
• Phase 7 — GUI exposure (tracked in the openswmm.gui companion issue)
• Phase 8 — Docs (Ch. 3 §3.3.10, Ch. 8 §8.4.x), hotstart schema, CHANGELOG

Acceptance criteria (headline gates; full tables in the plan)

• Defaults are inert: UNSTEADY_FRICTION NONE + FV_PRESSURE_CLOSURE SLOT +
  SURCHARGE_METHOD ∈ existing values ⇒ bit-identical on the 19-deck parity corpus, ctest ×3
• TPA-FV reproduces the 2006 rapid-filling experiment (bore arrival, head traces) and
  sustains sealed sub-atmospheric reaches the slot closure cannot (documented contrast)
• UF reproduces the paper's calibrated fits: Soares NSE ≥ 0.90, Vasconcelos Neto NSE ≥ 0.9,
  Aureli NSE ≥ 0.8 at the paper's (n, k3)
• Virtual-junction composition proven, not assumed: FV splice gates (A-G6) + DW latched-VJ
  downsurge gate (B-G5)
• Study folder re-runs end-to-end from a clean checkout with only OPENSWMM_BIN set

Non-goals

• Two-phase air modeling (paper's own limitation), Vasconcelos & Wright (2009) hybrid flux
  (documented contingency), per-link k3, waterhammer fidelity claims for DW

References

• Vasconcelos, Wright & Roe (2006), DOI 10.1061/(ASCE)0733-9429(2006)132:6(553)
• Pinto, Vasconcelos & Soares (2025), DOI 10.1061/JHEND8.HYENG-14443
• Sharior, Hodges & Vasconcelos (2023), DOI 10.1061/JHEND8.HYENG-13609 (DYNAMIC_SLOT precedent)

[dickinsonre]

I like this - maybe call it the Auburn Exrtension?