physmap 0.2.0__py3-none-any.whl

physmap/substrate/corpus_real.py

@@ -0,0 +1,206 @@
+"""PhysMAP Corpus Rung 2 — real-truth corpus-vs-causal test on Row-shaped data.
+
+Data-source-agnostic: three adapters feed the same machinery — `pipe` (the vehicle-3
+NB Ri sweep at conv_step3_final.json), `pump` (FDA pump fHb measurement; idles at
+EMPIRICAL-INCOMPLETE while harvest grows + magnitude bridge lands), `step0_fixture`
+(the algebraic stand-in for the plumbing smoke-test). Leave-one-out at the row level;
+rung-1's verdict functions are imported.
+
+The HEADLINE is G-corpus-beats-causal, but its interpretation is gated by
+G-divergence-exists, which itself has BOTH a numeric criterion AND a substrate
+criterion. If the substrate cannot carry a closure-reality divergence claim (Eq13 is a
+correlation, not measurement; algebraic truth is closure-derivable by construction),
+the headline is NOT-INFORMATIVE — neither pass nor fail. The corpus value test
+requires a divergent-truth substrate, which today only the (future) bridged pump is.
+
+Run: python -m physmap.substrate.corpus_real [--dataset pipe|pump|step0_fixture]
+Torch-free.
+"""
+
+from __future__ import annotations
+
+import argparse
+import csv
+import inspect
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import numpy as np
+
+from physmap.infra.blindspot_oracle import EMAX, SMAX, THETA_MAT
+from physmap.infra.corpus_runtime import _bootstrap_ci
+from physmap.infra.corpus_runtime import Entry, corpus_verdict, pde_residual_flag
+from physmap.substrate.stage1_ingest import (
+    TRUTH_FIXTURE,
+    TRUTH_INDEPENDENT,
+    Mechanism,
+    Row,
+    cfd_rows,
+    step0_fixture,
+)
+
+OUT_DIR = Path(__file__).parent.parent / "results" / "physmap_corpus_real"
+
+# Defaults
+K_DEFAULT = 5
+THETA_ERR = 0.05
+TOL = 0.05
+GUARDRAIL_PCT = 95
+SCALE_STEP0 = SMAX + EMAX
+
+# Pipe knobs
+RI_CAL_LO, RI_CAL_HI = 0.1, 10.0
+DEFAULT_PIPE_PATH = os.path.expanduser(
+    os.environ.get("PHYSMAP_PIPE_DATA", "~/physmap-wall/convection/conv_step3_final.json"))
+DEFAULT_PUMP_PATH = os.path.expanduser(
+    os.environ.get("PHYSMAP_PUMP_DATA", "~/physmap-wall/pump/pump_rows_step2.json"))
+
+
+# ── substrate metadata ───────────────────────────────────────────────────────
+
+@dataclass
+class SubstrateMeta:
+    """Per-substrate declaration of the properties that gate the headline's
+    interpretation. `divergent_truth_substrate` is the critical flag — if False, the
+    substrate cannot test the corpus's value (closure-vs-correlation is not closure-
+    vs-reality), and G-corpus-beats-causal must report NOT-INFORMATIVE."""
+    name: str
+    divergent_truth_substrate: bool
+    reason: str
+    norm_strategy: str                 # how to normalize closure/truth to comparable units
+    bound_for_pde: float | None        # None = PDE arm inert (no fixed ceiling)
+    magnitude_bridge_ok: bool
+    extra: dict = field(default_factory=dict)
+
+
+# ── physics coords (kNN index) ───────────────────────────────────────────────
+
+def physics_coords_row(row: Row, scaling: str = "log") -> np.ndarray:
+    """Per-row coord vector for kNN indexing. Mechanism-agnostic: uses each mechanism's
+    operating_value. Log scaling is the default — operating values typically span
+    orders of magnitude and Euclidean kNN behaves better in log space."""
+    vals = np.array([m.operating_value for m in row.mechanisms], float)
+    if scaling == "log":
+        return np.log(np.maximum(vals, 1e-12))
+    if scaling == "raw":
+        return vals
+    if scaling == "calib_range":
+        out = []
+        for m in row.mechanisms:
+            rng = m.calib_hi - m.calib_lo
+            out.append((m.operating_value - m.calib_lo) / max(rng, 1e-12))
+        return np.array(out, float)
+    raise ValueError(f"unknown scaling: {scaling}")
+
+
+# ── normalization (closure vs truth on a comparable scale) ───────────────────
+
+def _norm_for(row: Row, meta: SubstrateMeta) -> float:
+    """Per-row normalizer so |closure - truth|/norm is unitless and comparable to TOL."""
+    if meta.norm_strategy == "per_row_truth":
+        return float(row.cfd_truth)
+    if meta.norm_strategy == "global_scale":
+        return float(SCALE_STEP0)
+    if meta.norm_strategy == "per_row_ref_const":
+        return float(row.meta.get("RIH2_C5_normalization_reference", 1.0))
+    raise ValueError(f"unknown norm_strategy: {meta.norm_strategy}")
+
+
+def normalize_row(row: Row, meta: SubstrateMeta) -> tuple[float, float, float, float]:
+    """Return (closure_norm, truth_norm, error_norm_signed, norm)."""
+    norm = _norm_for(row, meta)
+    if meta.norm_strategy == "per_row_truth":
+        # closure/truth_norm both reported on the per-row truth scale
+        closure_norm = float(row.surrogate_prediction) / norm
+        truth_norm = 1.0
+    else:
+        closure_norm = float(row.surrogate_prediction) / norm
+        truth_norm = float(row.cfd_truth) / norm
+    err = truth_norm - closure_norm
+    return closure_norm, truth_norm, err, norm
+
+
+# ── per-row verdicts (the four real-arm verdicts; pde may be inert) ──────────
+
+def naive_verdict_row(row: Row) -> bool:
+    """Untrustworthy iff any mechanism is out of [calib_lo, calib_hi]."""
+    return any(not m.in_calibration() for m in row.mechanisms)
+
+
+def causal_verdict_row(row: Row, theta_mat: float = THETA_MAT) -> bool:
+    """Untrustworthy iff any material mechanism (contribution fraction ≥ theta_mat) is
+    out of calibration. Mirrors rung 1's causal verdict on the schema's mechanisms."""
+    mats = row.materialities()
+    for i, m in enumerate(row.mechanisms):
+        if (not m.in_calibration()) and (float(mats[i]) >= theta_mat):
+            return True
+    return False
+
+
+def guardrails_verdict_row(row: Row, reference: dict, pct: float = GUARDRAIL_PCT) -> bool:
+    """Untrustworthy iff any guardrail signal exceeds the pct-th percentile of the
+    precomputed reference distribution. Reference signals all-zero (placeholder substrate)
+    → guardrail arm is inert (never flags)."""
+    for k in ("ood", "residual", "variance"):
+        ref = np.asarray(reference.get(k, [0.0]), float)
+        thr = float(np.percentile(ref, pct)) if len(ref) else 0.0
+        sig = float(row.guardrail_signals.get(k, 0.0))
+        if sig > thr:
+            return True
+    return False
+
+
+def pde_residual_verdict(closure_norm: float, bound: float | None) -> bool | None:
+    """Bound check on the NORMALIZED closure. Returns None if the arm is inert
+    (no fixed ceiling for this substrate)."""
+    if bound is None:
+        return None
+    return bool(pde_residual_flag(np.array([closure_norm]), bound=bound)[0])
+
+
+# ── corpus build + LOO ───────────────────────────────────────────────────────
+
+def row_to_entry(row: Row, meta: SubstrateMeta, scaling: str = "log") -> Entry:
+    """Build a rung-1 Entry from a Row, normalized + with materiality fractions."""
+    closure_norm, truth_norm, err_norm, _ = normalize_row(row, meta)
+    mats = row.materialities()
+    s_frac = float(mats[0]) if len(mats) >= 1 else 0.0
+    e_frac = float(mats[1]) if len(mats) >= 2 else 0.0
+    return Entry(
+        coords=physics_coords_row(row, scaling=scaling),
+        closure=closure_norm,
+        truth=truth_norm,
+        error=err_norm,             # signed; corpus_verdict takes |error|
+        qoi_contrib_s=s_frac,
+        qoi_contrib_e=e_frac,
+    )
+
+
+def divergence_exists(rows: list[Row], meta: SubstrateMeta, tol: float,
+                      theta_mat: float) -> dict:
+    """Per-row check: is |closure - truth| > tol AND does causal NOT flag it?
+    Records the divergence-bearing condition ops explicitly."""
+    divergent = []
+    for r in rows:
+        cl_n, tr_n, _, _ = normalize_row(r, meta)
+        if abs(cl_n - tr_n) > tol and not causal_verdict_row(r, theta_mat):
+            divergent.append({"op": list(r.operating_point),
+                              "closure_norm": round(cl_n, 4),
+                              "truth_norm": round(tr_n, 4),
+                              "abs_err_norm": round(abs(cl_n - tr_n), 4)})
+    return {"n_divergent": len(divergent), "divergent_ops": divergent,
+            "numeric_criterion_passed": len(divergent) >= 1}
+
+
+# ---------------------------------------------------------------------------
+# The leave-one-out EXPERIMENT path -- loo_run, metrics_loo, gates, plotting,
+# CSV writing, the dataset loaders and the __main__ runner -- is not ported.
+#
+# None of it is on the benchmark path: outside this module only SubstrateMeta is
+# imported. It also computed per-arm recall and false-alarm rates, which a build
+# that reports no performance metrics must not carry -- the public-surface audit
+# flagged exactly those two lines, and deleting the dead code is the honest fix
+# rather than adding an exemption to the guard.
+# ---------------------------------------------------------------------------

physmap/substrate/engine.py

@@ -0,0 +1,209 @@
+"""Generic config-driven substrate engine.
+
+Per the v0.2 architecture refactor (Part 1): one `build_substrate(config, ...)`
+function replaces the per-vehicle hand-coded substrate loaders. Vehicle-specific
+data (geometry, closures, cell bands, raw-data loader) lives in YAML configs
+under `physmap/vehicles/`; the engine reads the config, enforces the
+geometry-match invariant, dispatches to a registered loader adapter, and
+annotates the returned SubstrateMeta with engine-level provenance.
+
+THE GEOMETRY-MATCH INVARIANT (the Sparrow-Cur / Lance & Smith lesson encoded
+as code):
+
+    assert matched_closure.geometry_class == config.geometry.class_, REFUSE
+
+The check has a single escape hatch: `expect_mismatch=True` paired with a
+non-empty `mismatch_rationale` in the VehicleConfig. This is the explicit
+override used by positive-control vehicles (Mudhafar) whose mismatch is the
+experiment. The override surfaces in the returned meta's `extra` dict so
+downstream auditors can see why the invariant was bypassed.
+
+Phase-1 staging: loader adapters in `substrate_loaders.py` are THIN wrappers
+around the existing hand-coded substrate loaders (`lance_smith_to_rows()`,
+etc.). The engine's job in Step 4 is the invariant + dispatch + meta
+annotation, not row-level computation. In Step 9 (per-vehicle migration),
+each loader is decomposed into a raw-data reader; the engine then computes
+matched + reference predictions via the closure registry, and the
+structural-equality gate becomes non-trivial.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+from pathlib import Path
+from typing import Callable
+
+from physmap.closures import REGISTRY, ClosureEntry
+from physmap.substrate.corpus_real import SubstrateMeta
+from physmap.substrate.stage1_ingest import Row
+from physmap.substrate.vehicle_config import (
+    VehicleConfig,
+    VehicleConfigError,
+    load_vehicle_config,
+)
+
+
+# ── exceptions ──────────────────────────────────────────────────────────────
+
+class GeometryMismatchError(ValueError):
+    """The matched closure's geometry_class does not equal the vehicle's
+    geometry class, and `expect_mismatch=True` was not set. Refused at
+    build time — the substrate engine guards itself against the trap that
+    bit Lance & Smith and almost bit Forrest."""
+
+
+# Loader signature: takes the validated VehicleConfig and the closure registry,
+# returns (rows, reference, meta) compatible with the existing pipeline.
+LoaderFn = Callable[[VehicleConfig, dict[str, ClosureEntry]],
+                    tuple[list[Row], dict, SubstrateMeta]]
+
+
+# ── LOADERS registry ────────────────────────────────────────────────────────
+# Populated by `substrate_loaders` at import time. Kept as a plain dict so
+# tests can monkey-patch entries for the byte-equality gate.
+
+LOADERS: dict[str, LoaderFn] = {}
+
+
+def register_loader(name: str, fn: LoaderFn) -> None:
+    """Register a data-source loader adapter. Raises if the name is taken
+    (silent override would mask refactor bugs)."""
+    if name in LOADERS:
+        raise ValueError(
+            f"LOADERS already has entry {name!r}; refusing silent override. "
+            f"If you intend to swap implementations, delete the entry first."
+        )
+    LOADERS[name] = fn
+
+
+# ── the engine ──────────────────────────────────────────────────────────────
+
+def build_substrate(
+    config: VehicleConfig | str | Path,
+    *,
+    registry: dict[str, ClosureEntry] | None = None,
+    corpus_path: str | Path | None = None,
+) -> tuple[list[Row], dict, SubstrateMeta]:
+    """Build a substrate from a VehicleConfig.
+
+    Args:
+        config: a `VehicleConfig` instance, or a path/string to a YAML file
+            (auto-loaded via `vehicle_config.load_vehicle_config`).
+        registry: closure registry; defaults to the global `REGISTRY`. Tests
+            inject a custom registry to exercise edge cases.
+        corpus_path: optional calibration-corpus path; accepted for forward
+            compatibility but unused in Phase 1 (the closure registry caches
+            ranges; the ClosureValidityDetector reads corpus.jsonl directly).
+
+    Returns:
+        (rows, reference, meta) — the same tuple shape every existing
+        substrate loader returns. `meta.extra` is augmented with engine-level
+        provenance keys: `substrate_engine_version`, `vehicle_id`,
+        `geometry_class`, `matched_closure_id`, `matched_closure_geometry_class`,
+        `matched_closure_status`, `expect_mismatch`, `mismatch_rationale` (only
+        if expect_mismatch is set), `reference_closure_ids`, `cell_bands_type`.
+
+    Raises:
+        GeometryMismatchError: matched-closure geometry != vehicle geometry
+            and expect_mismatch is not set.
+        ValueError: expect_mismatch is set but geometries actually agree
+            (dead override; either fix the YAML or drop the flag).
+        KeyError: unknown loader name in `data_source.loader`.
+    """
+    # Step 1 — coerce path to VehicleConfig
+    if isinstance(config, (str, Path)):
+        config = load_vehicle_config(config)
+    elif not isinstance(config, VehicleConfig):
+        raise TypeError(
+            f"build_substrate(config): expected VehicleConfig or path, got "
+            f"{type(config).__name__}."
+        )
+
+    reg = registry if registry is not None else REGISTRY
+
+    # Step 2 — registry lookup (KeyError already produced by VehicleConfig
+    # validation, but defensively re-check here so test-injected registries
+    # surface the error from the engine, not from dataclass construction).
+    if config.matched_closure_id not in reg:
+        raise KeyError(
+            f"matched_closure_id={config.matched_closure_id!r} not in the "
+            f"provided registry. Known: {sorted(reg.keys())}."
+        )
+    matched: ClosureEntry = reg[config.matched_closure_id]
+
+    # Step 3 — geometry-match invariant (THE Sparrow-Cur lesson)
+    geom_match = (matched.geometry_class == config.geometry.class_)
+
+    if not geom_match and not config.expect_mismatch:
+        raise GeometryMismatchError(
+            f"VehicleConfig {config.vehicle_id!r}: matched_closure_id "
+            f"{config.matched_closure_id!r} has geometry_class="
+            f"{matched.geometry_class!r} but vehicle geometry.class="
+            f"{config.geometry.class_!r}. This is the Sparrow-Cur / "
+            f"Lance & Smith trap; refused at build time. If this mismatch is "
+            f"INTENTIONAL (positive control), set `expect_mismatch: true` "
+            f"and supply a non-empty `mismatch_rationale` in the YAML."
+        )
+    if geom_match and config.expect_mismatch:
+        raise ValueError(
+            f"VehicleConfig {config.vehicle_id!r}: expect_mismatch=true but "
+            f"geometries actually match (both are "
+            f"{matched.geometry_class!r}). Either remove expect_mismatch / "
+            f"mismatch_rationale (override is dead), or correct the geometry "
+            f"class. Refusing to silently treat a matching configuration as "
+            f"a positive control."
+        )
+
+    # Step 4 — verify all reference closures resolve in the registry
+    # (VehicleConfig already checks against the GLOBAL REGISTRY; if a custom
+    # registry is injected, re-check.)
+    if registry is not None:
+        unknown_refs = [c for c in config.reference_closure_ids if c not in reg]
+        if unknown_refs:
+            raise KeyError(
+                f"reference_closure_ids unknown to provided registry: "
+                f"{unknown_refs}. Known: {sorted(reg.keys())}."
+            )
+
+    # Step 5 — loader dispatch
+    loader_name = config.data_source.loader
+    if loader_name not in LOADERS:
+        raise KeyError(
+            f"Unknown data-source loader {loader_name!r}. Registered: "
+            f"{sorted(LOADERS.keys())}. To add a new loader, call "
+            f"substrate_engine.register_loader(...) at import time."
+        )
+    loader = LOADERS[loader_name]
+
+    rows, reference, meta = loader(config, reg)
+
+    # Step 6 — annotate meta with engine-level provenance
+    extra = dict(meta.extra)
+    extra.update({
+        "substrate_engine_version": "v0.2-phase1",
+        "vehicle_id": config.vehicle_id,
+        "domain": config.domain,
+        "geometry_class": config.geometry.class_,
+        "geometry_dims": dict(config.geometry.dims),
+        "matched_closure_id": config.matched_closure_id,
+        "matched_closure_geometry_class": matched.geometry_class,
+        "matched_closure_status": matched.status,
+        "reference_closure_ids": list(config.reference_closure_ids),
+        "cell_bands_type": config.cell_bands.type,
+        "expect_mismatch": bool(config.expect_mismatch),
+    })
+    if config.expect_mismatch:
+        extra["mismatch_rationale"] = config.mismatch_rationale
+
+    annotated = dataclasses.replace(meta, extra=extra)
+    return rows, reference, annotated
+
+
+# Bootstrap: register the loader adapters at engine-import time. Importing
+# substrate_loaders also imports the existing legacy substrate modules (which
+# is fine — we want them available during the Phase-1 wrapper period).
+def _register_default_loaders() -> None:
+    from physmap.substrate import loaders as substrate_loaders   # noqa: F401  (side-effect import)
+
+
+_register_default_loaders()

physmap/substrate/forrest.py

@@ -0,0 +1,249 @@
+"""PhysMAP Forrest mini-channel vehicle — D3 differentiator substrate.
+
+Build the substrate for the D3 differentiator experiment. Source paper:
+Forrest, Hu, Buongiorno, McKrell (2014), "Convective Heat Transfer in a High
+Aspect Ratio Mini-Channel Heated on One Side," J. Heat Transfer 138(2):021704,
+DOI: 10.1115/1.4031646 / OSTI 1295764 / SAND2014-18834J. Geometry confirmed
+against the 2012 RERTR predecessor paper (Forrest, Buongiorno, McKrell, Hu).
+
+What this substrate is for (one sentence): a steady-state internal-flow
+heat-transfer vehicle with three cells defined by Re band — BENIGN
+(10k≤Re≤70k, geometry-MATCHED Modified Sparrow-Cur MAE 6.1%, paper Table 4),
+TRANSITION (4k≤Re<10k, textbook turbulent closures not validated; paper's
+semi-analytic Eq. 24 covers it at MAE 4.6%), and SUB_CRITICAL_LAMINAR
+(Re<4k, critical Re between 3500-4000 per Eq. 18; turbulent closures
+overpredict by ~40% at Pr=5.4 per paper body p.7) — suitable for testing
+whether PhysMAP's corpus-error signal catches divergence that
+input-distribution novelty detectors miss or weakly signal.
+
+Geometry-matched primary closure (resolves the Lance & Smith trap):
+  The primary closure tested on this substrate is Modified Sparrow-Cur
+  (Forrest 2014 Eq. 7, corpus entry
+  `modified-sparrow-cur-asym-narrow-rect-channel-2014`), which IS designed
+  for one-sided heated narrow rectangular channels. Circular-pipe closures
+  (Gnielinski, Dittus-Boelter, Petukhov, Sieder-Tate) are computed for
+  cross-comparison against Forrest's Table 4 MAEs but are NOT the primary
+  test target. Testing the differentiator on the geometry-mismatched
+  circular-pipe closures would contaminate the result with geometry
+  mismatch — exactly the trap that produced the Lance & Smith
+  confined-geometry finding. By using the matched closure, the
+  divergence at Re<4k and the transition is cleanly attributable to
+  closure validity-edge failure (Re below the closure's validated lower
+  bound 10000), not to geometry incompatibility.
+
+Build discipline (mirrors D1 / Lance & Smith):
+  - Truth column = measured Nu ONLY. Refuse fitted-correlation truth
+    (Eq. 19 and Eq. 24 are the AUTHORS' own fits; cannot serve as truth —
+    independence guard).
+  - Steady-state → no temporal-autocorrelation discount on effective n.
+    Each (Re, Pr) operating point is a genuinely independent sample.
+  - Inspect before blessing (D1 done-gate discipline).
+
+Two corrections wired in from the build directive:
+
+  Correction 1 — baseline-invisibility is the MEASURED OUTCOME of D3,
+  NOT passed by reading the paper. D3 measures the SIGNAL-GAP between
+  both baseline detectors (distance-to-training AND prediction-variance/
+  ensemble) and the corpus signal at the transition cell. Both detectors
+  must be quiet simultaneously at the transition for the truly-invisible
+  bar; gap-against-threshold is the weaker bar. Which bar counts as a win
+  is pre-registered BEFORE the experiment runs.
+
+  Correction 2 — Mudhafar (canonical smooth pipe, separate substrate) is
+  the baseline positive control. Built deliberately, not as an
+  afterthought. Mudhafar's divergent cells (small d, rough surface) are
+  baseline-VISIBLE by design. Same detectors that fire on Mudhafar's
+  divergence should stay quiet/weak on Forrest's transition — the
+  contrast that makes the differentiator result interpretable.
+
+Data-acquisition status:
+  - OSTI 1295764 / 2014 paper read in full; confirms NO supplementary data
+    tables. Table 2 (geometry) + Table 4 (cell-level MAE summary) are the
+    only tables. Per-point Nu values are in Figures 5, 6, 7, 9.
+  - Hybrid path: cell-level analysis from Table 4 + Eq. 24 model for the
+    benign cell (no digitization); figure digitization of Fig. 5 for the
+    transition+sub-critical cells where the differentiator signal lives.
+    Author-data request as long-tail clean path.
+
+The raw-data ingest function (forrest_to_rows) is parameterized by a
+caller-supplied data table; the three ingest stubs below
+(from_thesis_table / from_digitization / from_author_csv) raise
+NotImplementedError until the data-acquisition decision lands.
+
+Entry (post-data-acquisition): python -m physmap.forrest_inspect
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+
+# Cleanup 5 part 2: the Forrest legacy closure functions, calibration-range
+# constants, ForrestRow dataclass, forrest_to_rows loader, and the three
+# data-acquisition stubs have all been retired. Their canonical homes:
+#   - closures/formulas.py        (Pohlhausen, McAdams, Churchill,
+#                                   Sparrow-Cur, Gnielinski, Dittus-Boelter,
+#                                   Petukhov, Sieder-Tate formulas)
+#   - closures/registry.py        (re_range, pr_range, geometry_class,
+#                                   status)
+#   - vehicles/forrest.yaml       (geometry + data_source)
+#   - substrate_loaders.py        (engine-driven row build)
+#
+# This module retains ONLY:
+#   - geometry constants (CHANNEL_*) documenting the rig dimensions
+#   - the Cell Literal type + cell_assignment helper (still imported by
+#     forrest_resolvability)
+#   - the Re-band thresholds + Forrest Table-4 reference MAE dicts
+#     (descriptive constants used by reports + analysis scripts)
+
+
+# ── geometry + fluid properties ──────────────────────────────────────────────
+# From the Forrest et al. predecessor paper (2012 RERTR conference paper),
+# Table 1, confirmed in SAND2014-18834J / OSTI 1295764:
+#   - High-aspect-ratio rectangular channel, α* = gap/width = 0.035 (≈29:1
+#     width:gap convention).
+#   - Hydraulic diameter Dh = 3.78 mm (Table 1, explicit). The 2*gap = 3.92 mm
+#     value is the parallel-plates asymptote; the actual finite-width
+#     rectangular-channel Dh = 4·A_flow / P_w gives 3.78. The paper uses Dh
+#     as the characteristic length in its Re and Nu definitions.
+#   - One-sided heating (asymmetric); the heated wall is one of the long
+#     faces (51 mm × 305 mm heated). The Nu is the channel-averaged for the
+#     heated wall.
+#   - Working fluid: water. Pr range 2.2 – 5.4 (corresponds to bulk
+#     temperatures of roughly 60-95°C; lower Pr = higher temperature).
+
+# Geometry per Forrest, Buongiorno, McKrell, Hu (2012 RERTR conference paper),
+# Table 1 — the predecessor publication to the 2014 J. Heat Transfer paper.
+# Same experimental rig; the 2012 paper's Table 1 gives the dimensions
+# explicitly. (The 2014 paper extends the dataset to more Pr values and
+# higher Re, but uses the same rig.)
+CHANNEL_GAP_MM = 1.96
+CHANNEL_WIDTH_MM = 56.0
+CHANNEL_LENGTH_MM = 483.0
+CHANNEL_HEATED_LENGTH_MM = 305.0
+CHANNEL_HEATED_WIDTH_MM = 51.0
+CHANNEL_ASPECT_RATIO_ALPHA_STAR = CHANNEL_GAP_MM / CHANNEL_WIDTH_MM  # = 0.035, per Table 1
+CHANNEL_ASPECT_RATIO_INVERSE = CHANNEL_WIDTH_MM / CHANNEL_GAP_MM     # = 28.6, the
+                                                                     # "high aspect ratio"
+                                                                     # convention (~29:1)
+CHANNEL_HYDRAULIC_DIAMETER_MM = 3.79   # Forrest 2014 Table 2 explicit value
+                                       # (2012 RERTR paper Table 1 had 3.78;
+                                       # 2014 paper supersedes with 3.79).
+                                       # NOT 2*gap=3.92: the 2*gap limit is the
+                                       # parallel-plates asymptote; the actual
+                                       # rectangular-channel Dh = 4·A_flow/P_w
+                                       # accounts for finite width.
+
+# Closure-bound calib ranges per the Track C corpus entries.
+#
+# PRIMARY (geometry-matched) closure for this substrate:
+#   Modified Sparrow-Cur (Forrest 2014 Eq. 7) — Nu = 0.036·Re^0.76·Pr^(1/3).
+#   Corpus entry: modified-sparrow-cur-asym-narrow-rect-channel-2014.
+#   This is the ONLY corpus closure with explicit one-sided-heating geometry
+#   dependence and is the right closure for Forrest's narrow rectangular
+#   mini-channel. Its validity range is what should drive the
+#   benign/transition/laminar cell-validity gates.
+#
+# COMPARISON (geometry-mismatched, circular-pipe) closures:
+#   Gnielinski, Dittus-Boelter, Petukhov, Sieder-Tate. These are computed
+#   alongside Sparrow-Cur for cross-comparison against Forrest 2014 Table 4
+#   MAEs, but the closure-validity test runs on Sparrow-Cur (the matched
+#   closure). Testing the differentiator on Gnielinski would contaminate
+#   the result with geometry mismatch (the same trap that produced the
+#   Lance & Smith confined-geometry finding), so the matched closure is
+#   the primary; circular-pipe closures are reported for reference only.
+
+
+
+# ── cell definitions ─────────────────────────────────────────────────────────
+# Cell-band thresholds match Forrest 2014 paper's EXPLICIT characterizations
+# (revised after reading the full paper; the prior recon-memory had four
+# cells with wrong boundaries).
+#
+#   - Re < 4,000:       SUB_CRITICAL / LAMINAR. Critical Re between 3,500
+#                       and 4,000 (Eq. 18). At Re < 4,000 the flow is
+#                       likely still laminar. Paper body, p.7: the
+#                       Gnielinski correlation for Pr = 5.4 (top curve in
+#                       Fig. 6) overpredicts the Nusselt number by about
+#                       40%, indicating the closure is being applied
+#                       below its validity. Modified Sparrow-Cur (turbulent
+#                       form, Re^0.76) would similarly over-predict here.
+#
+#   - 4,000 ≤ Re < 10,000: TRANSITION. Flow becomes fully turbulent at
+#                          Re ≈ 7,000 per the friction-factor data (paper
+#                          p.5). Textbook turbulent closures are not
+#                          validated here — Forrest's Table 4 MAEs are
+#                          reported only for Re ≥ 10,000. The paper's
+#                          semi-analytic Eq. (24) covers 4k–70k at MAE
+#                          4.6%.
+#
+#   - 10,000 ≤ Re ≤ 70,000: BENIGN (turbulent). Textbook closures applicable
+#                            here with MAE 6.1-15.2% (Table 4). NO sub-cell
+#                            structure within this range — Gnielinski's
+#                            8.4% MAE is reported uniformly across this
+#                            interval, not split by sub-range.
+#
+# This is THREE cells, not four. The prior `divergent_high_re` (Re > 35k)
+# was a misreading of Eq. (19)'s 10k–35k validity (the authors' OWN power
+# law fit, limited to the range where a simple power law is adequate);
+# it is NOT a textbook-closure divergence cell.
+
+Cell = Literal[
+    "benign_turbulent",                # do-no-harm cell: closures perform per Table 4
+    "transition_excluded_indeterminate", # excluded: closure-divergence signal within measurement floor
+    "sub_critical_laminar",            # divergent test cell: ~50-80% closure over-prediction
+]
+
+BENIGN_RE_LO = 10000.0          # paper Table 4 lower bound for all textbook closures
+BENIGN_RE_HI = 70000.0          # paper Table 4 upper bound for all textbook closures
+TRANSITION_RE_LO = 4000.0       # paper p.7 / Fig. 5 region — EXCLUDED, not benign
+TRANSITION_RE_HI = 10000.0
+SUB_CRITICAL_RE_HI = 4000.0     # paper Eq. 18: Re_crit between 3500-4000
+
+
+def cell_assignment(Re: float) -> Cell:
+    """Per-row cell label by Re band. Bands READ FROM the Forrest 2014 paper
+    (Table 4 + Eq. 18 + p.7 cell-by-cell discussion), NOT derived from the
+    data (which would be a leak).
+
+    Cell roles in the D3 differentiator (per the build directive):
+      - `sub_critical_laminar`: the ONLY divergent test cell. Visible n=2
+        in Fig 5 at Re ~ 3800, Pr=5.4. Both Sparrow-Cur and Gnielinski
+        over-predict by ~50-80% (resolvable: |gap|/unc > 3).
+      - `transition_excluded_indeterminate`: excluded from the test cell
+        set. Resolvability triage on visual estimates from Fig 5 (n=12)
+        shows median |gap|/unc ~ 0.4-0.5 — within the measurement-
+        uncertainty floor. Paper text calls the transition "conservative
+        estimate" territory, which is a safety statement not a validity
+        statement, so the cell is indeterminate (NOT benign-relabeled).
+      - `benign_turbulent`: do-no-harm cell. Closures perform per Table 4
+        (Sparrow-Cur MAE 6.1%, Gnielinski 8.4%, etc.). The corpus signal
+        is expected to be quiet here.
+    """
+    if Re < SUB_CRITICAL_RE_HI:
+        return "sub_critical_laminar"
+    if Re < TRANSITION_RE_HI:
+        return "transition_excluded_indeterminate"
+    return "benign_turbulent"   # 10000 ≤ Re; covers full validated turbulent range
+
+
+# Paper Table 4 reference MAE numbers (2.2 ≤ Pr ≤ 5.4, Re per cell)
+# Used for cell-level comparison against corpus signal predictions.
+# Recorded here as ground-truth references; the live closure-vs-truth
+# comparison still runs row-by-row on measured Nu when data is in hand.
+TABLE_4_MAES_BENIGN = {
+    "modified-sparrow-cur-asym-narrow-rect-channel-2014": 0.061,   # 6.1% — GEOMETRY-MATCHED, lowest
+    "dittus-boelter-1930":     0.064,   # 6.4%
+    "modified-colburn":        0.073,   # 7.3% (not in corpus)
+    "gnielinski-1976":         0.084,   # 8.4%
+    "petukhov-1970":           0.114,   # 11.4% (not currently in corpus)
+    "sieder-tate-1936":        0.152,   # 15.2%
+    "barrow-one-sided":        0.204,   # 20.4% (worst — not in corpus)
+}
+TABLE_4_FORREST_FITS = {
+    "Empirical fit Eq.(19) [10000-35000]":  0.038,   # 3.8%
+    "Semi-analytic Eq.(24) [4000-70000]":   0.046,   # 4.6%
+}
+
+
+