simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/packages/cadmould_scoring/metrics.py

@@ -0,0 +1,519 @@
+"""Injection-molding metrics from an AI-Solver filling result (HDF5).
+
+Everything an early-stage gating decision needs, read straight from one
+``*_prediction.h5`` produced by the cloud AI filling solver:
+
+  * **max filling pressure** [bar] - the real per-node ``Pressure`` field
+    (the platform's summary ``max_pressure_Pa`` is 0 for this model).
+  * **fill completeness** - did the part fill, or is there a short shot?
+  * **fill-time map** ``t_fill[node]`` - when the flow front first reached each
+    node; the basis for evenness and weld-line analysis.
+  * **fill evenness / balance** - how simultaneously the part finishes filling
+    (racetracking and stranded regions show up as a long tail).
+  * **weld lines** - where two flow fronts meet head-on.  Detected from the
+    fill-time field: at a node reached from two near-opposite directions by
+    fronts that arrive at about the same time, the fronts collided -> weld.
+    Clustered into lines and located in part space so we can judge visibility.
+
+The only inputs are the result file and the gate positions used (so we can mark
+them and measure flow lengths).  Pure read-only; no cloud, no SDK.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import h5py
+import numpy as np
+from scipy.spatial import cKDTree
+
+
+# --------------------------------------------------------------------------
+# low-level readers
+# --------------------------------------------------------------------------
+def _timestep_names(f: h5py.File) -> list[str]:
+    return sorted(k for k in f if k.startswith("TimeStep_"))
+
+
+def read_coords(f: h5py.File) -> np.ndarray:
+    """Midplane node coordinates (N, 3) in mm (geometry group has a trailing space)."""
+    key = next(k for k in f if k.strip() == "geometry3DF")
+    return np.asarray(f[key]["Coordinates"][()], dtype=np.float64)
+
+
+def fill_time(f: h5py.File, dof_thresh: float = 0.5) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Per-node first-arrival time of the flow front.
+
+    Returns ``(t_fill, reached, times)`` where ``t_fill[i]`` is the time the
+    front first reached node ``i`` (inf if never), ``reached`` is the bool mask
+    of filled nodes, and ``times`` is the time axis.
+
+    In the cloud AI result ``Degree_of_filling`` is a sharp 0->1 front present at
+    every node (0 = not filled yet, ramps to 1 once the front passes) - *not*
+    NaN-masked.  A node counts as reached the first step its value crosses
+    ``dof_thresh``; the field is monotone, so "ever crossed" == "filled".
+    """
+    steps = _timestep_names(f)
+    times = np.array([float(f[s].attrs["Time"]) for s in steps], dtype=np.float64)
+    n = f[steps[0]]["Degree_of_filling"].shape[0]
+    t_fill = np.full(n, np.inf, dtype=np.float64)
+    reached = np.zeros(n, dtype=bool)
+    for s, t in zip(steps, times, strict=True):
+        dof = np.asarray(f[s]["Degree_of_filling"][()], dtype=np.float32)
+        now = np.isfinite(dof) & (dof > dof_thresh)
+        newly = now & ~reached
+        t_fill[newly] = t
+        reached |= now
+    return t_fill, reached, times
+
+
+def max_pressure_bar(f: h5py.File) -> float:
+    """Peak per-node cavity pressure over all time steps, returned in **bar**.
+
+    Honours the field's ``unit`` attribute: newer platform results store Pressure
+    in ``Pa``, older files in ``bar`` — both come back as bar (Pa is /1e5).
+    """
+    pmax = 0.0
+    unit = ""
+    for s in _timestep_names(f):
+        g = f[s]
+        if "Pressure" in g:
+            ds = g["Pressure"]
+            if not unit:
+                u = ds.attrs.get("unit", "")
+                unit = (u.decode() if isinstance(u, bytes) else str(u)).strip().lower()
+            pr = np.asarray(ds[()], dtype=np.float64)
+            if np.isfinite(pr).any():
+                pmax = max(pmax, float(np.nanmax(pr)))
+    if unit == "pa":
+        pmax /= 1.0e5
+    return pmax
+
+
+def max_shear_rate(f: h5py.File) -> float:
+    """Peak shear rate over the fill [1/s].
+
+    Handles both result formats: a straight ``Shear_rate`` field [1/s] (current)
+    used as-is, or the legacy log-encoded ``Log(1 + Shear_rate)`` (de-logged with
+    expm1; its values are in units of 100/s, hence the x100). High shear risks
+    material degradation, so it bounds how hard the flow rate can be pushed.
+    """
+    steps = _timestep_names(f)
+    if not steps:
+        return 0.0
+    g0 = f[steps[0]]
+    if "Shear_rate" in g0:
+        name, is_log, scale = "Shear_rate", False, 1.0
+    elif "Log(1 + Shear_rate)" in g0:
+        name, is_log, scale = "Log(1 + Shear_rate)", True, 100.0
+    else:
+        return 0.0
+    smax = 0.0
+    for s in steps:
+        sr = np.asarray(f[s][name][()], dtype=np.float64)
+        if is_log:
+            sr = np.expm1(sr)
+        if np.isfinite(sr).any():
+            smax = max(smax, float(np.nanmax(sr)))
+    return smax * scale
+
+
+# --------------------------------------------------------------------------
+# neighbour graph (scipy KD-tree)
+# --------------------------------------------------------------------------
+def knn_indices(coords: np.ndarray, k: int = 10) -> np.ndarray:
+    """(N, k) indices of each node's k nearest neighbours (self excluded).
+
+    Asks the tree for k+1 and drops the node itself, because a nearest-neighbour
+    query always returns the query point first. Taking k directly would leave every
+    node with k-1 real neighbours plus itself, which shifts the weld clusters.
+
+    On *coincident* nodes the chosen neighbours are arbitrary and no two libraries
+    need agree, since every candidate sits at distance zero. That is a property of
+    the question, not of this implementation; a real mesh essentially never ties.
+    """
+    coords = np.ascontiguousarray(coords, dtype=np.float64)
+    n = len(coords)
+    _dist, idx = cKDTree(coords).query(coords, k=k + 1)
+    idx = np.atleast_2d(idx)
+    out = np.zeros((n, k), dtype=np.int64)
+    for i in range(n):
+        # `j < n` is load-bearing, not defensive: when the mesh holds fewer than k+1
+        # nodes, query() pads the row with index n -- one past the end -- at distance
+        # infinity. Keeping those would emit out-of-range indices that only fail later,
+        # wherever a caller indexes coords with them.
+        nn = [int(j) for j in idx[i] if j != i and j < n]
+        # Short rows only on a degenerate mesh (too few nodes, or duplicates). Pad
+        # rather than raise: a ragged row would break the (N, k) shape every caller
+        # indexes into.
+        if len(nn) < k:
+            nn += [nn[-1]] * (k - len(nn)) if nn else [i] * k
+        out[i] = nn[:k]
+    return out
+
+
+# --------------------------------------------------------------------------
+# weld-line detection
+# --------------------------------------------------------------------------
+@dataclass
+class WeldCluster:
+    """One weld line: a group of kNN-adjacent weld nodes, summarised in part space."""
+
+    n_nodes: int
+    centroid: np.ndarray  # (3,) mm
+    extent_mm: float  # bounding diagonal of the cluster
+    mean_angle_deg: float  # mean front meeting angle (180 = head-on)
+    fill_time_s: float  # when the fronts met (mean t_fill of the cluster)
+    axis_pos: float  # 0..1 position along the part's long axis
+
+
+def flow_field(coords: np.ndarray, t_fill: np.ndarray, knn: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """Unit flow direction at each node and the gradient magnitude.
+
+    Flow runs from low to high fill time, so the direction is the (normalised)
+    least-squares gradient of ``t_fill`` over each node's neighbourhood.  The
+    magnitude is ~1/front-speed; it collapses toward 0 where the front
+    terminates (a flow-time ridge), which is exactly the weld neighbourhood.
+    """
+    n = len(coords)
+    f = np.zeros((n, 3))
+    mag = np.zeros(n)
+    for i in range(n):
+        if not np.isfinite(t_fill[i]):
+            continue
+        nbr = knn[i]
+        ok = np.isfinite(t_fill[nbr])
+        if np.count_nonzero(ok) < 3:
+            continue
+        dX = coords[nbr[ok]] - coords[i]
+        dt = t_fill[nbr[ok]] - t_fill[i]
+        g, *_ = np.linalg.lstsq(dX, dt, rcond=None)
+        m = float(np.linalg.norm(g))
+        mag[i] = m
+        if m > 1e-9:
+            f[i] = g / m
+    return f, mag
+
+
+def detect_welds(
+    coords: np.ndarray,
+    t_fill: np.ndarray,
+    knn: np.ndarray,
+    times: np.ndarray,
+    *,
+    min_angle_deg: float = 120.0,
+    conv_min: float = 0.45,
+    long_axis: int = 1,
+) -> tuple[np.ndarray, np.ndarray, list[WeldCluster]]:
+    """Find weld nodes (flow fronts colliding) and cluster them into lines.
+
+    Built on the flow-direction field (gradient of fill time).  Two signals
+    must agree, which is what makes it robust on a fine mesh where neighbouring
+    nodes fill barely a step apart:
+
+      * **Flow convergence** - the neighbours' flow directions point *into* this
+        node from both sides (``conv >= conv_min``).  In smooth flow the
+        upstream side flows toward the node and the downstream side flows away,
+        so convergence averages to ~0; only where two fronts run into each
+        other do all sides point inward.  (A lone front ending at a free edge
+        can also converge, so we also require:)
+      * **Opposed incoming fronts** - the two earlier neighbours that are most
+        opposed meet at >= ``min_angle_deg`` (a genuine head-on collision).
+
+    Returns ``(weld_score, weld_angle_deg, clusters)``; ``weld_score`` in 0..1.
+    """
+    n = len(coords)
+    f, mag = flow_field(coords, t_fill, knn)
+    cos_thresh = np.cos(np.radians(min_angle_deg))
+
+    score = np.zeros(n)
+    angle = np.zeros(n)
+    for i in range(n):
+        ti = t_fill[i]
+        if not np.isfinite(ti):
+            continue
+        nbr = knn[i]
+        # --- flow convergence: do neighbours' flow vectors point toward i? ---
+        u = coords[i] - coords[nbr]
+        un = np.linalg.norm(u, axis=1, keepdims=True)
+        u = u / np.maximum(un, 1e-9)
+        has_dir = mag[nbr] > 1e-9
+        if np.count_nonzero(has_dir) < 3:
+            continue
+        conv = float(np.mean(np.sum(f[nbr][has_dir] * u[has_dir], axis=1)))
+        if conv < conv_min:
+            continue
+        # --- opposed incoming fronts (head-on meeting angle) ---
+        tn = t_fill[nbr]
+        earlier = np.isfinite(tn) & (tn <= ti)
+        if np.count_nonzero(earlier) < 2:
+            continue
+        dirs = u[earlier]  # unit dirs from earlier nbrs into i
+        g = dirs @ dirs.T
+        np.fill_diagonal(g, 1.0)
+        cos_ab = float(np.min(g))
+        if cos_ab > cos_thresh:
+            continue
+        score[i] = min(1.0, conv)
+        angle[i] = float(np.degrees(np.arccos(np.clip(cos_ab, -1, 1))))
+
+    clusters = _cluster_welds(coords, score, angle, t_fill, knn, long_axis, score_min=conv_min)
+    return score, angle, clusters
+
+
+def cluster_member_mask(
+    coords: np.ndarray,
+    score: np.ndarray,
+    knn: np.ndarray,
+    *,
+    score_min: float = 0.45,
+    min_size: int = 4,
+) -> np.ndarray:
+    """Bool mask of weld nodes that belong to a real cluster (>= min_size).
+
+    Filters out the isolated specks along the midsurface's free rim (a known
+    edge artifact of convergence-based detection) so only genuine weld *lines*
+    remain - the same nodes that back the reported WeldCluster list.
+    """
+    weld = np.where(score >= score_min)[0]
+    mask = np.zeros(len(coords), dtype=bool)
+    if len(weld) == 0:
+        return mask
+    wset = set(weld.tolist())
+    parent = {i: i for i in wset}
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    for i in weld:
+        for j in knn[i]:
+            if j in wset:
+                parent[find(int(i))] = find(int(j))
+    groups: dict[int, list[int]] = {}
+    for i in wset:
+        groups.setdefault(find(i), []).append(i)
+    for members in groups.values():
+        if len(members) >= min_size:
+            mask[members] = True
+    return mask
+
+
+def _cluster_welds(
+    coords: np.ndarray,
+    score: np.ndarray,
+    angle: np.ndarray,
+    t_fill: np.ndarray,
+    knn: np.ndarray,
+    long_axis: int,
+    score_min: float = 0.34,
+) -> list[WeldCluster]:
+    """Union-find weld nodes that are kNN-adjacent into weld lines."""
+    weld = np.where(score >= score_min)[0]
+    if len(weld) == 0:
+        return []
+    wset = set(weld.tolist())
+    parent = {i: i for i in wset}
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(x: int, y: int) -> None:
+        parent[find(x)] = find(y)
+
+    for i in weld:
+        for j in knn[i]:
+            if j in wset:
+                union(int(i), int(j))
+
+    groups: dict[int, list[int]] = {}
+    for i in wset:
+        groups.setdefault(find(i), []).append(i)
+
+    lo = coords[:, long_axis].min()
+    hi = coords[:, long_axis].max()
+    span = max(hi - lo, 1e-9)
+
+    out: list[WeldCluster] = []
+    for members in groups.values():
+        if len(members) < 4:  # ignore specks
+            continue
+        m = np.array(members)
+        c = coords[m]
+        cen = c.mean(0)
+        ext = float(np.linalg.norm(c.max(0) - c.min(0)))
+        out.append(
+            WeldCluster(
+                n_nodes=len(members),
+                centroid=cen,
+                extent_mm=ext,
+                mean_angle_deg=float(np.mean(angle[m])),
+                fill_time_s=float(np.nanmean(t_fill[m])),
+                axis_pos=float((cen[long_axis] - lo) / span),
+            )
+        )
+    out.sort(key=lambda w: w.n_nodes, reverse=True)
+    return out
+
+
+# --------------------------------------------------------------------------
+# fill-evenness metrics
+# --------------------------------------------------------------------------
+def fill_balance(t_fill: np.ndarray, reached: np.ndarray) -> dict:
+    """How simultaneously the part finishes filling.
+
+    A balanced fill finishes everywhere at about the same time; racetracking or
+    a stranded pocket shows up as a long tail in t_fill.  ``tail_fraction`` is
+    the share of total fill time spent filling the last 10% of the part - near
+    0.1 is balanced, large means the end lags badly (imbalance / possible air
+    trap at the last-filled spot).
+    """
+    tf = t_fill[reached & np.isfinite(t_fill)]
+    if tf.size == 0:
+        return {
+            "total_fill_time_s": float("nan"),
+            "tail_fraction": float("nan"),
+            "t90_s": float("nan"),
+            "t100_s": float("nan"),
+        }
+    t100 = float(tf.max())
+    t90 = float(np.percentile(tf, 90))
+    tail = (t100 - t90) / t100 if t100 > 0 else 0.0
+    return {"total_fill_time_s": t100, "t90_s": t90, "t100_s": t100, "tail_fraction": float(tail)}
+
+
+def last_filled_region(
+    coords: np.ndarray,
+    t_fill: np.ndarray,
+    reached: np.ndarray,
+    long_axis: int = 1,
+    frac: float = 0.02,
+) -> tuple[np.ndarray, float]:
+    """Centroid + axis position of the last ``frac`` of the part to fill.
+
+    This is where the part finishes (and where any unvented air ends up).
+    """
+    tf = t_fill.copy()
+    tf[~(reached & np.isfinite(tf))] = -np.inf
+    k = max(1, int(frac * reached.sum()))
+    last = np.argpartition(tf, -k)[-k:]
+    cen = coords[last].mean(0)
+    lo, hi = coords[:, long_axis].min(), coords[:, long_axis].max()
+    return cen, float((cen[long_axis] - lo) / max(hi - lo, 1e-9))
+
+
+# --------------------------------------------------------------------------
+# top-level analysis
+# --------------------------------------------------------------------------
+@dataclass
+class Analysis:
+    """Every gating metric derived from one filling result, plus the inputs to read them by."""
+
+    path: Path
+    max_pressure_bar: float
+    max_shear_rate_1s: float
+    fill_pct: float
+    short_shot: bool
+    total_fill_time_s: float
+    tail_fraction: float
+    n_welds: int
+    weld_clusters: list[WeldCluster]
+    last_fill_axis_pos: float
+    last_fill_centroid: np.ndarray
+    gate_positions_mm: list[list[float]] = field(default_factory=list)
+    long_axis: int = 1
+
+    def summary(self) -> str:
+        """One console line of the headline metrics; the weld list reads ``none`` when empty."""
+        wl = (
+            "  ".join(f"[{c.n_nodes}n @axis{c.axis_pos:.2f} ang{c.mean_angle_deg:.0f}deg]" for c in self.weld_clusters)
+            or "none"
+        )
+        return (
+            f"P={self.max_pressure_bar:6.1f}bar  fill={self.fill_pct:5.1f}%"
+            f"{' SHORT-SHOT' if self.short_shot else ''}  "
+            f"t_fill={self.total_fill_time_s:.2f}s  tail={self.tail_fraction:.2f}  "
+            f"welds={self.n_welds}: {wl}"
+        )
+
+    def as_dict(self) -> dict:
+        """JSON-safe view, with every float rounded to its reporting precision."""
+        return {
+            "path": str(self.path),
+            "max_pressure_bar": round(self.max_pressure_bar, 1),
+            "max_shear_rate_1s": round(self.max_shear_rate_1s, 1),
+            "fill_pct": round(self.fill_pct, 2),
+            "short_shot": self.short_shot,
+            "total_fill_time_s": round(self.total_fill_time_s, 3),
+            "tail_fraction": round(self.tail_fraction, 3),
+            "n_welds": self.n_welds,
+            "welds": [
+                {
+                    "n_nodes": c.n_nodes,
+                    "axis_pos": round(c.axis_pos, 3),
+                    "centroid_mm": [round(float(x), 1) for x in c.centroid],
+                    "mean_angle_deg": round(c.mean_angle_deg, 1),
+                    "extent_mm": round(c.extent_mm, 1),
+                    "fill_time_s": round(c.fill_time_s, 3),
+                }
+                for c in self.weld_clusters
+            ],
+            "last_fill_axis_pos": round(self.last_fill_axis_pos, 3),
+        }
+
+
+def analyze(
+    path: str | Path, gate_positions_mm: list[list[float]] | None = None, *, k: int = 10, long_axis: int = 1
+) -> Analysis:
+    """Read one prediction file and derive every gating metric from it.
+
+    Args:
+        path: A ``*_prediction.h5`` written by the cloud AI filling solver.
+        gate_positions_mm: Gate coordinates used for the run. Carried through for
+            reporting only; they change no metric.
+        k: Neighbours per node in the graph weld detection runs on.
+        long_axis: Coordinate column treated as the part's long axis.
+    """
+    path = Path(path)
+    with h5py.File(path, "r") as f:
+        coords = read_coords(f)
+        t_fill, reached, times = fill_time(f)
+        pmax = max_pressure_bar(f)
+        smax = max_shear_rate(f)
+    knn = knn_indices(coords, k=k)
+    score, angle, clusters = detect_welds(coords, t_fill, knn, times, long_axis=long_axis)
+    bal = fill_balance(t_fill, reached)
+    last_cen, last_pos = last_filled_region(coords, t_fill, reached, long_axis=long_axis)
+    fill_pct = 100.0 * float(reached.mean())
+    return Analysis(
+        path=path,
+        max_pressure_bar=pmax,
+        max_shear_rate_1s=smax,
+        fill_pct=fill_pct,
+        short_shot=fill_pct < 99.0,
+        total_fill_time_s=bal["total_fill_time_s"],
+        tail_fraction=bal["tail_fraction"],
+        n_welds=len(clusters),
+        weld_clusters=clusters,
+        last_fill_axis_pos=last_pos,
+        last_fill_centroid=last_cen,
+        gate_positions_mm=gate_positions_mm or [],
+        long_axis=long_axis,
+    )
+
+
+if __name__ == "__main__":
+    import sys
+
+    p = sys.argv[1]
+    a = analyze(p)
+    print(a.summary())
+    import json
+
+    print(json.dumps(a.as_dict(), indent=2))