physmap 0.2.0__py3-none-any.whl

physmap/materiality/surrogate_fit.py

@@ -0,0 +1,293 @@
+"""Fit a forced-convection surrogate and measure how well it generalises.
+
+This exists because of one number that was never recorded: the residual of the original
+study's `Nu_forced(Re)` fit against the gravity-off CFD it was fitted to. Without it the
+coupling between the flag and the surrogate error cannot be bounded -- see
+`docs/findings/surrogate-and-truth-provenance.md`.
+
+WHY THE INPUT IS A LIST OF CASES, NOT A MAPPING
+-----------------------------------------------
+An earlier version took `{Re: Nu}`. That is wrong for this grid. A 2-D `(Re, Gr*)` grid
+contains **several cases at the same Re with different Gr, heat flux or entrance length**,
+and a dict keyed on Re silently keeps the last one written. Cases would vanish without
+any error, and the fit would be computed over a set nobody chose.
+
+So ingestion is by `Case`, each with its own id and its full operating conditions.
+Duplicate ids raise. Repeated `Re` values are legal and expected.
+
+HOW A REPEATED `Re` IS HANDLED, EXPLICITLY
+------------------------------------------
+1. **All cases are kept and all are fitted.** Nothing is collapsed or averaged.
+2. **A surrogate whose only input is `Re` cannot separate them.** Two cases at one `Re`
+   with different `Nu` must receive the same prediction, so some error is unavoidable
+   *for this choice of surrogate inputs*. Two quantities are reported, and they are not
+   the same thing:
+
+   - `same_re_spread` — the **observed** relative spread `(max − min) / mean`. A
+     description of the data, not a bound on anything.
+   - `minimax_relative_bound` — the **actual floor** on the worst relative error, for
+     the minimax measure: `(max − min) / (max + min)`, attained at the harmonic mean.
+
+   For `Nu = 8.0` and `9.6` these are 18.2% and 9.1%. An earlier version reported the
+   spread and called it the floor; it is about twice the floor. A bound is only
+   meaningful once the error measure is named — the RMS-relative measure has a different
+   optimum and a different value.
+
+   Neither quantity says the variation is irreducible **in the physics**. It is
+   unresolvable **by a surrogate whose only input is `Re`**, which is a statement about
+   the chosen inputs and is exactly why `conditions` is carried on every `Case`.
+3. **The split groups by `Re`.** Every case sharing an `Re` goes to the same side. A case
+   at `Re = 800` in the fit and another at `Re = 800` held out would leak, because the
+   surrogate sees only `Re` and would already have been shown that abscissa.
+
+Nothing here computes a label, a flag or a metric. It fits, predicts, and reports
+residuals.
+"""
+
+from __future__ import annotations
+
+import math
+from collections import defaultdict
+from dataclasses import dataclass, field
+from typing import Iterable, Mapping, Sequence
+
+__all__ = [
+    "Case",
+    "FitResult",
+    "ResidualReport",
+    "ingest",
+    "fit_power_law",
+    "residuals",
+    "split_by_re",
+    "fit_and_verify",
+    "same_re_spread",
+    "minimax_relative_bound",
+    "minimax_predictor",
+]
+
+
+@dataclass(frozen=True)
+class Case:
+    """One operating point. `conditions` carries everything the surrogate does NOT see --
+    `Gr`, wall heat flux, `L/D`, `Pr`, flow direction -- so that what was discarded from
+    the surrogate's inputs stays visible in the record."""
+
+    case_id: str
+    Re: float
+    Nu: float
+    conditions: Mapping[str, float | str] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.case_id:
+            raise ValueError("every case needs an id; anonymous cases cannot be traced")
+        if self.Re <= 0 or self.Nu <= 0:
+            raise ValueError(
+                f"{self.case_id}: Re and Nu must be positive for a log-space fit "
+                f"(got Re={self.Re}, Nu={self.Nu})"
+            )
+
+
+def ingest(cases: Iterable[Case]) -> tuple[Case, ...]:
+    """Validate a set of cases. Raises on duplicate ids."""
+    out = tuple(cases)
+    seen: dict[str, Case] = {}
+    for c in out:
+        if c.case_id in seen:
+            raise ValueError(
+                f"duplicate case id {c.case_id!r}. Ids must be unique, or cases are "
+                f"silently lost -- which is the failure this ingestion exists to prevent."
+            )
+        seen[c.case_id] = c
+    if not out:
+        raise ValueError("no cases")
+    return out
+
+
+def by_re(cases: Sequence[Case]) -> dict[float, list[Case]]:
+    groups: dict[float, list[Case]] = defaultdict(list)
+    for c in cases:
+        groups[c.Re].append(c)
+    return dict(groups)
+
+
+def same_re_spread(cases: Sequence[Case]) -> dict[float, float]:
+    """Observed relative spread in `Nu` at each repeated `Re`: `(max − min) / mean`.
+
+    **A description of the data, not a bound.** It is roughly twice the minimax floor,
+    and it is reported because it is the quantity a reader expects to see, not because
+    anything can be concluded from it. For a floor, use `minimax_relative_bound`.
+    """
+    out: dict[float, float] = {}
+    for re, group in by_re(cases).items():
+        if len(group) < 2:
+            continue
+        nus = [c.Nu for c in group]
+        out[re] = (max(nus) - min(nus)) / (sum(nus) / len(nus))
+    return out
+
+
+def minimax_predictor(nus: Sequence[float]) -> float:
+    """The single value minimising the worst RELATIVE error over `nus`.
+
+    Setting the two binding errors equal — the smallest and largest value — gives the
+    harmonic mean of the extremes. Intermediate values do not affect a minimax optimum.
+    """
+    lo, hi = min(nus), max(nus)
+    return 2.0 * lo * hi / (lo + hi)
+
+
+def minimax_relative_bound(cases: Sequence[Case]) -> dict[float, float]:
+    """For each repeated `Re`, the floor on the worst relative error a `Re`-only
+    surrogate can achieve there.
+
+        E* = (max − min) / (max + min),  attained at p* = 2·min·max / (min + max)
+
+    **The measure is named on purpose.** This bounds the worst relative error. A
+    different measure — RMS relative error, say — has a different optimum and a
+    different bound, so "the floor" is not well defined until the measure is fixed.
+
+    This is a floor under *this surrogate's chosen inputs*, not a claim that the
+    variation is irreducible physically.
+    """
+    out: dict[float, float] = {}
+    for re, group in by_re(cases).items():
+        if len(group) < 2:
+            continue
+        nus = [c.Nu for c in group]
+        lo, hi = min(nus), max(nus)
+        out[re] = (hi - lo) / (hi + lo)
+    return out
+
+
+@dataclass(frozen=True)
+class FitResult:
+    """`Nu = coefficient * Re**exponent`, fitted in log space over all cases."""
+
+    coefficient: float
+    exponent: float
+    n_cases: int
+    n_distinct_re: int
+    fitted_case_ids: tuple[str, ...]
+    #: Observed spread at repeated Re -- a description, not a bound.
+    same_re_spread: Mapping[float, float] = field(default_factory=dict)
+    #: Floor on the WORST RELATIVE error at repeated Re, for the minimax measure.
+    minimax_relative_bound: Mapping[float, float] = field(default_factory=dict)
+
+    def predict(self, re: float) -> float:
+        return self.coefficient * re**self.exponent
+
+
+@dataclass(frozen=True)
+class ResidualReport:
+    label: str
+    n: int
+    max_abs_rel: float | None = None
+    rms_rel: float | None = None
+    mean_signed_rel: float | None = None
+    per_case: tuple[tuple[str, float, float], ...] = field(default_factory=tuple)
+
+    def summary(self) -> str:
+        if not self.n:
+            return f"{self.label}: no cases"
+        return (
+            f"{self.label}: n={self.n}  max|rel|={self.max_abs_rel:.4%}  "
+            f"rms={self.rms_rel:.4%}  mean signed={self.mean_signed_rel:+.4%}"
+        )
+
+
+def fit_power_law(cases: Sequence[Case]) -> FitResult:
+    """Least-squares fit of `Nu = C Re^n` in log space over every case given.
+
+    Requires at least two DISTINCT `Re` values: many cases at one `Re` determine a
+    coefficient but not an exponent.
+    """
+    cases = ingest(cases)
+    groups = by_re(cases)
+    if len(groups) < 2:
+        raise ValueError(
+            f"a power-law fit needs at least 2 distinct Re values, got {len(groups)} "
+            f"across {len(cases)} case(s). The exponent is otherwise unidentifiable."
+        )
+    xs = [math.log(c.Re) for c in cases]
+    ys = [math.log(c.Nu) for c in cases]
+    n = len(xs)
+    mx, my = sum(xs) / n, sum(ys) / n
+    sxx = sum((x - mx) ** 2 for x in xs)
+    sxy = sum((x - mx) * (y - my) for x, y in zip(xs, ys))
+    exponent = sxy / sxx
+    return FitResult(
+        coefficient=math.exp(my - exponent * mx),
+        exponent=exponent,
+        n_cases=n,
+        n_distinct_re=len(groups),
+        fitted_case_ids=tuple(c.case_id for c in cases),
+        same_re_spread=same_re_spread(cases),
+        minimax_relative_bound=minimax_relative_bound(cases),
+    )
+
+
+def residuals(fit: FitResult, cases: Sequence[Case], label: str) -> ResidualReport:
+    if not cases:
+        return ResidualReport(label=label, n=0)
+    per = tuple(
+        (c.case_id, c.Re, (fit.predict(c.Re) - c.Nu) / c.Nu)
+        for c in sorted(cases, key=lambda q: (q.Re, q.case_id))
+    )
+    rels = [r for _, _, r in per]
+    return ResidualReport(
+        label=label,
+        n=len(rels),
+        max_abs_rel=max(abs(r) for r in rels),
+        rms_rel=math.sqrt(sum(r * r for r in rels) / len(rels)),
+        mean_signed_rel=sum(rels) / len(rels),
+        per_case=per,
+    )
+
+
+def split_by_re(
+    cases: Sequence[Case], holdout_re: Iterable[float]
+) -> tuple[tuple[Case, ...], tuple[Case, ...]]:
+    """Split so that every case sharing an `Re` lands on the same side.
+
+    The surrogate's only input is `Re`, so splitting within an `Re` would show the fit an
+    abscissa it is then scored on.
+    """
+    cases = ingest(cases)
+    hold = set(holdout_re)
+    unknown = hold - set(by_re(cases))
+    if unknown:
+        raise ValueError(f"held-out Re values not present in the cases: {sorted(unknown)}")
+    fit_side = tuple(c for c in cases if c.Re not in hold)
+    held_side = tuple(c for c in cases if c.Re in hold)
+    if not fit_side:
+        raise ValueError("every Re was held out; nothing left to fit")
+    return fit_side, held_side
+
+
+def fit_and_verify(
+    fit_cases: Sequence[Case], held_out_cases: Sequence[Case]
+) -> tuple[FitResult, ResidualReport, ResidualReport]:
+    """Fit on one set of cases, report residuals on both.
+
+    Raises if any `Re` appears on both sides -- the leak that makes a held-out residual a
+    fitted residual under another name, and that is silent when unchecked.
+    """
+    fit_cases, held_out_cases = ingest(fit_cases), tuple(held_out_cases)
+    if held_out_cases:
+        ingest(held_out_cases)
+    shared_ids = {c.case_id for c in fit_cases} & {c.case_id for c in held_out_cases}
+    if shared_ids:
+        raise ValueError(f"case ids appear on both sides: {sorted(shared_ids)}")
+    shared_re = set(by_re(fit_cases)) & set(by_re(held_out_cases))
+    if shared_re:
+        raise ValueError(
+            f"Re values appear on both sides: {sorted(shared_re)}. The surrogate sees "
+            f"only Re, so the held-out residual would be a fitted residual under another "
+            f"name. Use split_by_re() to divide the cases."
+        )
+    fit = fit_power_law(fit_cases)
+    return (
+        fit,
+        residuals(fit, fit_cases, "fitted"),
+        residuals(fit, held_out_cases, "held out"),
+    )

physmap/pipeline/__init__.py

@@ -0,0 +1,58 @@
+"""D3 detection + adjudication pipeline — the architecture refactor's
+detection-side surface.
+
+Module layout (renamed during R4 reorg — d3_ prefix dropped):
+  core                  (was d3_pipeline)          Pipeline + DetectorAdapter + protocols
+  aggregators           (was d3_aggregators)       Phase-1 aggregators (AnyFired, ...)
+  defeasible_aggregator (was d3_defeasible_aggregator) Phase-2 reasoner
+  detectors             (was d3_detectors)         Inner detector classes
+  validity_signal       (was d3_validity_signal)   Literature-distance detector
+  surrogate             (was d3_surrogate)         GP surrogate + thresholds
+  phase1_gate           (was d3_phase1_gate)       Phase-1 NACA gate runner
+  phase2_gate           (was d3_phase2_gate)       Phase-2 NACA gate runner
+  assessment_v06                                   Phase-1 -> v0.6 subgraph mapper
+  evidence_stage                                   Claim-centric JustificationStage
+
+Common entrypoints re-exported so consumers can write
+`from physmap.pipeline import Pipeline, AnyFired, ...`:
+"""
+
+from physmap.pipeline.aggregators import AnyFired, CorpusGated, WeightedVote
+from physmap.pipeline.core import (
+    Assessment,
+    Detector,
+    DetectorAdapter,
+    DetectorResult,
+    JustificationStage,
+    Pipeline,
+    Verdict,
+    make_closure_validity_adapter,
+    make_distance_adapter,
+    make_ensemble_variance_adapter,
+    make_gp_variance_adapter,
+)
+from physmap.pipeline.defeasible_aggregator import (
+    AdjudicationResult,
+    DefeasibleAdjudicator,
+    OffsetRule,
+)
+
+__all__ = [
+    "Assessment",
+    "Detector",
+    "DetectorAdapter",
+    "DetectorResult",
+    "JustificationStage",
+    "Pipeline",
+    "Verdict",
+    "AnyFired",
+    "CorpusGated",
+    "WeightedVote",
+    "AdjudicationResult",
+    "DefeasibleAdjudicator",
+    "OffsetRule",
+    "make_closure_validity_adapter",
+    "make_distance_adapter",
+    "make_ensemble_variance_adapter",
+    "make_gp_variance_adapter",
+]

physmap/pipeline/aggregators.py

@@ -0,0 +1,199 @@
+"""Phase-1 aggregators — Aggregator implementations for the D3 pipeline.
+
+Per the v0.2 architecture refactor (Part 2): the aggregator consumes ONLY
+decision signals and reduces them to a `Verdict`. Three Phase-1 aggregators:
+
+  * `AnyFired`    — union of detector fires. The locked ensemble metric
+                    (per [[physmap-ensemble-claim-definition]]):
+                        ensemble := steelman_baseline ∪ corpus_validity_signal
+                    success iff Pareto dominance (≥ everywhere, > somewhere).
+  * `CorpusGated` — corpus acts on points the baselines pass. Useful for
+                    diagnosing whether the corpus signal adds catches on
+                    operating points the baselines incorrectly stay quiet on.
+  * `WeightedVote` — sum of (fired × weight) > threshold. Phase-1 stub for
+                     future calibration experiments; not used in the locked
+                     ensemble metric.
+
+Phase-2 plugs in the DEFEASIBLE-ADJUDICATION reasoner (offset / agreement /
+threshold-distance modulation → Disposition). NOT built — gated on NACA result.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Iterable
+
+from physmap.pipeline.core import (
+    Aggregator,
+    DetectorResult,
+    SignalRole,
+    Verdict,
+)
+
+
+# ── AnyFired (the locked ensemble metric) ───────────────────────────────────
+
+@dataclass
+class AnyFired:
+    """Union of all decision-signal fires.
+
+    Reduces decision signals to fire iff at least one fired. The rationale
+    cites every detector that fired (so audit trails always name names);
+    on quiet, the rationale states all detectors were quiet.
+
+    This is the LOCKED ensemble metric per
+    `[[physmap-ensemble-claim-definition]]`:
+        ensemble := steelman_baseline ∪ corpus_validity_signal
+    The aggregator IS the ensemble — building the union as an Aggregator
+    makes the ensemble metric fall out of the pipeline naturally.
+    """
+    name: str = "any_fired"
+
+    def combine(self, decision_signals: dict[str, DetectorResult]) -> Verdict:
+        if not decision_signals:
+            raise ValueError(
+                "AnyFired.combine received no decision signals; nothing to "
+                "weigh. The pipeline should not call the aggregator on empty "
+                "input."
+            )
+        fired = [r for r in decision_signals.values() if r.fired]
+        if fired:
+            rationale = "; ".join(r.rationale for r in fired)
+            return Verdict(label="fire", rationale=rationale)
+        rationale = "all detectors quiet: " + "; ".join(
+            r.rationale for r in decision_signals.values()
+        )
+        return Verdict(label="quiet", rationale=rationale)
+
+
+# ── CorpusGated ─────────────────────────────────────────────────────────────
+
+@dataclass
+class CorpusGated:
+    """Fire iff (baselines all quiet) AND (corpus-validity fires).
+
+    Surfaces the "corpus catches what baselines miss" cell — the diagnostic
+    operating point where corpus's structural property (literature-only,
+    no training dependence) buys actual lift. If baselines fire on a point,
+    this aggregator stays quiet (already covered).
+
+    `baseline_names` lists which detectors count as "baselines"; the
+    remaining detector(s) act as the corpus arm. The corpus arm must
+    include AT LEAST one signal with `threshold is None` (the literature-
+    only validity detector) — otherwise CorpusGated degenerates into
+    "all baselines quiet" with no corpus voice.
+    """
+    baseline_names: tuple[str, ...]
+    corpus_names: tuple[str, ...] = ("closure_validity",)
+    name: str = "corpus_gated"
+
+    def combine(self, decision_signals: dict[str, DetectorResult]) -> Verdict:
+        missing_b = [n for n in self.baseline_names if n not in decision_signals]
+        missing_c = [n for n in self.corpus_names if n not in decision_signals]
+        if missing_b or missing_c:
+            raise KeyError(
+                f"CorpusGated.combine missing required detectors: "
+                f"baselines={missing_b}, corpus={missing_c}. "
+                f"Got detectors: {sorted(decision_signals.keys())}."
+            )
+        baseline_fired = any(decision_signals[n].fired for n in self.baseline_names)
+        corpus_fired = any(decision_signals[n].fired for n in self.corpus_names)
+
+        if (not baseline_fired) and corpus_fired:
+            corpus_rationales = "; ".join(
+                decision_signals[n].rationale for n in self.corpus_names
+                if decision_signals[n].fired
+            )
+            return Verdict(
+                label="fire",
+                rationale=(
+                    f"corpus_gated: baselines all quiet AND corpus fires -> "
+                    f"corpus catches what baselines missed. {corpus_rationales}"
+                ),
+            )
+        if baseline_fired and corpus_fired:
+            return Verdict(
+                label="quiet",
+                rationale=(
+                    "corpus_gated: both baselines and corpus fired; "
+                    "this aggregator surfaces ONLY the baselines-miss / "
+                    "corpus-catch operating point, so quiet here."
+                ),
+            )
+        if baseline_fired and not corpus_fired:
+            return Verdict(
+                label="quiet",
+                rationale=(
+                    "corpus_gated: baseline fired, corpus quiet. Not a "
+                    "corpus-catch point; verdict is quiet."
+                ),
+            )
+        return Verdict(
+            label="quiet",
+            rationale="corpus_gated: all detectors quiet.",
+        )
+
+
+# ── WeightedVote (Phase-1 stub for calibration experiments) ─────────────────
+
+@dataclass
+class WeightedVote:
+    """Fire iff sum(weight_i for detector_i in fired) >= vote_threshold.
+
+    A future calibration knob — not used in the locked ensemble metric.
+    `weights` maps detector_name -> weight; missing detectors default to
+    0.0 (silent abstention). `vote_threshold` is the sum-of-weights cutoff
+    (default 1.0; with unit weights this degenerates to AnyFired).
+
+    Phase-1 ships this as a stub so the strategy axis is real (Aggregator
+    is a true plug point), but NACA's gate metric is AnyFired.
+    """
+    weights: dict[str, float]
+    vote_threshold: float = 1.0
+    name: str = "weighted_vote"
+
+    def __post_init__(self) -> None:
+        if not self.weights:
+            raise ValueError(
+                "WeightedVote requires a non-empty weights dict; otherwise "
+                "no detector can contribute to the vote."
+            )
+        if any(w < 0 for w in self.weights.values()):
+            raise ValueError(
+                f"WeightedVote.weights cannot be negative: {self.weights}. "
+                f"A negative weight would mean 'fired -> reduce verdict'; "
+                f"that's not voting, that's defeasibility (Phase 2)."
+            )
+        if self.vote_threshold <= 0:
+            raise ValueError(
+                f"WeightedVote.vote_threshold must be > 0; got "
+                f"{self.vote_threshold}."
+            )
+
+    def combine(self, decision_signals: dict[str, DetectorResult]) -> Verdict:
+        total = 0.0
+        contributors: list[str] = []
+        for name, weight in self.weights.items():
+            r = decision_signals.get(name)
+            if r is not None and r.fired:
+                total += weight
+                contributors.append(f"{name}(w={weight:g})")
+        if total >= self.vote_threshold:
+            return Verdict(
+                label="fire",
+                rationale=(
+                    f"weighted_vote: total={total:g} >= threshold="
+                    f"{self.vote_threshold:g} from {contributors}"
+                ),
+            )
+        return Verdict(
+            label="quiet",
+            rationale=(
+                f"weighted_vote: total={total:g} < threshold="
+                f"{self.vote_threshold:g} "
+                f"(fired contributors: {contributors or '(none)'})"
+            ),
+        )
+
+
+__all__ = ["AnyFired", "CorpusGated", "WeightedVote"]