simcon-toolkit 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,312 @@
+"""Build a ready-to-run Campaign from a config file.
+
+Everything that happens once per campaign: read the config and material card, mesh the part,
+pick the gate, authenticate, resolve the material, create the cloud project, upload the
+geometry. Cached in `cache/runs/<part-key>/campaign_state.json` so re-running any stage does not re-mesh or
+re-upload — the geometry_id is part of every run id, so a fresh upload would invalidate every
+existing result and silently force a full re-run.
+
+One licence session wraps meshing and the material card. Cloud calls here go over REST (the
+project/group/notes surface the SDK does not wrap), so they need no session.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import numpy as np
+import yaml
+
+import cadmould
+from cadmould import (
+    material as _cm_material,
+    mesh,
+    tools,
+)
+from cadmould_cloud import auth as cloud_auth
+from cadmould_cloud.client import PlatformAPI
+from cadmould_geometry import stl
+
+from . import material_card
+from .harness import Campaign
+from .identity import find_existing_campaign, foreign_campaigns, part_key, slug
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+def _resolve(_unused: Path, rel: str) -> Path:
+    """Resolve a config path relative to the PROJECT ROOT, not the config file's folder.
+
+    Config paths read as if written from the project root, which is
+    how anyone editing the yaml naturally thinks about them; resolving against `configs/`
+    instead silently pointed at a path inside `configs/`.
+    """
+    p = Path(rel)
+    return p if p.is_absolute() else (ROOT / rel).resolve()
+
+
+def load_config(path: str | Path) -> dict:
+    path = Path(path)
+    cfg = yaml.safe_load(path.read_text())
+    cfg["_dir"] = path.parent
+    return cfg
+
+
+def campaign_dir_name(cfg: dict) -> str:
+    """The folder this campaign lives in: the part's identity, scale included.
+
+    Falls back to a saved campaign of the same name when the geometry is gone, so a
+    dossier can still be re-emitted from a kept `cache/` on a machine that no longer
+    holds the part. Ambiguity is refused rather than guessed.
+    """
+    part = _resolve(cfg["_dir"], cfg["part"]["stl"])
+    scale = float(cfg["part"].get("scale", 1.0))
+    if not part.exists():
+        base = Path(cfg["storage"]["runs_dir"])
+        runs_root = base if base.is_absolute() else ROOT / base
+        found = find_existing_campaign(runs_root, part)
+        if found is not None:
+            return found.name
+    return part_key(part, scale)
+
+
+def resolve_config(arg: str | None) -> Path:
+    """The config a stage runs against, refusing a default that could mean two things.
+
+    The fallback to the bundled sample stays — it is what makes a first run one command.
+    It is withdrawn only once another campaign exists, because from then on a bare stage
+    could plausibly mean either, and choosing wrong is silent: it reads and writes under
+    the sample's key while looking like a continuation of the engineer's own work.
+    """
+    default = ROOT / "configs" / "simple-plate.yaml"
+    if arg:
+        return Path(arg)
+
+    cfg = load_config(default)
+    base = Path(cfg["storage"]["runs_dir"])
+    runs_root = base if base.is_absolute() else ROOT / base
+    try:
+        default_key: str | None = campaign_dir_name(cfg)
+    except SystemExit:
+        default_key = None
+
+    others = foreign_campaigns(runs_root, default_key)
+    if others:
+        listed = "\n  ".join(others)
+        raise SystemExit(
+            "no config given, and more than one campaign is on disk:\n  "
+            f"{listed}\n"
+            f"Defaulting to {default.name} here would read and write the bundled sample's "
+            "campaign while looking like it continued yours. Name the config you mean, "
+            "for example:  python main.py <step> configs/your-part.yaml"
+        )
+    return default
+
+
+def runs_dir_for(cfg: dict) -> Path:
+    """Per-part runs directory, so two campaigns cannot clobber each other's state.
+
+    The geometry_id is baked into every run id, so a shared state file would let one part's
+    upload silently invalidate the other's entire run history.
+    """
+    base = cfg["storage"]["runs_dir"]
+    p = Path(base)
+    p = p if p.is_absolute() else ROOT / base
+    return p / campaign_dir_name(cfg)
+
+
+def stage_dir_for(cfg: dict) -> Path:
+    """Where each stage records what the next one reads.
+
+    Under cache/, never under output/: these are recorded decisions, and a customer
+    clearing a folder called output would take them with it. The campaign would then
+    re-derive a floor or a boundary rather than reuse the one it agreed.
+    """
+    d = runs_dir_for(cfg) / "stages"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def dossier_dir_for(cfg: dict) -> Path:
+    """Where the answer lands: doe_spec.yaml and dossier.md, and nothing else.
+
+    Under output/, because it is the customer's to keep, move or delete.
+    """
+    d = ROOT / "output" / campaign_dir_name(cfg)
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+def build(config_path: str | Path, *, logger=print) -> tuple[Campaign, dict]:
+    cfg = load_config(config_path)
+    cfg_dir = cfg["_dir"]
+    runs_dir = runs_dir_for(cfg)
+    runs_dir.mkdir(parents=True, exist_ok=True)
+    state_path = runs_dir / "campaign_state.json"
+    state = json.loads(state_path.read_text()) if state_path.exists() else {}
+
+    stl_path = _resolve(cfg_dir, cfg["part"]["stl"])
+    plb = _resolve(cfg_dir, cfg["material"]["plb"])
+
+    # ---- local: material card + mesh + gate (one session, not nested) --------
+    with cadmould.Session.user_based():
+        card = material_card.load(plb, session_open=True)
+        logger(card.describe())
+
+        scale = float(cfg["part"].get("scale", 1.0))
+        cfex = runs_dir / "_mesh" / f"{part_key(stl_path, scale)}.cfex"
+        raw_pts, faces = stl.read_stl(stl_path)
+        pts = raw_pts * scale
+        volume_cm3 = stl.volume_mm3(raw_pts, faces) / 1000.0 * scale**3
+        if not cfex.exists():
+            meshed = (
+                mesh.Mesher(mesh.Mesh(pts.ravel(), faces.ravel()))
+                .with_surface_triangulation()
+                .with_thickness_and_w2w()
+                .build()
+            )
+            cfex.parent.mkdir(parents=True, exist_ok=True)
+            mesh.io.CfexWriter().save(meshed, str(cfex))
+            # The mesh was rebuilt, so whatever the cloud holds is not this file. The
+            # content key makes that unlikely, but a state file can outlive its mesh and
+            # a stale id is invisible: every run would score the wrong geometry.
+            #
+            # Written to disk here rather than with the rest of the state at the end: if
+            # the upload below fails, the old id must not survive to be reused on the
+            # next run, when the mesh will exist and nothing will re-invalidate it.
+            state["geometry_id"] = None
+            state_path.parent.mkdir(parents=True, exist_ok=True)
+            state_path.write_text(json.dumps(state, indent=2))
+        else:
+            meshed = mesh.io.CfexReader().load(str(cfex))[0]
+
+        suggested = tools.suggest_gates(meshed)
+        if cfg["gates"].get("positions_mm"):
+            gates = [[float(v) for v in g] for g in cfg["gates"]["positions_mm"]]
+        else:
+            gates = [[float(p.x), float(p.y), float(p.z)] for p in suggested.points]
+
+        # Nominal flow from the SDK's own physics, not a guessed fill time. suggest_fill_profile
+        # accounts for wall thickness and the material's rheology/thermal data, so the box lands
+        # where the process actually is. An arbitrary "fill in 1 s" default was 3.5x too slow on
+        # a 0.71 mm-wall part whose wall freezes in ~0.13 s — it would have put the entire box in
+        # freeze-off. It is also the better answer for minimal user input: nothing to set.
+        raw_material = _cm_material.io.PlbReader().load(str(plb))
+        fill_profile = tools.suggest_fill_profile(meshed, raw_material, suggested)
+        sdk_fill_time_s = float(tools.estimate_fill_time(meshed, fill_profile))
+        sdk_cooling_time_s = float(tools.suggest_cooling_time(meshed, raw_material))
+
+    dims = pts.max(0) - pts.min(0)
+    long_axis = int(np.argmax(dims))
+    logger(
+        f"  mesh {meshed.node_count()} nodes / {meshed.element_count()} elems; "
+        f"volume {volume_cm3:.2f} cm3; long axis {'xyz'[long_axis]}"
+    )
+    logger(f"  gate(s) {np.round(gates, 2).tolist()}")
+
+    # ---- cloud: auth, material, project, geometry ---------------------------
+    cc = cfg["cloud"]
+    api = PlatformAPI(cc["rest_base_url"], cloud_auth.get_access_token(), logger=lambda *_: None)
+    mat = api.find_material(cfg["material"]["catalogue_name"])
+    material_id = mat["material_id"]
+    ver = api.get_material_version(mat["latest_version"]["version_id"])
+    d_melt = abs(float(ver["suggested_mass_temp_K"]) - card.melt.rec_K)
+    logger(
+        f"  material {mat['trade_name']} id={material_id}; catalogue vs card melt "
+        f"{'AGREES' if d_melt < 1.0 else f'DIFFERS by {d_melt:.2f} K'}"
+    )
+
+    project = api.get_or_create_project(cc["project"], notes="Frontloaded DOE POC (frontloaded DOE, the trade show)")
+    project_id = project["id"]
+
+    geometry_id = state.get("geometry_id")
+    if not geometry_id or state.get("cfex_name") != cfex.name:
+        up = api.request_geometry_upload(cfex.name, description=f"DOE POC: {stl_path.name}")
+        api.put_cfex(up["presigned_put_url"], cfex)
+        geometry_id = up["geometry_id"]
+        logger(f"  uploaded geometry -> {geometry_id}")
+    else:
+        logger(f"  reusing geometry {geometry_id} (cached; a new upload would invalidate every existing run id)")
+
+    state.update(
+        {
+            "project_id": project_id,
+            "geometry_id": geometry_id,
+            "material_id": material_id,
+            "cfex_name": cfex.name,
+            "volume_cm3": volume_cm3,
+            "gates_mm": gates,
+            "long_axis": long_axis,
+        }
+    )
+    state_path.write_text(json.dumps(state, indent=2))
+
+    sv = cfg["solver"]
+    campaign = Campaign(
+        api=api,
+        project_id=project_id,
+        geometry_id=geometry_id,
+        material_id=material_id,
+        volume_cm3=volume_cm3,
+        card=card,
+        long_axis=long_axis,
+        gates_mm=gates,
+        runs_dir=runs_dir,
+        model_version=cc["model_version"],
+        num_timesteps=int(sv["num_timesteps"]),
+        htc_W_m2K=float(sv["htc_W_m2K"]),
+        switchover_phi=tuple(cfg["variables"]["switchover_readout_phi"]),
+        logger=logger,
+    )
+
+    fv = cfg["variables"]["flow"]
+    nominal_flow = fv.get("nominal_cm3_s")
+    if nominal_flow is None:
+        if fv.get("from") == "sdk_suggestion" or fv.get("target_fill_time_s") is None:
+            nominal_flow = round(volume_cm3 / sdk_fill_time_s, 4)
+            nominal_basis = f"sdk_suggest_fill_profile (fill {sdk_fill_time_s:.4f} s)"
+        else:
+            nominal_flow = round(volume_cm3 / float(fv["target_fill_time_s"]), 4)
+            nominal_basis = f"target_fill_time_s={fv['target_fill_time_s']}"
+    else:
+        nominal_basis = "pinned in config"
+    logger(f"  SDK suggests fill {sdk_fill_time_s:.4f} s, cooling {sdk_cooling_time_s:.2f} s")
+    logger(f"  nominal flow {nominal_flow:.4f} cm3/s  ({nominal_basis})")
+    box = material_card.wide_box(
+        card, nominal_flow_cm3_s=float(nominal_flow), flow_rel_span=float(cfg["variables"]["flow"]["rel_span"])
+    )
+
+    info = {
+        "cfg": cfg,
+        "card": card,
+        "box": box,
+        "nominal_flow_cm3_s": float(nominal_flow),
+        "nominal_flow_basis": nominal_basis,
+        "sdk_fill_time_s": sdk_fill_time_s,
+        "sdk_cooling_time_s": sdk_cooling_time_s,
+        "volume_cm3": volume_cm3,
+        "gates_mm": gates,
+        "long_axis": long_axis,
+        "cfex": cfex,
+        "runs_dir": runs_dir,
+        "project_id": project_id,
+        "geometry_id": geometry_id,
+        "material_id": material_id,
+        "api": api,
+        "part_name": cfg["part"]["name"],
+        "part_slug": slug(cfg["part"]["name"]),
+        "stage_dir": stage_dir_for(cfg),
+    }
+    return campaign, info
+
+
+if __name__ == "__main__":
+    cp = sys.argv[1] if len(sys.argv) > 1 else str(ROOT / "configs" / "simple-plate.yaml")
+    c, info = build(cp)
+    print("\nwide box:")
+    for k in ("melt_C", "wall_C", "flow_cm3_s"):
+        lo, hi = info["box"][k]
+        print(f"  {k:12s} {lo:8.2f} .. {hi:8.2f}   basis={info['box']['basis'][k]}")
+    info["api"].close()

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

@@ -0,0 +1,201 @@
+"""Cheap surrogate + variable ranking, on numpy alone.
+
+No scipy/sklearn in this venv, so both pieces are implemented directly. Neither is exotic:
+
+**Surrogate — Gaussian-process / RBF interpolation** with a Gaussian kernel on inputs normalised
+to the unit box. Chosen over a quadratic response surface because the feasibility boundary is
+expected to be a curved surface in a 3-D box, and a quadratic cannot bend twice; and over a
+neural surrogate because with ~1 000 points and 3 inputs a kernel method is both better
+conditioned and honest about where it has no data — which G3 needs, since it places new points
+where the surrogate is *uncertain*.
+
+**Ranking — variance-based effect shares (Sobol indices)** estimated by Monte Carlo *on the
+surrogate*, which is free. First-order index S_i is the share of output variance explained by
+moving variable i alone; total index S_i^T adds everything variable i participates in through
+interactions. Reported as normalised shares, which is what the brief asks for.
+
+The nugget is not a nuisance parameter here — it is set from the **derived noise floor**, because
+we know the outputs are quantised on a floating-point lattice (F8). Fitting through quantisation
+noise is what makes an interpolator ring.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+
+
+def normalise(X: np.ndarray, box: np.ndarray) -> np.ndarray:
+    """Map (n, d) physical points into the unit box, so one length scale is meaningful."""
+    lo, hi = box[:, 0], box[:, 1]
+    return (X - lo) / np.maximum(hi - lo, 1e-12)
+
+
+@dataclass
+class Surrogate:
+    """Gaussian RBF interpolator with a noise nugget and a leave-one-out error estimate."""
+
+    Xn: np.ndarray  # (n, d) normalised inputs
+    y: np.ndarray  # (n,)
+    box: np.ndarray  # (d, 2) physical bounds
+    length: float
+    nugget: float
+    _w: np.ndarray
+    _K: np.ndarray
+    _Kinv: np.ndarray
+    y_mean: float
+    y_scale: float
+
+    # -- prediction ---------------------------------------------------------
+    def _kern(self, A: np.ndarray, B: np.ndarray) -> np.ndarray:
+        d2 = ((A[:, None, :] - B[None, :, :]) ** 2).sum(-1)
+        return np.exp(-0.5 * d2 / self.length**2)
+
+    def predict(self, X: np.ndarray) -> np.ndarray:
+        Xn = normalise(np.atleast_2d(X), self.box)
+        return self._kern(Xn, self.Xn) @ self._w * self.y_scale + self.y_mean
+
+    def predict_unit(self, Xn: np.ndarray) -> np.ndarray:
+        """Predict from already-normalised points (avoids re-normalising in hot loops)."""
+        return self._kern(np.atleast_2d(Xn), self.Xn) @ self._w * self.y_scale + self.y_mean
+
+    def variance_unit(self, Xn: np.ndarray) -> np.ndarray:
+        """Posterior variance, in normalised output units. Zero at the data, large away from it.
+
+        This is what G3's adaptive sampling steers on: place runs where the surrogate does not
+        know the answer *and* the boundary is near.
+        """
+        Xn = np.atleast_2d(Xn)
+        Ks = self._kern(Xn, self.Xn)
+        v = 1.0 + self.nugget - np.einsum("ij,jk,ik->i", Ks, self._Kinv, Ks)
+        return np.maximum(v, 0.0)
+
+    # -- diagnostics --------------------------------------------------------
+    def loo_error(self) -> dict:
+        """Leave-one-out error without refitting, via the inverse-matrix identity.
+
+        e_i = (K^-1 y)_i / (K^-1)_ii — exact for a fixed kernel, so it costs nothing and
+        cannot be fudged. The filling-profile POC used the same check.
+        """
+        a = self._Kinv @ ((self.y - self.y_mean) / self.y_scale)
+        d = np.diag(self._Kinv)
+        e = (a / d) * self.y_scale
+        rng = float(self.y.max() - self.y.min()) or 1.0
+        return {
+            "mae": float(np.abs(e).mean()),
+            "rmse": float(np.sqrt((e**2).mean())),
+            "max": float(np.abs(e).max()),
+            "nrmse_range": float(np.sqrt((e**2).mean()) / rng),
+        }
+
+
+def fit(
+    X: np.ndarray, y: np.ndarray, box: np.ndarray, *, noise_floor: float | None = None, length: float | None = None
+) -> Surrogate:
+    """Fit the surrogate. ``noise_floor`` is the DERIVED per-KPI floor, in y units."""
+    X = np.atleast_2d(np.asarray(X, float))
+    y = np.asarray(y, float).ravel()
+    box = np.asarray(box, float)
+    Xn = normalise(X, box)
+
+    y_mean = float(y.mean())
+    y_scale = float(y.std()) or 1.0
+    yz = (y - y_mean) / y_scale
+
+    if length is None:
+        # A length scale that spans a few nearest-neighbour distances: long enough to smooth
+        # the quantisation lattice, short enough to resolve a curved boundary.
+        n, d = Xn.shape
+        length = float(np.clip(2.0 * n ** (-1.0 / d), 0.06, 0.5))
+
+    # The nugget encodes the quantisation floor. Without it the interpolator would chase a
+    # lattice step as if it were signal (F8: p80 moves in 0.06 bar increments).
+    nug = ((noise_floor / y_scale) ** 2 if noise_floor else 1e-8) + 1e-10
+
+    s = Surrogate(
+        Xn=Xn,
+        y=y,
+        box=box,
+        length=length,
+        nugget=float(nug),
+        _w=np.zeros(len(y)),
+        _K=np.zeros((len(y), len(y))),
+        _Kinv=np.zeros((len(y), len(y))),
+        y_mean=y_mean,
+        y_scale=y_scale,
+    )
+    K = s._kern(Xn, Xn) + np.eye(len(y)) * s.nugget
+    # Cholesky with escalating jitter: a Gaussian kernel on ~1 000 points is often numerically
+    # singular, and failing loudly here beats returning a silently garbage fit.
+    jitter = 0.0
+    for _ in range(8):
+        try:
+            np.linalg.cholesky(K + np.eye(len(y)) * jitter)
+            break
+        except np.linalg.LinAlgError:
+            jitter = max(jitter * 10, 1e-10)
+    else:
+        raise np.linalg.LinAlgError("surrogate kernel not positive definite even with jitter")
+    Kj = K + np.eye(len(y)) * jitter
+    w = np.linalg.solve(Kj, yz)
+    object.__setattr__(s, "_w", w)
+    object.__setattr__(s, "_K", Kj)
+    object.__setattr__(s, "_Kinv", np.linalg.inv(Kj))
+    return s
+
+
+def sobol_indices(model, dim: int, *, n: int = 4096, seed: int = 0) -> dict:
+    """First-order and total effect shares by Saltelli's estimator, on the surrogate.
+
+    S_i  : variance explained by variable i alone.
+    S_i^T: variance i is involved in at all, including interactions.
+    A large gap between them means the variable matters mainly *in combination* — which is
+    exactly the case where ranking it low and fixing it would be wrong.
+    """
+    rng = np.random.default_rng(seed)
+    A = rng.random((n, dim))
+    B = rng.random((n, dim))
+    yA = model(A)
+    yB = model(B)
+    varY = float(np.var(np.concatenate([yA, yB])))
+    if varY <= 0:
+        return {"var": 0.0, "S1": [0.0] * dim, "ST": [0.0] * dim}
+
+    S1, ST = [], []
+    for i in range(dim):
+        AB = A.copy()
+        AB[:, i] = B[:, i]  # i from B, rest from A
+        yAB = model(AB)
+        # Saltelli 2010 estimators, which behave far better at modest n than the raw forms.
+        S1.append(float(np.mean(yB * (yAB - yA)) / varY))
+        ST.append(float(np.mean((yA - yAB) ** 2) / (2.0 * varY)))
+    return {"var": varY, "S1": S1, "ST": ST}
+
+
+def effect_shares(surr: Surrogate, *, n: int = 4096, seed: int = 0) -> dict:
+    """Normalised effect shares plus the raw indices, ready for the dossier."""
+    dim = surr.Xn.shape[1]
+    idx = sobol_indices(surr.predict_unit, dim, n=n, seed=seed)
+    st = np.array(idx["ST"], float)
+    st_pos = np.maximum(st, 0.0)
+    share = st_pos / st_pos.sum() if st_pos.sum() > 0 else np.zeros(dim)
+    return {"S1": idx["S1"], "ST": idx["ST"], "share": share.tolist(), "var": idx["var"]}
+
+
+def effect_span(surr: Surrogate, dim: int, *, grid: int = 24) -> list[float]:
+    """Peak-to-peak swing of the KPI attributable to each variable, in y units.
+
+    This is what the inert test needs — the noise floor is a bound on the output, so it must be
+    compared against an output *span*, not a variance share. A variable can hold a large share
+    of a tiny total variance and still be inert.
+    """
+    out = []
+    lin = np.linspace(0.0, 1.0, grid)
+    base = np.full((grid, dim), 0.5)
+    for i in range(dim):
+        P = base.copy()
+        P[:, i] = lin
+        y = surr.predict_unit(P)
+        out.append(float(y.max() - y.min()))
+    return out

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

@@ -0,0 +1,169 @@
+"""Check the Chebyshev centre, binding-constraint detection, and margin conversion.
+
+The centre point and bounds are the headline deliverable, so they are tested against regions and
+constraints whose right answers can be worked out by hand — including the two cases that motivated
+the design: the survivor mean landing outside a disconnected region, and a margin derived from a
+constraint that never activates. Run:  python -m process_window.test_centre
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .centre import Constraint, solve
+
+FAILED: list[str] = []
+
+
+def check(name: str, cond: bool, detail: str = "") -> None:
+    print(f"  {'PASS' if cond else 'FAIL'}  {name}{'  ' + detail if detail else ''}")
+    if not cond:
+        FAILED.append(name)
+
+
+class Lin:
+    """KPI = c0 + sum(coef * x) in unit coords, with a matching effect span per axis."""
+
+    def __init__(self, c0, coef):
+        self.c0 = float(c0)
+        self.coef = np.asarray(coef, float)
+
+    def predict_unit(self, P):
+        return self.c0 + np.atleast_2d(P) @ self.coef
+
+    @property
+    def span(self):
+        return np.abs(self.coef)
+
+
+class Box:
+    """Feasible inside a centred cube of half-width h, expressed as a KPI on distance."""
+
+    def __init__(self, h):
+        self.h = h
+
+    def predict_unit(self, P):
+        return np.max(np.abs(np.atleast_2d(P) - 0.5), axis=1)
+
+
+def main() -> int:
+    box = np.array([[0.0, 100.0]] * 3)
+    names = ("a", "b", "c")
+
+    print("Centred cube -> centre in the middle")
+    r = solve(constraints=[Constraint("cube", Box(0.25), 0.25, "max", 0.01)], box=box, var_names=names, grid_n=41)
+    check("centre ~ (50,50,50)", np.allclose(r.centre_phys, 50, atol=3), str(np.round(r.centre_phys, 1)))
+    check("inradius ~0.25", abs(r.inradius_unit - 0.25) < 0.04, f"{r.inradius_unit:.3f}")
+
+    print("\nMetric check: L-infinity, NOT L1 — a cube region and a diamond region")
+
+    # A box's inradius is the same under both metrics, so a cube cannot detect the difference.
+    # An L1 ball (diamond) of radius r has L-inf inradius r/d but L1 inradius r, so in 3-D the two
+    # differ threefold. This is the test that catches eroding by a cross instead of a cube.
+    class Diamond:
+        def predict_unit(self, P):
+            return np.sum(np.abs(np.atleast_2d(P) - 0.5), axis=1)
+
+    r = 0.30
+    g = solve(constraints=[Constraint("diamond", Diamond(), r, "max", 0.005)], box=box, var_names=names, grid_n=61)
+    expect_linf, expect_l1 = r / 3.0, r
+    print(f"    inradius {g.inradius_unit:.4f}   L-inf expects {expect_linf:.4f}, L1 would give {expect_l1:.4f}")
+    check(
+        "diamond inradius matches L-infinity",
+        abs(g.inradius_unit - expect_linf) < 0.03,
+        f"{g.inradius_unit:.4f} vs {expect_linf:.4f}",
+    )
+    check("and is NOT the L1 value", abs(g.inradius_unit - expect_l1) > 0.10)
+
+    print("\nDisconnected region -> the case that breaks the survivor mean")
+
+    class TwoBlobs:
+        def predict_unit(self, P):
+            P = np.atleast_2d(P)
+            d1 = np.max(np.abs(P - np.array([0.18, 0.18, 0.5])), axis=1)
+            d2 = np.max(np.abs(P - np.array([0.82, 0.82, 0.5])), axis=1)
+            return np.minimum(d1, d2)
+
+    con = Constraint("blobs", TwoBlobs(), 0.12, "max", 0.005)
+    r = solve(constraints=[con], box=box, var_names=names, grid_n=41)
+    inside = bool(con.feasible(r.centre_unit[None, :])[0])
+    M = np.stack([m.ravel() for m in np.meshgrid(*[np.linspace(0, 1, 41)] * 3, indexing="ij")], 1)
+    mean_unit = M[con.feasible(M)].mean(0)
+    mean_inside = bool(con.feasible(mean_unit[None, :])[0])
+    print(f"    chebyshev {np.round(r.centre_unit, 3)} inside={inside}")
+    print(f"    survivor mean {np.round(mean_unit, 3)} inside={mean_inside}")
+    check("Chebyshev centre is inside", inside)
+    check("survivor mean is outside -> Chebyshev is necessary", inside and not mean_inside)
+
+    print("\nBinding constraint is identified by normalised slack")
+    # 'tight' has 2 bands of headroom at the centre; 'loose' has 40. tight must bind.
+    tight = Constraint(
+        "tight", Lin(10.0, [5.0, 0.0, 0.0]), 10.0, "min", 1.25, effect_span=Lin(10.0, [5.0, 0.0, 0.0]).span
+    )
+    loose = Constraint(
+        "loose", Lin(100.0, [5.0, 0.0, 0.0]), 60.0, "min", 1.0, effect_span=Lin(100.0, [5.0, 0.0, 0.0]).span
+    )
+    r = solve(constraints=[tight, loose], box=box, var_names=names, grid_n=41)
+    print(f"    slack {r.slack_at_centre}  binding={r.binding_constraint}")
+    check("binding constraint is 'tight'", r.binding_constraint == "tight")
+
+    print("\nNo active constraint -> margin is zero, and it says so")
+    far1 = Constraint("far1", Lin(100.0, [1.0, 0.0, 0.0]), 10.0, "min", 1.0, effect_span=np.array([1.0, 0.0, 0.0]))
+    far2 = Constraint("far2", Lin(5.0, [1.0, 0.0, 0.0]), 500.0, "max", 1.0, effect_span=np.array([1.0, 0.0, 0.0]))
+    r = solve(constraints=[far1, far2], box=box, var_names=names, grid_n=41)
+    check("margin is zero when nothing binds", np.allclose(r.margin_phys, 0.0), str(np.round(r.margin_phys, 3)))
+    check("and it is reported explicitly", any("NO CONSTRAINT IS ACTIVE" in n for n in r.notes))
+    check(
+        "box is not collapsed by a phantom margin",
+        bool(np.all(r.shrunk_box_phys[:, 1] - r.shrunk_box_phys[:, 0] > 50.0)),
+        str(np.round(r.shrunk_box_phys[:, 1] - r.shrunk_box_phys[:, 0], 1)),
+    )
+
+    print("\nActive constraint -> margin = band/gradient, per axis")
+    # KPI = 40 + 10a + 1b + 0c, threshold 40 'min', band 0.5 -> at centre value 45.5, slack 11
+    # bands, so make the threshold closer: 45 -> slack 1 band, active.
+    surr = Lin(40.0, [10.0, 1.0, 0.0])
+    act = Constraint("active", surr, 45.0, "min", 0.5, effect_span=surr.span)
+    r = solve(constraints=[act], box=box, var_names=names, grid_n=41)
+    print(f"    binding={r.binding_constraint} slack={r.slack_at_centre}")
+    print(f"    margins {np.round(r.margin_phys, 3)}")
+    check(
+        "steep axis gets the smaller margin",
+        r.margin_phys[0] < r.margin_phys[1],
+        f"a={r.margin_phys[0]:.2f} b={r.margin_phys[1]:.2f}",
+    )
+    check(
+        "steep axis margin ~ band/grad = 0.5/10 = 5 units", abs(r.margin_phys[0] - 5.0) < 1.5, f"{r.margin_phys[0]:.2f}"
+    )
+    check(
+        "axis that cannot move the KPI one band is charged nothing",
+        r.margin_phys[2] == 0.0 and any("does not define this boundary" in n for n in r.notes),
+        f"c={r.margin_phys[2]:.2f}",
+    )
+
+    print("\nSub-grid region -> not reported as 'box rejected'")
+
+    # Centred BETWEEN grid points (grid_n=21 -> spacing 0.05, points at 0.50 and 0.55), so no
+    # grid node can fall inside it. This is the case that must not be reported as "box rejected".
+    class Sliver:
+        def predict_unit(self, P):
+            return np.abs(np.atleast_2d(P)[:, 0] - 0.525)
+
+    r = solve(constraints=[Constraint("sliver", Sliver(), 0.0015, "max", 1e-4)], box=box, var_names=names, grid_n=21)
+    check("detects a too-coarse grid", any("GRID TOO COARSE" in n for n in r.notes), "; ".join(r.notes)[:80])
+
+    print("\nGenuinely empty -> confirmed by dense probe")
+    r = solve(
+        constraints=[Constraint("impossible", Lin(0.0, [1.0, 0, 0]), 99.0, "min", 1.0)],
+        box=box,
+        var_names=names,
+        grid_n=21,
+    )
+    check("confirms empty", any("really is rejected" in n for n in r.notes))
+
+    print(f"\n{'ALL PASS' if not FAILED else 'FAILURES: ' + ', '.join(FAILED)}")
+    return 1 if FAILED else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())