simcon-toolkit 0.1.0__py3-none-any.whl

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

@@ -0,0 +1,298 @@
+"""The green region, the Chebyshev centre, and the safety margin in variable space.
+
+Three things the brief is specific about, and each has a trap:
+
+**Chebyshev centre, not the survivor mean.** The mean of the survivors is pulled toward wherever
+the design happened to put points, and on a non-convex or disconnected green region it can land
+*outside* it entirely (demonstrated in `test_centre.py`). The Chebyshev centre is the deepest
+interior point — the centre of the largest inscribed ball — so it maximises the distance to the
+nearest failure in every direction at once. With three variables this is a distance transform on a
+grid, no optimiser needed.
+
+**The margin must be in variable space, and against the constraint that actually binds.**
+A KPI uncertainty band is in bar or K; the engineer needs K, cm³/s and %. The conversion is
+`band / |dKPI/dx_i|` — the distance you must move x_i before a KPI change becomes distinguishable
+from the band. But it must be computed for the constraint whose surface is *nearest* at the
+centre. Deriving it from a constraint that never activates inside the box produces a margin that
+is both meaningless and, because a shallow gradient makes `band/gradient` enormous, actively
+harmful: it collapses the window of the variable the engineer is freest to move. So every
+constraint is carried with its own threshold and band, the binding one is identified by normalised
+slack, and the margin comes from that one.
+
+**Distances must be normalised before they can be compared.** 1 K and 1 cm³/s are not comparable
+magnitudes, so the distance transform runs in the unit box. Skipping that silently weights
+whichever variable happens to have the largest numeric range.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+
+@dataclass
+class Constraint:
+    """One acceptance criterion, in a form the geometry code can reason about.
+
+    ``sense="min"`` means feasible where value >= threshold (e.g. a no-flow margin);
+    ``sense="max"`` means feasible where value <= threshold (e.g. a hotspot rank cut).
+    ``band`` is the KPI's derived resolution floor — the unit in which "close to the threshold"
+    is measured, so proximity is judged against what the solver can actually resolve.
+    """
+
+    name: str
+    surr: object
+    threshold: float
+    sense: str
+    band: float
+    effect_span: np.ndarray | None = None
+
+    def value(self, P: np.ndarray) -> np.ndarray:
+        return self.surr.predict_unit(np.atleast_2d(P))
+
+    def feasible(self, P: np.ndarray) -> np.ndarray:
+        v = self.value(P)
+        return v >= self.threshold if self.sense == "min" else v <= self.threshold
+
+    def slack_bands(self, P: np.ndarray) -> np.ndarray:
+        """How many bands of headroom this constraint has. Negative = violated."""
+        v = self.value(P)
+        raw = (v - self.threshold) if self.sense == "min" else (self.threshold - v)
+        return raw / max(self.band, 1e-12)
+
+
+@dataclass
+class GreenRegion:
+    grid_shape: tuple[int, ...]
+    box: np.ndarray
+    feasible: np.ndarray
+    centre_unit: np.ndarray
+    centre_phys: np.ndarray
+    inradius_unit: float
+    margin_phys: np.ndarray
+    shrunk_box_phys: np.ndarray
+    feasible_fraction: float
+    limiting_variable: str | None
+    binding_constraint: str | None
+    slack_at_centre: dict = field(default_factory=dict)
+    notes: list = field(default_factory=list)
+
+
+def _grid(box: np.ndarray, n: int) -> np.ndarray:
+    axes = [np.linspace(0.0, 1.0, n) for _ in range(len(box))]
+    mesh = np.meshgrid(*axes, indexing="ij")
+    return np.stack([m.ravel() for m in mesh], axis=1)
+
+
+def _erode_cube(m: np.ndarray) -> np.ndarray:
+    """One erosion by a full (3,)*d cube — i.e. one step of L-infinity.
+
+    Cube erosion is separable, but the 1-D erosions must be **chained**: each axis erodes the
+    *result* of the previous axis. Rolling the same input for every axis instead erodes by a cross,
+    which gives the L1 (Manhattan) transform — a different metric, and the wrong one here.
+    """
+    out = m
+    for ax in range(m.ndim):
+        a, b = np.roll(out, 1, axis=ax), np.roll(out, -1, axis=ax)
+        lo = [slice(None)] * m.ndim
+        hi = [slice(None)] * m.ndim
+        lo[ax], hi[ax] = 0, -1
+        a[tuple(lo)] = False  # roll wraps; the wrapped face must not count as safe
+        b[tuple(hi)] = False
+        out = out & a & b
+    return out
+
+
+def _chebyshev(feasible: np.ndarray) -> tuple[np.ndarray, float]:
+    """Deepest interior cell and its depth in cells — exact L-infinity distance transform.
+
+    L-infinity is the right metric for a process window: the depth is then the half-width of the
+    largest inscribed **box**, which is exactly "how far can each variable move independently
+    before leaving the window". A Euclidean or L1 inradius would not answer that question.
+
+    Outside the grid counts as infeasible, so the box edges bound the inscribed cube — a centre
+    cannot claim depth it only has because the grid stopped.
+    """
+    depth = feasible.astype(np.int32)
+    cur = feasible.copy()
+    while cur.any():
+        cur = _erode_cube(cur)
+        depth += cur.astype(np.int32)
+    return np.array(np.unravel_index(int(np.argmax(depth)), feasible.shape)), float(depth.max())
+
+
+def gradient_unit(surr, at_unit: np.ndarray, *, h: float = 0.02) -> np.ndarray:
+    """d(KPI)/d(x_i) per unit of normalised x_i, central difference."""
+    d = len(at_unit)
+    g = np.zeros(d)
+    for i in range(d):
+        lo, hi = at_unit.copy(), at_unit.copy()
+        lo[i] = max(0.0, at_unit[i] - h)
+        hi[i] = min(1.0, at_unit[i] + h)
+        span = hi[i] - lo[i]
+        if span > 0:
+            g[i] = float(surr.predict_unit(hi[None, :])[0] - surr.predict_unit(lo[None, :])[0]) / span
+    return g
+
+
+def solve(
+    *,
+    constraints: list[Constraint],
+    box: np.ndarray,
+    var_names: tuple[str, ...],
+    grid_n: int = 41,
+    active_within_bands: float = 6.0,
+    floor_frac: float = 0.02,
+    cap_frac: float = 0.5,
+) -> GreenRegion:
+    """Green region, Chebyshev centre, and the inward-shrunk recommended box."""
+    notes: list[str] = []
+    d = len(box)
+    spans = box[:, 1] - box[:, 0]
+    pts = _grid(box, grid_n)
+
+    feas_flat = np.ones(len(pts), bool)
+    for c in constraints:
+        feas_flat &= c.feasible(pts)
+    feasible = feas_flat.reshape((grid_n,) * d)
+    frac = float(feasible.mean())
+
+    if not feasible.any():
+        # A grid can only see a region thicker than one cell; probe densely before declaring the
+        # box rejected, or we would report a confident wrong answer.
+        rng = np.random.default_rng(0)
+        probe = rng.random((200_000, d))
+        hits = np.ones(len(probe), bool)
+        for c in constraints:
+            hits &= c.feasible(probe)
+        if hits.any():
+            notes.append(
+                f"GRID TOO COARSE: no feasible cell at grid_n={grid_n}, but {int(hits.sum())} of "
+                f"200000 random probes are feasible (~{100 * hits.mean():.3f} % of the box). The "
+                "green region is thinner than one grid cell — refine the grid rather than "
+                "reporting the box as rejected."
+            )
+            notes.append(
+                f"suggested grid_n >= "
+                f"{int(np.clip(np.ceil(3.0 / max(hits.mean() ** (1.0 / d), 1e-6)), grid_n * 2, 401))}"
+            )
+        else:
+            notes.append("no feasible cell on the grid and none in 200000 random probes — the box really is rejected")
+        return GreenRegion(
+            (grid_n,) * d,
+            box,
+            feasible,
+            np.full(d, np.nan),
+            np.full(d, np.nan),
+            0.0,
+            np.full(d, np.nan),
+            box.copy(),
+            frac,
+            None,
+            None,
+            {},
+            notes,
+        )
+
+    idx, depth_cells = _chebyshev(feasible)
+    centre_unit = idx / (grid_n - 1)
+    cell = 1.0 / (grid_n - 1)
+    inradius_unit = depth_cells * cell
+    centre_phys = box[:, 0] + centre_unit * spans
+
+    if depth_cells <= 1:
+        notes.append(
+            f"Chebyshev depth is only {depth_cells:.0f} grid cell(s): the green region is "
+            "barely thicker than the grid resolution, so the centre is poorly determined. "
+            "Refine the grid before trusting it."
+        )
+
+    # --- which constraint actually binds at the centre? ----------------------
+    slack = {c.name: float(c.slack_bands(centre_unit[None, :])[0]) for c in constraints}
+    binding = min(slack, key=slack.get)
+    binding_c = next(c for c in constraints if c.name == binding)
+    notes.append(
+        "slack at centre, in units of each KPI's own resolution band: "
+        + ", ".join(f"{k}={v:+.1f}" for k, v in sorted(slack.items(), key=lambda kv: kv[1]))
+    )
+
+    if slack[binding] > active_within_bands:
+        notes.append(
+            f"NO CONSTRAINT IS ACTIVE at the centre: the nearest ({binding}) still has "
+            f"{slack[binding]:.1f} bands of headroom. The recommended box is therefore limited by "
+            "the extent of the green region and by the wide box itself, not by any KPI boundary — "
+            "so a KPI-derived safety margin is not meaningful here and is set to zero. Report the "
+            "box as 'no active constraint found inside the wide box' rather than implying a "
+            "margin was earned."
+        )
+        margin_phys = np.zeros(d)
+    else:
+        # Margin from the BINDING constraint's local gradient. Axes along which that constraint
+        # cannot move by even one band across the whole box do not define its boundary, so they
+        # are charged nothing — otherwise a shallow gradient would collapse the window of the
+        # variable the engineer is freest to move.
+        g_unit = np.abs(gradient_unit(binding_c.surr, centre_unit))
+        margin_phys = np.zeros(d)
+        for i in range(d):
+            es = None if binding_c.effect_span is None else float(binding_c.effect_span[i])
+            if es is not None and es < binding_c.band:
+                notes.append(
+                    f"{var_names[i]}: cannot move {binding} by one band anywhere in the "
+                    f"box (span {es:.4g} < band {binding_c.band:.4g}); it does not define "
+                    "this boundary, so no margin is charged on this axis."
+                )
+                continue
+            if g_unit[i] <= 1e-12:
+                margin_phys[i] = cap_frac * spans[i]
+            else:
+                margin_phys[i] = float(np.clip(binding_c.band / g_unit[i], floor_frac, cap_frac) * spans[i])
+
+    # --- largest axis-aligned box inside the green region, then shrink -------
+    lo_u, hi_u = np.zeros(d), np.zeros(d)
+    for i in range(d):
+        for direction in (-1, +1):
+            k = 0
+            while True:
+                probe = idx.copy()
+                probe[i] = idx[i] + direction * (k + 1)
+                if probe[i] < 0 or probe[i] >= grid_n or not feasible[tuple(probe)]:
+                    break
+                k += 1
+            if direction < 0:
+                lo_u[i] = k * cell
+            else:
+                hi_u[i] = k * cell
+
+    margin_unit = margin_phys / np.maximum(spans, 1e-12)
+    shrunk = np.empty_like(box)
+    limiting, worst = None, np.inf
+    for i in range(d):
+        half_lo = max(lo_u[i] - margin_unit[i], 0.0)
+        half_hi = max(hi_u[i] - margin_unit[i], 0.0)
+        shrunk[i, 0] = box[i, 0] + (centre_unit[i] - half_lo) * spans[i]
+        shrunk[i, 1] = box[i, 0] + (centre_unit[i] + half_hi) * spans[i]
+        width = half_lo + half_hi
+        if width < worst:
+            worst, limiting = width, var_names[i]
+        if width <= 0:
+            notes.append(
+                f"{var_names[i]}: the margin ({margin_phys[i]:.4g}) exceeds the room "
+                "inside the green region — no usable window; fix it at the centre value."
+            )
+
+    return GreenRegion(
+        (grid_n,) * d,
+        box,
+        feasible,
+        centre_unit,
+        centre_phys,
+        inradius_unit,
+        margin_phys,
+        shrunk,
+        frac,
+        limiting,
+        binding,
+        slack,
+        notes,
+    )

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

@@ -0,0 +1,144 @@
+"""Space-filling designs, on numpy alone (no scipy in this venv).
+
+**Sobol, not LHS**, and the reason matters: the brief chose Sobol because it is *incremental* —
+the first 2^k points of the sequence are themselves a balanced design, so the sweep can stop
+early or be extended without recommitting, and the design does not have to be fixed before we
+know which variables matter. An LHS loses its stratification the moment you add a point, which
+would forfeit exactly that property. So this is a real Sobol sequence (direction numbers below),
+not an LHS standing in for one.
+
+`scipy.stats.qmc` is unavailable here, so the generator is implemented directly. It is verified
+against the properties that actually matter for this campaign (balance of every 2^k prefix,
+one-dimensional projection uniformity) in `test_design.py`.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+# Primitive polynomials (as bit-encoded coefficients) and initial direction numbers for the
+# first 8 dimensions, from the standard Joe-Kuo tables. Dimension 1 is the plain van der
+# Corput sequence in base 2 (degree 0, no recurrence).
+#
+# These numbers are third-party data under their own BSD licence, which covers the
+# upstream program and these numbers alike; of the two, this project carries only the
+# numbers, and the code below is the project's own. Their copyright notice and
+# disclaimer are in NOTICE at the root of this project, and must travel with any copy.
+_POLY = [1, 3, 7, 11, 13, 19, 25, 37]
+_MDEG = [0, 1, 2, 3, 3, 4, 4, 5]
+_MINIT: list[list[int]] = [
+    [],
+    [1],
+    [1, 3],
+    [1, 3, 1],
+    [1, 1, 1],
+    [1, 1, 3, 3],
+    [1, 3, 5, 13],
+    [1, 1, 5, 5, 17],
+]
+_BITS = 30
+
+
+def _direction_numbers(dim: int) -> np.ndarray:
+    """(dim, _BITS) table of direction integers V[j][i] for the Gray-code recurrence."""
+    if dim > len(_POLY):
+        raise ValueError(f"Sobol here supports up to {len(_POLY)} dimensions, asked for {dim}")
+    V = np.zeros((dim, _BITS + 1), dtype=np.uint64)
+    # dimension 0: V[i] = 1 << (BITS - i)  -> van der Corput
+    for i in range(1, _BITS + 1):
+        V[0, i] = np.uint64(1) << np.uint64(_BITS - i)
+    for j in range(1, dim):
+        s, a, m = _MDEG[j], _POLY[j], _MINIT[j]
+        for i in range(1, s + 1):
+            V[j, i] = np.uint64(m[i - 1]) << np.uint64(_BITS - i)
+        for i in range(s + 1, _BITS + 1):
+            v = V[j, i - s] ^ (V[j, i - s] >> np.uint64(s))
+            for k in range(1, s):
+                if (a >> (s - 1 - k)) & 1:
+                    v ^= V[j, i - k]
+            V[j, i] = v
+    return V
+
+
+def sobol(n: int, dim: int, *, skip: int = 0) -> np.ndarray:
+    """First ``n`` Sobol points in [0,1)^dim, as an (n, dim) array.
+
+    Generated by the Gray-code recurrence, so ``sobol(2n, d)[:n] == sobol(n, d)`` — that
+    identity is what makes the sweep extensible, and it is asserted in the tests.
+
+    ``skip=0`` keeps index 0, the all-zeros point. QMC code often drops it because it is not a
+    "random-looking" point, but here it maps to a real and interesting process point — the box
+    corner at coldest melt, coldest mould, slowest fill — which this study wants evaluated
+    anyway. Keeping it also preserves exact balance: every 2^k prefix then puts exactly one
+    point in each of the 2^k bins of every one-dimensional projection, whereas dropping a point
+    from the block leaves one bin empty and one doubled (measured, and asserted in the tests).
+    """
+    if n <= 0:
+        return np.zeros((0, dim))
+    V = _direction_numbers(dim)
+    total = n + skip
+    out = np.zeros((total, dim), dtype=np.float64)
+    x = np.zeros(dim, dtype=np.uint64)
+    for i in range(1, total):
+        c = 1
+        v = i - 1
+        while v & 1:
+            v >>= 1
+            c += 1
+        x ^= V[:, c]
+        out[i] = x.astype(np.float64) / float(1 << _BITS)
+    return out[skip:]
+
+
+def scale_to_box(
+    unit: np.ndarray, box: dict[str, tuple[float, float]], order: tuple[str, ...]
+) -> dict[str, np.ndarray]:
+    """Map unit-hypercube points onto the named variable box."""
+    if unit.shape[1] != len(order):
+        raise ValueError(f"design has {unit.shape[1]} dims, box order names {len(order)}")
+    return {name: box[name][0] + unit[:, i] * (box[name][1] - box[name][0]) for i, name in enumerate(order)}
+
+
+def epsilon_design(
+    centre: dict[str, float],
+    *,
+    melt_deltas_K=(0.02, 0.05, 0.10),
+    wall_deltas_K=(0.02, 0.05, 0.10),
+    flow_rel=(2e-4, 1e-3),
+) -> list[dict]:
+    """Physically meaningless input perturbations, for the noise-floor experiment.
+
+    The point is to move the *inputs* by an amount no real machine could resolve, and see how
+    far the *outputs* move. Whatever spread comes back is the floor below which an apparent
+    effect is not an effect.
+
+    Scale justification: a production machine holds melt temperature to roughly ±1–2 K and
+    mould temperature to about ±1 K, so 0.02–0.10 K is two orders of magnitude below anything
+    controllable — physically meaningless by a wide margin, while still changing the submitted
+    float. Flow is perturbed *relatively* (it is a ratio scale) by 0.02–0.1 %, likewise far
+    below any screw's metering repeatability.
+
+    Note what this does **not** measure. The solver is deterministic, so there is no run-to-run
+    scatter to find; a zero perturbation would return a bit-identical result. What is measured
+    is the response to a negligible input change, dominated by float16 storage quantization of
+    the result fields plus the model's own conditioning. That is a genuine resolution floor —
+    but calling it "noise" would wrongly imply more runs could average it away.
+    """
+    pts = [dict(centre, label="eps nominal", kind="nominal")]
+    for d in melt_deltas_K:
+        for s in (+1, -1):
+            pts.append(dict(centre, melt_C=centre["melt_C"] + s * d, label=f"eps melt {s * d:+.3f}K", kind="melt"))
+    for d in wall_deltas_K:
+        for s in (+1, -1):
+            pts.append(dict(centre, wall_C=centre["wall_C"] + s * d, label=f"eps wall {s * d:+.3f}K", kind="wall"))
+    for r in flow_rel:
+        for s in (+1, -1):
+            pts.append(
+                dict(
+                    centre,
+                    flow_cm3_s=centre["flow_cm3_s"] * (1.0 + s * r),
+                    label=f"eps flow {s * r * 100:+.3f}%",
+                    kind="flow",
+                )
+            )
+    return pts