simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/process-window/process_window/inspect_part.py

@@ -0,0 +1,184 @@
+"""G0 geometry inspection. Free, local, and it predicts the answer before any simulation.
+
+The previous gating study's playbook makes this step 1 for a reason: bbox, volume, wall
+thickness and flow-length ratio already tell you whether a part is thermally marginal, and
+therefore whether a feasibility sweep will discriminate at all. On a thick-walled part it
+predicts an all-green sweep before you spend a single cloud run.
+
+Run:  python main.py inspect [--part a.stl b.stl ...]
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import numpy as np
+
+import cadmould
+from cadmould import mesh, tools
+from cadmould_geometry import stl
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def cavity_count(pts: np.ndarray, faces: np.ndarray) -> int:
+    """Number of separate bodies in the STL — i.e. how many cavities are actually modelled.
+
+    Reported because a briefing document said "4 of 32 cavities" while the geometry was a single
+    body, and that claim propagated into every caveat before anyone checked it. It costs
+    milliseconds, so there is no reason not to state it up front.
+    """
+    return stl.body_count(pts, faces)
+
+
+def inspect(stl_path: Path, *, session_open: bool = False) -> dict:
+    pts, faces = stl.read_stl(stl_path)
+    dims = pts.max(0) - pts.min(0)
+    volume_cm3 = stl.volume_mm3(pts, faces) / 1000.0
+    long_axis = int(np.argmax(dims))
+    n_bodies = cavity_count(pts, faces)
+
+    def _mesh_it():
+        meshed = (
+            mesh.Mesher(mesh.Mesh(pts.ravel(), faces.ravel()))
+            .with_surface_triangulation()
+            .with_thickness_and_w2w()
+            .build()
+        )
+        gates = [[float(p.x), float(p.y), float(p.z)] for p in tools.suggest_gates(meshed).points]
+        return meshed, gates
+
+    if session_open:
+        meshed, gates = _mesh_it()
+    else:
+        with cadmould.Session.user_based():
+            meshed, gates = _mesh_it()
+
+    # Flow length from the suggested gate to the furthest mesh node, along the surface's
+    # bounding geometry. A straight-line distance understates a wrapped path but is the right
+    # order of magnitude and needs no geodesic solver.
+    g = np.array(gates[0]) if gates else pts.mean(0)
+    flow_len = float(np.linalg.norm(pts - g, axis=1).max())
+
+    # Wall thickness: the mesher measures it, but the wheel exposes no getter, so estimate it
+    # from the closed-surface identity volume ~= area/2 * thickness for a thin shell.
+    area_mm2 = stl.surface_area_mm2(pts, faces)
+    open_edges = stl.open_edge_count(pts, faces)
+    t_est = 2.0 * volume_cm3 * 1000.0 / area_mm2 if area_mm2 else float("nan")
+
+    return {
+        "name": stl_path.stem,
+        "path": str(stl_path),
+        "bodies_in_stl": n_bodies,
+        "nodes": meshed.node_count(),
+        "elements": meshed.element_count(),
+        "volume_cm3": volume_cm3,
+        "area_mm2": area_mm2,
+        "bbox_mm": [round(float(d), 1) for d in dims],
+        "long_axis": "xyz"[long_axis],
+        "long_mm": float(dims[long_axis]),
+        "wall_est_mm": t_est,
+        "flow_length_mm": flow_len,
+        "L_over_t": flow_len / t_est if t_est else float("nan"),
+        "watertight": open_edges == 0,
+        "open_edges": open_edges,
+        "suggested_gate_mm": gates[0] if gates else None,
+        "n_suggested_gates": len(gates),
+    }
+
+
+def verdict(d: dict) -> list[str]:
+    """What the geometry alone says about whether a feasibility sweep will discriminate."""
+    out = []
+    lt = d["L_over_t"]
+    # PP fills to roughly L/t ~ 200-250 before pressure becomes the limit; well under that and
+    # a single gate is comfortable, which also means freeze-off is unlikely to bite.
+    if np.isfinite(lt):
+        if lt < 80:
+            out.append(
+                f"L/t = {lt:.0f}: very easy to fill (PP tolerates ~200+). A fill-phase "
+                "feasibility sweep will likely find the whole process window feasible."
+            )
+        elif lt < 150:
+            out.append(f"L/t = {lt:.0f}: moderate. Some of the process window should be marginal.")
+        else:
+            out.append(f"L/t = {lt:.0f}: demanding for PP. Expect a real infeasible region.")
+    if d["wall_est_mm"] < 1.0:
+        out.append(
+            f"mean wall ~{d['wall_est_mm']:.2f} mm: thin. Thin walls freeze fast, so "
+            "freeze-off is a live constraint and the no-flow gate should bite."
+        )
+    elif d["wall_est_mm"] > 2.5:
+        out.append(
+            f"mean wall ~{d['wall_est_mm']:.2f} mm: thick. Slow to freeze; the fill phase "
+            "will be forgiving and packing/cooling will dominate instead."
+        )
+    if not d["watertight"]:
+        out.append(
+            f"NOT watertight ({d['open_edges']} open edges) — the volume and wall estimate "
+            "are unreliable; check the STL before trusting derived flow rates."
+        )
+    return out
+
+
+DEFAULT_PART = ROOT / "sample" / "simple_plate.stl"
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description="G0 geometry inspection")
+    # Named, like every other template's geometry. It takes more than one because
+    # comparing candidate parts is the point of inspecting before a campaign; a single
+    # --part behaves exactly as it does elsewhere in the kit.
+    ap.add_argument(
+        "--part",
+        nargs="+",
+        type=Path,
+        default=[DEFAULT_PART],
+        help=f"STL geometry to inspect; pass several to compare them (default: {DEFAULT_PART.name} under sample/)",
+    )
+    args = ap.parse_args()
+
+    missing = [p for p in args.part if not p.is_file()]
+    if missing:
+        for p in missing:
+            print(f"geometry not found: {p}", file=sys.stderr)
+        print("Pass your own STL with --part, or put one back at sample/simple_plate.stl.", file=sys.stderr)
+        return 2
+
+    rows = []
+    with cadmould.Session.user_based():
+        for s in args.part:
+            rows.append(inspect(Path(s), session_open=True))
+
+    for d in rows:
+        print(f"\n=== {d['name']} ===")
+        print(
+            f"  bodies in STL   {d['bodies_in_stl']}"
+            + ("  <- cavities actually modelled; state this, do not inherit it" if d["bodies_in_stl"] >= 1 else "")
+        )
+        print(f"  mesh            {d['nodes']} nodes / {d['elements']} elements")
+        print(f"  bbox            {d['bbox_mm']} mm  (long axis {d['long_axis']}, {d['long_mm']:.0f} mm)")
+        print(f"  volume          {d['volume_cm3']:.2f} cm3   surface {d['area_mm2']:.0f} mm2")
+        print(f"  mean wall (est) {d['wall_est_mm']:.2f} mm")
+        print(f"  flow length     {d['flow_length_mm']:.0f} mm from suggested gate")
+        print(f"  L/t             {d['L_over_t']:.0f}")
+        print(f"  watertight      {d['watertight']}" + ("" if d["watertight"] else f"  ({d['open_edges']} open edges)"))
+        print(f"  suggested gate  {np.round(d['suggested_gate_mm'], 2).tolist()}  ({d['n_suggested_gates']} gate(s))")
+        for line in verdict(d):
+            print(f"  -> {line}")
+
+    if len(rows) > 1:
+        print("\n=== comparison ===")
+        print(f"  {'part':32s} {'vol cm3':>9s} {'long mm':>8s} {'wall mm':>8s} {'L/t':>6s}")
+        for d in rows:
+            print(
+                f"  {d['name'][:32]:32s} {d['volume_cm3']:9.2f} {d['long_mm']:8.0f} "
+                f"{d['wall_est_mm']:8.2f} {d['L_over_t']:6.0f}"
+            )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

simcon_toolkit/_kit/templates/process-window/process_window/kpis.py

@@ -0,0 +1,355 @@
+"""KPI extraction from one AI-solver filling result.
+
+Implements exactly the KPI set in the brief, and nothing else. Two design rules run
+through all of it:
+
+**Dimensionless by construction where possible.** Guardrail 1 forbids absolute thresholds,
+because the AI solver under-predicts absolute cavity pressure on multi-gate parts (~0.3x on
+8 gates) and we model 1 of 32 cavities with no runner. Rather than police that downstream, the
+are formed as *ratios* — normalised by a temperature difference the process itself defines
+(melt minus wall, or melt minus no-flow). A ratio has no scale to be wrong about, so it
+transfers across cavity counts in a way a temperature in Kelvin does not. `p80` is the one
+KPI that stays in physical units, and it is used for **ordering only**.
+
+**The feasibility gate is freeze-off, not fill completeness.** A short shot is a
+*consequence* of the melt reaching its no-flow temperature before the cavity fills. The
+no-flow margin is therefore the causal quantity, it is continuous (so boundary refinement has
+a gradient to follow), and it is immune to the known incomplete-fill bug in the AI model.
+Fill completeness is still measured on every run and reported — as a diagnostic.
+
+Weld detection is reused from the sibling gate-study template (`metrics`) rather than
+reimplemented: three plausible detectors were tried there and failed, and the working one
+(convergence of the flow-direction field) is calibrated and documented.
+"""
+
+from __future__ import annotations
+
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import h5py
+import numpy as np
+
+# Reused from templates/gate-study rather than vendored, so there is one source of truth for
+# the weld detector and its calibration. It is imported directly from the shared package.
+from cadmould_scoring import metrics as M
+
+from .units import UnitError, pressure_field_to_bar
+
+DOF_THRESH = 0.5  # cloud results: sharp 0->1 front; arrival = first crossing
+
+# Bump whenever a KPI definition changes. It is part of every run id, so a redefinition
+# invalidates existing records instead of silently reusing scores computed under the old
+# definition — a record is (inputs -> KPIs), so changing the KPIs changes what it means.
+#   v1: initial set
+#   v2: added the end-of-fill channel-closure reading of the no-flow margin (F16)
+KPI_VERSION = "v2"
+
+
+# ---------------------------------------------------------------------------
+# low-level readers
+# ---------------------------------------------------------------------------
+def _steps(f: h5py.File) -> list[str]:
+    return sorted(k for k in f if k.startswith("TimeStep_"))
+
+
+def _phi_axis(f: h5py.File, steps: list[str], reached_frac: np.ndarray) -> tuple[np.ndarray, str]:
+    """Injected-volume fraction phi per time step, and where it came from.
+
+    **Do not trust the solver's ``filling_level`` attribute.** On cloud AI results it is
+    written as a constant ``1.0`` at every step, which silently collapses the whole phi axis
+    onto a single point: `argmin(|phi - 0.8|)` then returns step 0, so `p80` becomes the
+    pressure before anything has filled and every switchover read-out is identical. Verified
+    on a 50-step production result. It is checked for variation here and rejected if flat.
+
+    The correct axis for a **constant-Q** run is ``t / t_end``: injected volume is Q*t, so
+    phi = Q*t/V = t/t_fill exactly. This is the same reparameterisation the filling-profile
+    POC is built on, and it inherits the same incompressible-melt caveat — injected volume is
+    equated with filled cavity volume, which is sub-percent during fill and worst as phi -> 1.
+    The AI solver only ever runs constant-Q, so the assumption always holds here.
+
+    Node-reached fraction is the last resort: it is a *geometric* proxy, not a volume
+    fraction, and on a part with uneven wall thickness the two differ materially.
+    """
+    lv = [f[s].attrs.get("filling_level") for s in steps]
+    if all(v is not None for v in lv):
+        arr = np.asarray([float(v) for v in lv], dtype=np.float64)
+        if float(np.ptp(arr)) > 0.01:
+            return arr, "filling_level"
+
+    times = np.asarray([float(f[s].attrs["Time"]) for s in steps], dtype=np.float64)
+    t_end = float(times[-1])
+    if t_end > 0:
+        return times / t_end, "time_over_t_end_constant_Q"
+    return reached_frac, "reached_fraction_proxy"
+
+
+def _core_temp_series(f: h5py.File, steps: list[str]) -> np.ndarray:
+    """(T, N) melt temperature at the wall's mid-plane (core layer), in K.
+
+    The core is the right layer for both thermal KPIs. Skin layers are quenched by the
+    mould by design, so they say more about the wall temperature than about the melt; the
+    core is what is still flowing, and it is the core freezing that stops the fill.
+    """
+    ds0 = f[steps[0]]["Temperature"]
+    core = ds0.shape[1] // 2
+    return np.stack([np.asarray(f[s]["Temperature"][:, core], dtype=np.float32) for s in steps])
+
+
+def _fill_state(f: h5py.File) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]:
+    """``(t_fill, arrival_step, reached, reached_frac_per_step)``.
+
+    Arrival is the first step at which ``Degree_of_filling`` crosses 0.5. Keying off
+    ``isfinite`` instead — as the old hand-authored files invite — makes every node appear
+    to arrive at t=0 and silently destroys every time-resolved KPI.
+    """
+    steps = _steps(f)
+    n = f[steps[0]]["Degree_of_filling"].shape[0]
+    t_fill = np.full(n, np.inf, np.float64)
+    arr_step = np.full(n, -1, np.int32)
+    reached = np.zeros(n, bool)
+    frac = np.zeros(len(steps), np.float64)
+    for i, s in enumerate(steps):
+        dof = np.asarray(f[s]["Degree_of_filling"][()], dtype=np.float32)
+        now = np.isfinite(dof) & (dof > DOF_THRESH)
+        newly = now & ~reached
+        t_fill[newly] = float(f[s].attrs["Time"])
+        arr_step[newly] = i
+        reached |= now
+        frac[i] = reached.mean()
+    return t_fill, arr_step, reached, frac
+
+
+def _max_pressure_bar_at(f: h5py.File, step_name: str) -> float:
+    ds = f[step_name]["Pressure"]
+    unit = ds.attrs.get("unit")
+    if unit is None:
+        raise UnitError(f"{step_name}/Pressure has no 'unit' attribute; refusing to infer Pa vs bar.")
+    pr = pressure_field_to_bar(np.asarray(ds[()], dtype=np.float64), unit)
+    fin = pr[np.isfinite(pr)]
+    return float(fin.max()) if fin.size else float("nan")
+
+
+# ---------------------------------------------------------------------------
+# result
+# ---------------------------------------------------------------------------
+@dataclass
+class Kpis:
+    # --- primary continuous KPI: ORDERING ONLY, never a threshold in bar ---
+    p80_bar: float
+    p80_phi_actual: float  # the phi actually available nearest 0.80
+
+    # --- feasibility: two readings of "distance to no-flow" ---
+    # at ARRIVAL: is the melt still molten when it gets there? Weak, because fountain flow keeps
+    # the front hot (F15) — retained for continuity and because it is the literal reading.
+    no_flow_margin: float  # (T_core,min_at_front - T_noflow)/(T_melt - T_noflow)
+    no_flow_margin_K: float  # same in K, for the engineer's intuition
+    # at END OF FILL: did the flow channel stay open? This is the reading that discriminates
+    # (F16). A robust 5th percentile, not the minimum: the minimum is dominated by the mesher's
+    # degenerate sub-0.05 mm slivers and swings 90 K on a handful of nodes.
+    no_flow_margin_end_K: float  # p5(T_core at end of fill) - T_noflow
+    frozen_fraction_end: float  # share of filled nodes with core below no-flow (DIAGNOSTIC)
+
+    # --- fill-phase quality proxy ---
+    weld_front_temp_K: float
+    weld_front_temp_ratio: float  # (T_weld - T_wall)/(T_melt - T_wall)
+    n_weld_clusters: int
+
+    # --- warpage RISK flag (dimensionless) ---
+    hotspot: float  # in-plane core-temperature spread / (T_melt - T_wall)
+
+    # --- diagnostics, NOT gates ---
+    fill_residual: float  # unfilled node fraction at end of fill (known bug)
+    race_anomaly_tail: float  # ANOMALY DETECTOR ONLY - must never screen
+
+    # --- switchover read-out (free: state AT switchover, not effect OF switching) ---
+    switchover: dict = field(default_factory=dict)
+
+    # --- provenance / honesty flags ---
+    phi_axis_source: str = "filling_level"
+    flags: list = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        d = dict(self.__dict__)
+        for k, v in d.items():
+            if isinstance(v, float):
+                d[k] = None if not np.isfinite(v) else round(v, 6)
+        return d
+
+    def summary(self) -> str:
+        return (
+            f"p80={self.p80_bar:7.1f}bar(phi{self.p80_phi_actual:.2f})  "
+            f"nfEnd={self.no_flow_margin_end_K:+7.1f}K(froz={self.frozen_fraction_end:.3f})  "
+            f"noflow={self.no_flow_margin:+.3f}({self.no_flow_margin_K:+.1f}K)  "
+            f"weldT={self.weld_front_temp_K:6.1f}K(r={self.weld_front_temp_ratio:.3f},"
+            f"n={self.n_weld_clusters})  hotspot={self.hotspot:.4f}  "
+            f"resid={self.fill_residual:.3f}"
+        )
+
+
+# ---------------------------------------------------------------------------
+def extract(
+    path: str | Path,
+    *,
+    melt_K: float,
+    wall_K: float,
+    no_flow_K: float | None = None,
+    switchover_phi: tuple[float, ...] = (0.90, 0.95, 0.98, 0.99),
+    long_axis: int = 1,
+    knn_k: int = 10,
+) -> Kpis:
+    """Compute the full KPI set from one result file.
+
+    ``melt_K`` / ``wall_K`` are the *requested* process values (the result file omits the
+    ``/input`` group), and are what the ratio KPIs normalise against — so the
+    normalisation reflects the process point we asked for, not one inferred from the field.
+    """
+    path = Path(path)
+    flags: list[str] = []
+
+    with h5py.File(path, "r") as f:
+        steps = _steps(f)
+        if not steps:
+            raise ValueError(f"{path.name}: no TimeStep_* groups")
+        coords = M.read_coords(f)
+        t_fill, arr_step, reached, reached_frac = _fill_state(f)
+        phi, phi_src = _phi_axis(f, steps, reached_frac)
+        if phi_src == "reached_fraction_proxy":
+            flags.append("phi_axis_is_geometric_proxy")
+        if phi_src == "time_over_t_end_constant_Q":
+            flags.append("filling_level_attr_flat_ignored")
+        core_T = _core_temp_series(f, steps)  # (T, N) K
+
+        # --- p80: primary KPI, at the step nearest 80 % injected volume -------
+        i80 = int(np.argmin(np.abs(phi - 0.80)))
+        p80 = _max_pressure_bar_at(f, steps[i80])
+        p80_phi = float(phi[i80])
+        if abs(p80_phi - 0.80) > 0.05:
+            flags.append(f"p80_phi_off_by_{abs(p80_phi - 0.80):.3f}")
+
+        # --- switchover read-out ---------------------------------------------
+        switch: dict = {}
+        for ps in switchover_phi:
+            i = int(np.argmin(np.abs(phi - ps)))
+            filled_now = (arr_step >= 0) & (arr_step <= i)
+            # Two DIFFERENT temperatures, kept apart on purpose. Reporting only the minimum
+            # over all filled nodes is actively misleading: it is dominated by the
+            # earliest-filled material near the gate, which has been cooling the longest and
+            # is legitimately below the no-flow temperature while the part is still filling
+            # perfectly well. Placed next to the no-flow margin it reads as infeasibility
+            # when nothing is wrong.
+            #   front_*  = melt that has just arrived -> can the rest of the cavity still be
+            #              filled? This is the freeze-off-relevant number at switchover.
+            #   coldest_*= coldest point anywhere already filled -> gate/skin freeze proxy.
+            front = arr_step == i
+            switch[f"phi_{ps:.2f}"] = {
+                "phi_actual": float(phi[i]),
+                "p_max_bar": _max_pressure_bar_at(f, steps[i]),
+                "unfilled_fraction": float(1.0 - filled_now.mean()),
+                "front_core_T_min_K": (float(np.nanmin(core_T[i][front])) if front.any() else None),
+                "coldest_filled_core_T_K": (float(np.nanmin(core_T[i][filled_now])) if filled_now.any() else None),
+            }
+
+        # --- weld detection (reused, calibrated prior art) --------------------
+        knn = M.knn_indices(coords, k=knn_k)
+        score, _angle, clusters = M.detect_welds(
+            coords, t_fill, knn, np.asarray([float(f[s].attrs["Time"]) for s in steps]), long_axis=long_axis
+        )
+        weld_mask = M.cluster_member_mask(coords, score, knn)
+
+    # --- weld-front temperature: core temp at the moment the fronts met ------
+    if weld_mask.any():
+        idx = np.where(weld_mask & (arr_step >= 0))[0]
+        weld_T = float(np.nanmean(core_T[arr_step[idx], idx])) if idx.size else float("nan")
+    else:
+        weld_T = float("nan")
+        flags.append("no_weld_clusters_detected")
+
+    dT = melt_K - wall_K
+    if dT <= 0:
+        raise UnitError(f"melt ({melt_K} K) must exceed wall ({wall_K} K)")
+    weld_ratio = (weld_T - wall_K) / dT if np.isfinite(weld_T) else float("nan")
+
+    # --- no-flow margin: coldest core melt on the front, when it arrived -----
+    filled = arr_step >= 0
+    T_at_arrival = core_T[arr_step[filled], np.where(filled)[0]]
+    T_at_arrival = T_at_arrival[np.isfinite(T_at_arrival)]
+
+    # Sanity check on the temperature field's scale. The core cannot sit far above the
+    # melt the solver was asked for: shear heating adds some, but tens of K in the *mean*
+    # is not shear heating, it is a scale or offset problem — and a temperature field that
+    # is wrong by a constant makes the weld-front and no-flow KPIs quietly meaningless
+    # while still producing plausible-looking numbers. Flagged loudly, not swallowed.
+    if T_at_arrival.size:
+        excess = float(np.median(T_at_arrival)) - melt_K
+        if excess > 30.0:
+            flags.append(f"core_T_median_{excess:+.0f}K_vs_requested_melt__VERIFY_FIELD_SCALE")
+
+    # End-of-fill core temperature over filled nodes: the channel-closure reading.
+    end_core = core_T[-1][filled]
+    end_core = end_core[np.isfinite(end_core)]
+
+    if no_flow_K is None:
+        nf_ratio = nf_K = nf_end_K = frozen_frac = float("nan")
+        flags.append("no_flow_temp_unavailable")
+    else:
+        T_min = float(np.nanmin(T_at_arrival)) if T_at_arrival.size else float("nan")
+        nf_K = T_min - no_flow_K
+        span = melt_K - no_flow_K
+        nf_ratio = nf_K / span if span > 0 else float("nan")
+        if end_core.size:
+            nf_end_K = float(np.percentile(end_core, 5)) - no_flow_K
+            frozen_frac = float((end_core < no_flow_K).mean())
+        else:
+            nf_end_K = frozen_frac = float("nan")
+
+    # --- hotspot / thermal heterogeneity at end of fill ----------------------
+    # In-plane spread of core temperature at the start of packing is what drives
+    # DIFFERENTIAL shrinkage, and differential shrinkage is what warps a part. Uniformly
+    # hot is not a warpage risk; unevenly hot is. Normalised by (melt - wall) so it is a
+    # ratio: no absolute scale to be wrong about, and it transfers across cavity counts.
+    # This is the one KPI the brief left open. Robust percentile spread (p95-p05) rather
+    # than max-min, because the field is float16 and a single quantisation outlier at the
+    # gate singularity would otherwise set the metric.
+    endT = core_T[-1][filled]
+    endT = endT[np.isfinite(endT)]
+    hotspot = float(np.percentile(endT, 95) - np.percentile(endT, 5)) / dT if endT.size else float("nan")
+
+    # --- diagnostics ---------------------------------------------------------
+    residual = float(1.0 - reached.mean())
+    bal = M.fill_balance(t_fill, reached)
+    race = float(bal["tail_fraction"])
+
+    return Kpis(
+        p80_bar=p80,
+        p80_phi_actual=p80_phi,
+        no_flow_margin=nf_ratio,
+        no_flow_margin_K=nf_K,
+        no_flow_margin_end_K=nf_end_K,
+        frozen_fraction_end=frozen_frac,
+        weld_front_temp_K=weld_T,
+        weld_front_temp_ratio=weld_ratio,
+        n_weld_clusters=len(clusters),
+        hotspot=hotspot,
+        fill_residual=residual,
+        race_anomaly_tail=race,
+        switchover=switch,
+        phi_axis_source=phi_src,
+        flags=flags,
+    )
+
+
+if __name__ == "__main__":
+    import json
+
+    # A diagnostic, not a campaign stage: score one result file from the shell.
+    if len(sys.argv) < 2:
+        raise SystemExit("usage: python -m process_window.kpis <result.h5> [melt_K] [wall_K] [no_flow_K]")
+    p = sys.argv[1]
+    melt = float(sys.argv[2]) if len(sys.argv) > 2 else 513.15
+    wall = float(sys.argv[3]) if len(sys.argv) > 3 else 313.15
+    nf = float(sys.argv[4]) if len(sys.argv) > 4 else None
+    k = extract(p, melt_K=melt, wall_K=wall, no_flow_K=nf)
+    print(k.summary())
+    print(json.dumps(k.as_dict(), indent=2, default=str))