loadpath 0.1.1__py3-none-any.whl

loadpath/verify.py

@@ -0,0 +1,1215 @@
+"""
+Check the part we actually deliver, not the density field we optimized.
+
+The final mesh differs from the optimizer's field (smoothing, the exact
+booleans, dropped fragments), so verification re-voxelizes the mesh,
+runs a fresh linear static analysis at the material's real modulus for every
+load case, and measures geometry with exact booleans:
+
+- mass, and how much lighter than the solid design space it is;
+- peak von Mises stress per load case and the safety factor against the
+  material's strength;
+- deflection at the loads;
+- fatigue life, creep and bolt-preload relaxation for load cases that
+  repeat or are held (durability.py);
+- keep-out intrusion and preserve loss (mm^3, from booleans: both should be
+  zero to rounding);
+- body count and thinnest member.
+
+Stress next to where loads and supports are applied is excluded from the
+peak. A load spread over a few nodes is a modeling idealization, and the
+stress it produces there is a property of the idealization, not of the
+part; every FEA package has the same caveat. Everything else counts.
+"""
+from __future__ import annotations
+
+import threading
+import time
+
+import numpy as np
+from scipy import ndimage
+
+from .domain import boundary_conditions, gravity_force
+from .fem import HexMesh, Solver, Stiffness, von_mises
+from .spec import Study
+
+__all__ = ["voxelize", "verify_part"]
+
+STRESS_ALLOWANCE = 1.15
+
+
+def voxelize(mesh, pitch: float, box=None, fractional=False):
+    """Solid cells of a closed mesh by ray parity along +z through each
+    column of cell centers. Returns (bool grid, origin = min corner of cell
+    (0,0,0)). `box` = (lo, hi) voxelizes only that region (the rays still
+    start below the whole mesh, so parity is right). `fractional` returns
+    each cell's filled share instead (float grid): the z overlap is exact
+    from the ray's crossings, averaged over 3 x 3 sub-columns per cell."""
+    if fractional:
+        return _voxel_fractions(mesh, pitch, box)
+    mlo = np.asarray(mesh.bounds, float)[0]
+    lo, hi = (np.asarray(b, float) for b in box) if box is not None else np.asarray(mesh.bounds, float)
+    # a box a whole number of cells across (a design grid's) must come out
+    # that many: (hi - lo) / pitch rounds to just over n at some pitches
+    # (the arm link's 57 cells read 58 at 2.887 mm, and its access report
+    # failed on the shape mismatch)
+    dims = np.maximum(np.ceil((hi - lo) / pitch - 1e-6).astype(int), 1)
+    origin = lo - 0.5 * (dims * pitch - (hi - lo))
+    xs = origin[0] + (np.arange(dims[0]) + 0.5) * pitch
+    ys = origin[1] + (np.arange(dims[1]) + 0.5) * pitch
+    gx, gy = np.meshgrid(xs, ys, indexing="ij")
+    # A hair of jitter keeps rays off exact edges and vertices, where a hit
+    # could be reported twice and flip the parity.
+    jit = pitch * 1e-4
+    ray_o = np.stack([gx.ravel() + 0.37 * jit, gy.ravel() + 0.61 * jit,
+                      np.full(gx.size, mlo[2] - pitch)], axis=1)
+    ray_d = np.tile([0.0, 0.0, 1.0], (len(ray_o), 1))
+    locs, ray_idx, _ = mesh.ray.intersects_location(ray_o, ray_d, multiple_hits=True)
+    if len(ray_idx) == 0 and len(mesh.faces):
+        # A mesh handed back from a worker process (GRIP's turret) answered
+        # no ray at all, where the same mesh saved and reloaded answers
+        # 16,740: rebuild it fresh, with a fresh intersector, and ask again.
+        import trimesh
+
+        fresh = trimesh.Trimesh(np.array(mesh.vertices, float), np.array(mesh.faces), process=False)
+        locs, ray_idx, _ = fresh.ray.intersects_location(ray_o, ray_d, multiple_hits=True)
+    locs = np.asarray(locs, float).reshape(-1, 3)
+    ray_idx = np.asarray(ray_idx, int).reshape(-1)
+    zc = origin[2] + (np.arange(dims[2]) + 0.5) * pitch
+    solid = np.zeros(dims, bool)
+    order = np.lexsort((locs[:, 2], ray_idx))
+    ray_idx, zs = ray_idx[order], locs[order, 2]
+    starts = np.searchsorted(ray_idx, np.arange(len(ray_o)))
+    ends = np.searchsorted(ray_idx, np.arange(len(ray_o)), side="right")
+    for r in np.nonzero(ends > starts)[0]:
+        z = zs[starts[r]:ends[r]]
+        # Merge near-duplicate hits (shared edges) before pairing.
+        if len(z) > 1:
+            z = z[np.concatenate([[True], np.diff(z) > 1e-7])]
+        if len(z) % 2:
+            z = z[:-1]
+        inside = np.zeros(dims[2], bool)
+        for a, b in z.reshape(-1, 2):
+            inside |= (zc > a) & (zc < b)
+        i, j = np.unravel_index(r, (dims[0], dims[1]))
+        solid[i, j] = inside
+    return solid, origin
+
+
+def _voxel_fractions(mesh, pitch, box=None, sub=3):
+    lo, hi = (np.asarray(b, float) for b in box) if box is not None else np.asarray(mesh.bounds, float)
+    dims = np.maximum(np.ceil((hi - lo) / pitch - 1e-6).astype(int), 1)
+    origin = lo - 0.5 * (dims * pitch - (hi - lo))
+    # the sub-columns are one bool grid at pitch/sub in x and y; each z
+    # interval's overlap with each cell is added exactly
+    mlo = np.asarray(mesh.bounds, float)[0]
+    fine = np.array([dims[0] * sub, dims[1] * sub])
+    xs = origin[0] + (np.arange(fine[0]) + 0.5) * pitch / sub
+    ys = origin[1] + (np.arange(fine[1]) + 0.5) * pitch / sub
+    gx, gy = np.meshgrid(xs, ys, indexing="ij")
+    jit = pitch * 1e-4
+    ray_o = np.stack([gx.ravel() + 0.37 * jit, gy.ravel() + 0.61 * jit,
+                      np.full(gx.size, mlo[2] - pitch)], axis=1)
+    locs, ray_idx, _ = mesh.ray.intersects_location(ray_o, np.tile([0.0, 0.0, 1.0], (len(ray_o), 1)),
+                                                    multiple_hits=True)
+    locs = np.asarray(locs, float).reshape(-1, 3)
+    ray_idx = np.asarray(ray_idx, int).reshape(-1)
+    order = np.lexsort((locs[:, 2], ray_idx))
+    ray_idx, zs = ray_idx[order], locs[order, 2]
+    starts = np.searchsorted(ray_idx, np.arange(len(ray_o)))
+    ends = np.searchsorted(ray_idx, np.arange(len(ray_o)), side="right")
+    z0 = origin[2] + np.arange(dims[2]) * pitch
+    frac = np.zeros(dims, float)
+    for r in np.nonzero(ends > starts)[0]:
+        z = zs[starts[r]:ends[r]]
+        if len(z) > 1:
+            z = z[np.concatenate([[True], np.diff(z) > 1e-7])]
+        if len(z) % 2:
+            z = z[:-1]
+        cover = np.zeros(dims[2])
+        for a, b in z.reshape(-1, 2):
+            cover += np.clip(np.minimum(b, z0 + pitch) - np.maximum(a, z0), 0.0, pitch)
+        i, j = np.unravel_index(r, (fine[0], fine[1]))
+        frac[i // sub, j // sub] += cover
+    return np.clip(frac / (pitch * sub * sub), 0.0, 1.0), origin
+
+
+def _thickness(solid, pitch):
+    """Member thickness on the medial ridge: twice the distance to void at
+    cells that are local maxima of that distance."""
+    edt = ndimage.distance_transform_edt(np.pad(solid, 1))[1:-1, 1:-1, 1:-1]
+    ridge = solid & (edt >= ndimage.maximum_filter(edt, size=3)) & (edt > 0)
+    # A ridge cell's distance to void is ceil(n/2) for a member n cells
+    # thick, so 2*edt over-reads odd and 2*edt-1 under-reads even
+    # thicknesses by a whole cell; 2*edt-0.5 is within half a cell of both.
+    vals = (2.0 * edt[ridge] - 0.5) * pitch
+    if vals.size == 0:
+        return None, None
+    return float(vals.min()), float(np.percentile(vals, 5))
+
+
+def surface_thickness(mesh, samples: int = 6000, seed: int = 0, study: Study | None = None):
+    """Member thickness without a grid: from evenly spread surface points, a
+    ray straight in along the inward normal to where it leaves the part (the
+    shape diameter). Returns (p1, p5) in mm. The voxel ridge reading
+    (_thickness) is quantized to the analysis cell, under-reading a 2.05 mm
+    wall at a 0.98 mm pitch as 1.46; this one is not, but it costs a ray
+    cast per sample, so it is for scoring a finished part, not every outcome.
+    With the study, a ray that both enters and leaves on the user's own
+    surfaces (preserved or keep-out) is left out: that thickness is the
+    study's, not the optimizer's (GRIP's wrist yoke: its J5 servo sits 1.9 mm
+    above the J4 horn, so the preserved horn plate between them is 1.9 mm)."""
+    import trimesh
+
+    # a fresh, merged copy: a part straight from the booleans can carry
+    # degenerate slivers whose bounds break the ray tree (the motor mount)
+    mesh = trimesh.Trimesh(np.array(mesh.vertices, float), np.array(mesh.faces), process=True)
+    mesh.update_faces(mesh.nondegenerate_faces())
+    pts, fi = trimesh.sample.sample_surface_even(mesh, samples, seed=seed)
+    n = mesh.face_normals[fi]
+    ok = np.isfinite(pts).all(axis=1) & (np.linalg.norm(n, axis=1) > 0.5)
+    pts, n = pts[ok], n[ok]
+    origin = pts - n * 1e-3
+    # in batches: without embree the ray tree's candidate pairs for all 6000
+    # rays at once took 7 GB on a 75k-face yoke (the cloud box OOMed)
+    hits = [mesh.ray.intersects_location(origin[k:k + 500], -n[k:k + 500], multiple_hits=False)[:2]
+            for k in range(0, len(origin), 500)]
+    loc = np.concatenate([h[0].reshape(-1, 3) for h in hits]) if hits else np.zeros((0, 3))
+    ri = np.concatenate([h[1] + k for h, k in zip(hits, range(0, len(origin), 500))]).astype(int) if hits else np.zeros(0, int)
+    if len(ri) == 0:
+        return None, None
+    d = np.linalg.norm(loc - origin[ri], axis=1)
+    if study is not None:
+        shapes = [r.shape for r in list(study.preserve) + list(study.keep_out)]
+        if shapes:
+            def on_user(q):
+                return np.min([np.abs(sh.sdf(q)) for sh in shapes], axis=0) < 0.05
+            mine = ~(on_user(pts[ri]) & on_user(loc))
+            if mine.any():
+                d = d[mine]
+    return float(np.percentile(d, 1)), float(np.percentile(d, 5))
+
+
+def nodal_von_mises(stiff, u, modulus, thermal=None):
+    """Von Mises at the nodes: each element's stress evaluated at its own
+    corners, averaged over the elements sharing a node. Element-centre stress
+    sits half a cell inside the surface, which is exactly where stress
+    concentrates; on a plate with a hole (Peterson Kt_net = 2.43, peak 81 MPa)
+    centre values read 64-74 MPa and neighbor-smoothed centres 59-68, while
+    nodal averages read 73 at 7 cells per hole radius and 81.7 from 9 cells
+    up, converged. Averaging across elements is also what keeps a single
+    voxel staircase corner from reading as a spike."""
+    return von_mises(nodal_stress(stiff, u, modulus, thermal))
+
+
+def nodal_stress(stiff, u, modulus, thermal=None):
+    """The nodal-averaged stress tensor (sx, sy, sz, txy, tyz, tzx), as
+    nodal_von_mises averages it. `modulus` is one number or one per element;
+    `thermal` (per element) is a free expansion strain, taken off the strain
+    before the stress is formed."""
+    from .fem import CORNERS, elastic_c, hex8_b
+
+    cg = getattr(stiff, "cutgrid", None)
+    if cg is not None:
+        return cg.nodal_stress(u, modulus, thermal)
+    mesh = stiff.mesh
+    c = elastic_c(1.0, stiff.nu)
+    element = getattr(stiff, "element", None)
+    mod = np.broadcast_to(np.asarray(modulus, float), (mesh.n_elem,))[:, None]
+    ue = u[mesh.edof]
+    acc = np.zeros((mesh.n_nodes, 6))
+    for k, (a, b, cc) in enumerate(2.0 * CORNERS - 1.0):
+        strain = ue @ (hex8_b(a, b, cc, stiff.nu, element) / mesh.pitch).T
+        if thermal is not None:
+            strain[:, :3] -= np.asarray(thermal, float)[:, None]
+        np.add.at(acc, mesh.enode[:, k], (strain @ c.T) * mod)
+    cnt = np.bincount(mesh.enode.ravel(), minlength=mesh.n_nodes)
+    return acc / cnt[:, None]
+
+
+# mm above the lowest point that still counts as standing on the build plate
+_PLATE_BAND = 1.0
+
+
+def _overhang(mesh, direction, study=None, max_angle_deg=45.0, tolerance_deg=5.0):
+    """Down-facing surface that needs support: faces whose normal is within
+    (max_angle - tolerance) of straight down, i.e. ceilings and slopes
+    shallower than the self-supporting limit, excluding the face on the build
+    plate and the rounded bottom edge within 1 mm of it (a few layers, which
+    print without support; marching cubes rounds every edge on the plate, and
+    on the printed hook the 0.5-1 mm band alone was a point of its 4.3%). The
+    tolerance keeps marching-cubes facets on a true 45-degree
+    slope from counting. `overhangArea` is everything; `designOverhangArea`
+    leaves out faces on preserved or keep-out geometry, which the user drew
+    (a horizontal bore's ceiling is theirs, not the optimizer's)."""
+    from .am import build_vector
+
+    up = build_vector(direction)
+    down = -(mesh.face_normals @ up)
+    centers = mesh.triangles_center
+    height = centers @ up
+    bad = (down > np.cos(np.radians(max_angle_deg - tolerance_deg))) & (height > height.min() + _PLATE_BAND)
+    area = float(mesh.area_faces[bad].sum())
+    out = {"overhangArea": area, "overhangFraction": area / float(mesh.area)}
+    if study is not None:
+        drawn = np.zeros(len(centers), bool)
+        for r in study.preserve + study.keep_out:
+            drawn |= np.abs(r.shape.sdf(centers)) < 0.6
+        d_area = float(mesh.area_faces[bad & ~drawn].sum())
+        out["designOverhangArea"] = d_area
+        out["designOverhangFraction"] = d_area / float(mesh.area)
+    return out
+
+
+def _boundary_cut_area(study: Study, mesh) -> float:
+    """mm^2 of the part's surface lying flat on a face of a box design space,
+    away from every support and preserved shape: organic material sawn off
+    where the design box happened to end, not where anything mates. Zero on
+    a clean result (GRIP's wrist yoke QA, 10/28)."""
+    from .shapes import Box
+
+    boxes = [d for d in study.design_space if isinstance(d, Box)]
+    if not boxes:
+        return 0.0
+    c = mesh.triangles_center
+    nrm = mesh.face_normals
+    area = mesh.area_faces
+    keep = [r.shape for r in study.preserve]
+    for sup in study.supports:
+        try:
+            keep.append(sup.shape if sup.shape is not None else study.region_shape(sup.region)[0])
+        except ValueError:
+            pass
+    near = np.min([k.sdf(c) for k in keep], axis=0) < 1.0 if keep else np.zeros(len(c), bool)
+    cut = np.zeros(len(c), bool)
+    for b in boxes:
+        for ax in range(3):
+            for side, plane in ((-1, b.lo[ax]), (1, b.hi[ax])):
+                cut |= (np.abs(c[:, ax] - plane) < 0.05) & (nrm[:, ax] * side > 0.99)
+    return float(area[cut & ~near].sum())
+
+
+# A concave edge sharper than this (the faces turn by more than 60 degrees)
+# is a crease: a notch that concentrates stress and that a fillet should have
+# rounded. Marching-cubes facets on an organic surface turn by a few degrees.
+CREASE_ANGLE_DEG = 60.0
+
+
+def _creases(study: Study, mesh, angle_deg: float = CREASE_ANGLE_DEG) -> dict:
+    """Sharp concave edges the optimizer made: where an organic member meets
+    preserved geometry without a fillet, or two members meet in a notch.
+    GRIP's wrist yoke passed every number with hard creases at its bosses,
+    found only by zooming in (QA, 10/28); this measures them. Edges lying on
+    keep-out surfaces (a blind bore's floor) or between two faces of the
+    user's own preserved geometry are the user's, and are left out.
+    Returns crease length (mm) and up to five crease locations."""
+    ang = mesh.face_adjacency_angles
+    sharp = (~mesh.face_adjacency_convex) & (ang > np.radians(angle_deg))
+    out = {"creaseLength": 0.0, "creaseAt": []}
+    if not sharp.any():
+        return out
+    e = mesh.face_adjacency_edges[sharp]
+    a, b = mesh.vertices[e[:, 0]], mesh.vertices[e[:, 1]]
+    mid = 0.5 * (a + b)
+    length = np.linalg.norm(b - a, axis=1)
+    users = np.zeros(len(mid), bool)
+    if study.keep_out:
+        users |= np.min([np.abs(r.shape.sdf(mid)) for r in study.keep_out], axis=0) < 0.3
+    if study.preserve:
+        fc = mesh.triangles_center[mesh.face_adjacency[sharp]]          # (n, 2, 3)
+        on = np.min([np.abs(r.shape.sdf(fc.reshape(-1, 3))) for r in study.preserve], axis=0).reshape(-1, 2)
+        users |= (on < 0.05).all(axis=1)
+    mine = ~users
+    out["creaseLength"] = float(length[mine].sum())
+    pts = mid[mine]
+    w = length[mine]
+    while len(pts) and len(out["creaseAt"]) < 5:
+        # heaviest cluster first, 5 mm across
+        i = int(np.argmax([w[np.linalg.norm(pts - p, axis=1) < 5.0].sum() for p in pts]))
+        near = np.linalg.norm(pts - pts[i], axis=1) < 5.0
+        out["creaseAt"].append({"at": pts[near].mean(axis=0).round(2).tolist(), "length": float(w[near].sum())})
+        pts, w = pts[~near], w[~near]
+    return out
+
+
+def _closed_bores(study: Study, mesh) -> list:
+    """Cylindrical keep-outs (bores) with an end the part closes over.
+
+    A fastener needs its whole path clear: the shank through the bore, and
+    the head, washer and driver out past its end. A bore that stops inside
+    material is a blind hole no screw can be driven through, the way the
+    wall bracket's screw holes came out capped (and GRIP's yoke had material
+    over its bolt seats). The fix is in the study: extend the keep-out over
+    the head and the driver's reach. Probes a short way past each end cap,
+    on the axis and on a ring at 0.3 of the radius; an end is closed when
+    most probes land inside the part. A keep-out marked "bore": false (a
+    clearance volume that may end against material) is not checked."""
+    from .shapes import Cylinder
+
+    out = []
+    for r in study.keep_out:
+        if not r.bore:
+            continue
+        sh = r.shape
+        if not isinstance(sh, Cylinder) or sh.r_inner > 0:
+            continue
+        a = sh.axis
+        u = np.cross(a, [1.0, 0.0, 0.0] if abs(a[0]) < 0.9 else [0.0, 1.0, 0.0])
+        u /= np.linalg.norm(u)
+        v = np.cross(a, u)
+        # on and near the axis only: a head-clearance bore ending on its
+        # seat is closed round the rim by design, with the screw's own
+        # narrower bore running on through the middle (the motor mount's
+        # access holes); a capped hole is closed across the middle too
+        ring = [np.zeros(3)] + [0.3 * sh.r * (np.cos(t) * u + np.sin(t) * v)
+                                for t in np.linspace(0, 2 * np.pi, 6, endpoint=False)]
+        for end, cap, out_dir in (("p0", sh.p0, -a), ("p1", sh.p1, a)):
+            probes = np.array([cap + d * out_dir + o for d in (1.5, 3.0) for o in ring])
+            inside = mesh.contains(probes)
+            if inside.mean() > 0.5:
+                out.append({"id": r.id, "end": end, "at": cap.round(2).tolist()})
+    return out
+
+
+def _union(shapes):
+    import manifold3d as m3d
+
+    from .sharp import exact_manifold
+    # the same exact solids reconstruct.py cut and added (circles 0.002 mm true)
+    mans = [exact_manifold(s) for s in shapes]
+    if not mans:
+        return None
+    return m3d.Manifold.batch_boolean(mans, m3d.OpType.Add) if len(mans) > 1 else mans[0]
+
+
+def _hotspots(xyz, vm, body, peak, radius, count=3):
+    """Up to `count` local stress maxima at least 2*radius apart, among nodes
+    within half of the peak."""
+    order = np.argsort(-np.where(body, vm, -1.0))
+    picked = []
+    for i in order:
+        if not body[i] or vm[i] < 0.5 * peak or len(picked) >= count:
+            break
+        if all(np.linalg.norm(xyz[i] - xyz[j]) >= 2 * radius for j in picked):
+            picked.append(i)
+    return [xyz[i] for i in picked]
+
+
+# A wetted wall is a voxel staircase: the stress at its nodes alternates
+# between the step's teeth (unloaded corners, low) and its re-entrant corners
+# (high), and refining the grid does not settle it, the staircase being the
+# same shape at every pitch. On a closed cylinder under pressure (r 20, wall
+# 3, Lamé 7.10 MPa at the bore) the wetted nodes read 5.6 at the median and
+# 8.6-9.2 at the peak from 2.5 to 5 cells through the wall; averaged over the
+# wetted nodes within 1.5 cells of each, the peak reads 7.6-7.9, the real
+# wall's to within the discretization allowance.
+_WET_SMOOTH = 1.5
+# cells through the thinnest pinned wall or skin (study.shells), and the most
+# cells verification will spend getting there
+_SHELL_CELLS = 4.0
+_SHELL_MAX_CELLS = 400_000
+
+
+def _smooth_wetted(xyz, vm, wet, pitch):
+    """von Mises at wetted nodes averaged over the wetted nodes near each."""
+    from scipy.spatial import cKDTree
+
+    idx = np.nonzero(wet)[0]
+    if len(idx) == 0:
+        return vm
+    import scipy.sparse as sp
+
+    tree = cKDTree(xyz[idx])
+    pairs = tree.query_pairs(_WET_SMOOTH * pitch, output_type="ndarray")
+    n = len(idx)
+    rows = np.concatenate([pairs[:, 0], pairs[:, 1], np.arange(n)])
+    cols = np.concatenate([pairs[:, 1], pairs[:, 0], np.arange(n)])
+    m = sp.csr_matrix((np.ones(len(rows)), (rows, cols)), shape=(n, n))
+    out = vm.copy()
+    out[idx] = (m @ vm[idx]) / np.asarray(m.sum(axis=1)).ravel()
+    return out
+
+
+def _rigid_free(xyz, u):
+    """u less its best-fit rigid motion (least squares over the nodes): the
+    deformation of a part held only by a 3-2-1 support."""
+    from .fem import rigid_body_modes
+
+    b = rigid_body_modes(xyz)
+    coef = np.linalg.lstsq(b, u, rcond=None)[0]
+    return u - b @ coef
+
+
+def _user_edges(study: Study, band: float):
+    """Where a keep-out's surface meets a preserved body's (a screw-head
+    counterbore's floor corner on a boss face, a bore's rim): a sharp edge
+    the user drew, which the optimizer cannot round. Its linear-elastic stress
+    grows without bound as the grid gets finer, like a clamped edge's, so it
+    is left out of the peak over the same band. (The wall bracket's 150k-cell
+    confirm check peaked there and read SF 1.6, 2.6, 2.5, 1.9, 3.7 at 11.5-15%
+    of the space, out of order, against 2.7-3.8 on the 60k check.)
+
+    Being near both surfaces is not enough: a pressure vessel's wall, or a
+    ring whose bore is the keep-out's, lines the keep-out, and the two
+    surfaces coincide over the whole cavity (a thick sphere's bore, Lame's
+    peak, was left out entirely). An edge is where the surfaces cross
+    (their normals not opposed) or where the keep-out's own surface turns
+    within the band (a tunnel's rim on the face it ends on). Returns a
+    function of points -> bool, or None when the study has no such edges."""
+    keep = [r.shape for r in study.keep_out]
+    pres = [r.shape for r in study.preserve]
+    if not keep or not pres:
+        return None
+    h = 0.05 * band
+    axes = np.eye(3)
+
+    def sdf(shapes, xyz):
+        return np.min([sh.sdf(xyz) for sh in shapes], axis=0)
+
+    def normal(shapes, xyz):
+        g = np.stack([sdf(shapes, xyz + h * a) - sdf(shapes, xyz - h * a) for a in axes], axis=1)
+        return g / np.maximum(np.linalg.norm(g, axis=1, keepdims=True), 1e-12)
+
+    def near(xyz):
+        xyz = np.asarray(xyz, float)
+        out = (np.abs(sdf(keep, xyz)) < band) & (np.abs(sdf(pres, xyz)) < band)
+        if not out.any():
+            return out
+        x = xyz[out]
+        nk = normal(keep, x)
+        edge = np.einsum("ij,ij->i", nk, normal(pres, x)) > -0.9
+        for o in np.concatenate([axes, -axes]) * band:
+            edge |= np.einsum("ij,ij->i", nk, normal(keep, x + o)) < 0.9
+        out[out] = edge
+        return out
+    return near
+
+
+# trimesh's ray/contains queries share the mesh's rtree, which is not
+# thread-safe (concurrent queries corrupt its node reads: "RTreeError:
+# readNode"); the submodels' voxelizing takes turns, their solves overlap
+_MESH_QUERY = threading.Lock()
+
+
+def _submodel_peak(study, mesh, hm, u, center, half, pitch, mat, contact_xyz, band, case=None, edges=None,
+                   cut=False):
+    """Re-solve a small box around a global hotspot at a finer pitch, driven by
+    the global displacement field on the box's cut faces (classic FE
+    submodeling). Voxel stress converges only with about 8 cells across a
+    feature's radius; the global grid rarely affords that, the box does.
+    Returns (peak MPa, position) or None."""
+    from scipy.spatial import cKDTree
+
+    lo, hi = center - half, center + half
+    cgrid = None
+    with _MESH_QUERY:
+        if cut:
+            from .cutcell import cut_from_mesh
+
+            cgrid = cut_from_mesh(mesh, pitch, study.elastic(mat), box=(lo, hi))
+            solid, origin = cgrid.solid_grid()
+        else:
+            solid, origin = voxelize(mesh, pitch, box=(lo, hi))
+    if solid.sum() < 64:
+        return None
+    sm = cgrid.mesh if cgrid is not None else HexMesh(np.argwhere(solid), pitch, origin)
+    blo = origin
+    bhi = origin + np.asarray(solid.shape) * pitch
+    eps = 0.25 * pitch
+    cut = np.any((sm.node_xyz < blo + eps) | (sm.node_xyz > bhi - eps), axis=1)
+    near_contact = np.zeros(sm.n_nodes, bool)
+    if len(contact_xyz):
+        near_contact = cKDTree(contact_xyz).query(sm.node_xyz, k=1, distance_upper_bound=band)[0] < np.inf
+    driven = cut | near_contact
+    if driven.all() or not driven.any():
+        return None
+    # Global displacement at the driven nodes: inverse-distance weights over
+    # the nearest global nodes (the field is smooth at this scale).
+    gd, gi = cKDTree(hm.node_xyz).query(sm.node_xyz[driven], k=8)
+    w = 1.0 / np.maximum(gd, 1e-9) ** 2
+    w /= w.sum(axis=1, keepdims=True)
+    ug = u.reshape(-1, 3)[gi]
+    up = (w[..., None] * ug).sum(axis=1).ravel()
+    pd = np.repeat(driven, 3)
+    st = Stiffness(sm, study.elastic(mat), np.zeros(sm.n_dof, bool))
+    k = (cgrid.assemble(st, mat.E) if cgrid is not None else st.assemble(np.full(sm.n_elem, mat.E))).tocsr()
+    free = ~pd
+    kff = k[free][:, free]
+    rhs = -(k[free][:, pd] @ up)
+    if case is not None:
+        # a pressure inside the box pushes on its walls here too
+        from .pressure import pressure_force
+
+        fp = np.zeros(sm.n_dof)
+        for ld in case.loads:
+            if ld.pressure:
+                fp += pressure_force(sm, study.region_shape(ld.region)[0], ld.pressure)[0]
+        rhs = rhs + fp[free]
+    solver = Solver(sm, rtol=1e-7, maxiter=4000)
+    # Rigid-body modes are pinned by the driven nodes; AMG still wants a
+    # near-null space sized to the free unknowns, so use plain CG+AMG on kff.
+    from scipy.sparse.linalg import cg
+
+    from .fem import amg_solver
+    ml = amg_solver(kff, symmetry="hermitian", strength="symmetric", max_coarse=400, coarse_solver="splu")
+    uf, info = cg(kff, rhs, rtol=1e-7, maxiter=4000, M=ml.aspreconditioner(cycle="V"))
+    del solver
+    if info != 0:
+        return None
+    us = np.zeros(sm.n_dof)
+    us[pd] = up
+    us[free] = uf
+    vm = von_mises(cgrid.nodal_stress(us, mat.E)) if cgrid is not None else nodal_von_mises(st, us, mat.E)
+    if case is not None and fp.any():
+        # over the global grid's reach: a finer staircase is no smoother
+        vm = _smooth_wetted(sm.node_xyz, vm, np.abs(fp.reshape(-1, 3)).sum(axis=1) > 0, hm.pitch)
+    # Trust the inside of the box only: two global cells from the cut faces.
+    margin = 2.0 * hm.pitch
+    inner = np.all((sm.node_xyz > blo + margin) & (sm.node_xyz < bhi - margin), axis=1) & ~near_contact
+    if edges is not None:
+        inner &= ~edges(sm.node_xyz)
+    if not inner.any():
+        return None
+    i = int(np.argmax(np.where(inner, vm, -1.0)))
+    return float(vm[i]), sm.node_xyz[i].tolist()
+
+
+
+def _inside(mesh, pts, rng):
+    """Point-in-solid by ray-crossing parity (odd = inside): a ray along +x,
+    tilted a little at random so edge and vertex grazes are measure-zero,
+    tested exactly (Moller-Trumbore) against the triangles whose y-z box it
+    can pass through. trimesh's own test (no embree) took 80 s of a 90 s
+    verify on the arm link."""
+    tri = np.asarray(mesh.triangles, float)
+    v0, e1, e2 = tri[:, 0], tri[:, 1] - tri[:, 0], tri[:, 2] - tri[:, 0]
+    lo, hi = tri.min(axis=1), tri.max(axis=1)
+    span = float(np.ptp(tri[..., 0])) + 1.0
+    out = np.zeros(len(pts), bool)
+    for i, o in enumerate(np.asarray(pts, float)):
+        tilt = rng.uniform(-1e-3, 1e-3, 2)
+        d = np.array([1.0, *tilt]) / np.sqrt(1.0 + tilt @ tilt)
+        g = np.abs(tilt) * span + 1e-9
+        c = np.flatnonzero((hi[:, 0] >= o[0]) & (lo[:, 1] <= o[1] + g[0]) & (hi[:, 1] >= o[1] - g[0])
+                           & (lo[:, 2] <= o[2] + g[1]) & (hi[:, 2] >= o[2] - g[1]))
+        if not len(c):
+            continue
+        p = np.cross(d, e2[c])
+        det = np.einsum("ij,ij->i", e1[c], p)
+        ok = np.abs(det) > 1e-12
+        inv = np.where(ok, 1.0 / np.where(ok, det, 1.0), 0.0)
+        tv = o - v0[c]
+        u = np.einsum("ij,ij->i", tv, p) * inv
+        q = np.cross(tv, e1[c])
+        v = (q @ d) * inv
+        t = np.einsum("ij,ij->i", q, e2[c]) * inv
+        out[i] = int((ok & (u >= 0) & (v >= 0) & (u + v <= 1) & (t > 1e-9)).sum()) % 2 == 1
+    return out
+
+
+def _preserve_missing(pres_eff, part, mesh, samples: int = 400) -> float:
+    """Volume of preserved geometry the part lacks (mm^3). The boolean finds
+    candidate pieces; each is then confirmed by sampling points inside it and
+    asking the mesh itself (by ray parity) whether they are solid. Where a
+    keep-out shares a preserved surface (a bore the size of a boss's inner
+    wall), manifold3d can report slivers of the preserved shape missing from
+    a part that, point by point, has them: the grip upper arm's elbow socket
+    read 300 mm^3 short with every sampled point inside."""
+    from .shapes import trimesh_from_manifold
+
+    rng = np.random.default_rng(0)
+    total = 0.0
+    for b in (pres_eff - part).decompose():
+        v = b.volume()
+        if v <= 1e-3:
+            continue
+        tb = trimesh_from_manifold(b)
+        lo, hi = tb.bounds
+        pts = np.empty((0, 3))
+        for n in (samples, 20 * samples):     # rejection sampling in the piece's box
+            cand = lo + rng.random((n, 3)) * (hi - lo)
+            pts = cand[_inside(tb, cand, rng)][:samples]
+            if len(pts) >= 10:
+                break
+        if len(pts) < 10:
+            # too thin a sliver for sampling to land in: missing only if it
+            # is thicker than a print resolves (thickness ~ 2 V / A)
+            total += v if 2.0 * v / max(b.surface_area(), 1e-9) > 0.1 else 0.0
+            continue
+        total += v * float((~_inside(mesh, pts, rng)).mean())
+    return total
+
+
+def use_cut_cells(study, cut_cells=None) -> bool:
+    """Whether verification analyzes cut cells: the argument, else
+    LOADPATH_CUT_CELLS (1/0), else the study's resolution.cutCells, else
+    yes unless the study carries a pressure."""
+    import os
+
+    if cut_cells is not None:
+        return bool(cut_cells)
+    env = os.environ.get("LOADPATH_CUT_CELLS", "").strip().lower()
+    if env in ("1", "true", "yes", "on"):
+        return True
+    if env in ("0", "false", "no", "off"):
+        return False
+    asked = (getattr(study, "raw", None) or {}).get("resolution", {}).get("cutCells")
+    if asked is not None:
+        return bool(asked)
+    # Default on, but not under pressure: a pressure's wetted nodes come
+    # from the whole-cell staircase, and on a cut grid they sit off the
+    # true wall (the thick sphere read Lame's 21 MPa as 105).
+    return not any(ld.pressure for case in getattr(study, "load_cases", ()) for ld in case.loads)
+
+
+def _solve_cut(cg, nu, fixed, springs, e_mat, moduli, rhs):
+    """Solve the cut-cell model (cutcell.CutGrid) for each right-hand side:
+    the shared-matrix cells as usual, the cut cells' own matrices added
+    (assembled), or as the multigrid's extra operator, which its Galerkin
+    coarsening carries down exactly. Returns (stiffness object with
+    .cutgrid, displacements)."""
+    from .simp import _use_mg
+
+    hm = cg.mesh
+    if _use_mg(hm.n_elem):
+        from .mg import GridElasticity
+
+        extra = cg.cut_operator(moduli)
+        if springs is not None:
+            extra = (extra + e_mat * springs).tocsr()
+        stiff = GridElasticity(hm, nu, fixed, springs=extra, rtol=1e-6, maxiter=3000)
+        stiff.set_moduli(cg.full_moduli(moduli))
+    else:
+        stiff = Stiffness(hm, nu, fixed)
+        k = cg.assemble(stiff, moduli)
+        if springs is not None:
+            k = (k + e_mat * springs).tocsr()
+        solver = Solver(hm, rtol=1e-6, maxiter=3000, rebuild_after_iters=10_000)
+        stiff.cutgrid = cg
+        return stiff, solver.solve_many(k, rhs)
+    stiff.cutgrid = cg
+    return stiff, stiff.solve_many(rhs)
+
+
+# cells through a member below which it gets a submodel (cut cells)
+_THIN_CELLS = 3.0
+
+
+def _thin_spots(hm, solid, origin, pitch, vm, body, peak, radius, taken, count=3):
+    """Hotspots on members under _THIN_CELLS cells thick reading at least
+    0.8 of the peak, at least 2 * radius from each other and from `taken`."""
+    edt = ndimage.distance_transform_edt(np.pad(solid, 1))[1:-1, 1:-1, 1:-1]
+    # a cell's member thickness: twice the largest distance to void nearby
+    thick = 2.0 * ndimage.maximum_filter(edt, size=5) - 0.5
+    thin_el = thick[tuple(hm.elem_ijk.T)] < _THIN_CELLS
+    thin = np.zeros(hm.n_nodes, bool)
+    thin[hm.enode[thin_el].ravel()] = True
+    cand = body & thin & (vm >= 0.8 * peak)
+    out = []
+    for i in np.argsort(-np.where(cand, vm, -1.0)):
+        if not cand[i] or len(out) >= count:
+            break
+        x = hm.node_xyz[i]
+        if all(np.linalg.norm(x - y) >= 2 * radius for y in list(taken) + out):
+            out.append(x)
+    return out
+
+
+# Buckling is read on a grid of at most this many cells. The eigensolver
+# factors the stiffness once and solves with it every iteration, so the cost
+# grows fast with size: the 23 g wall bracket took 11 s at 5k cells, 17 s at
+# 21k and 144 s at 71k (5.7 GB). The coarse grid reads low, the safe side:
+# 1.44 / 1.54 / 1.37 at 5k / 11k / 21k cells against 1.81-1.83 at 42-71k.
+# The search verifies every outcome, so this is per outcome: at 20k cells
+# the arm link and turret spent 37-52 s each.
+BUCKLING_CELLS = 12_000
+
+
+def _buckling(study: Study, mesh, vol: float, pitch: float, contact_band: float | None,
+              directions: list) -> dict | None:
+    """The part's linear buckling load factor per load case: the multiple of
+    the case's loads at which a perfect version of it buckles (nonlinear.
+    linear_buckling, incompatible-mode hex8: a column one cell thick reads
+    Euler's load within 1%). Real parts buckle below it (imperfections), and
+    the goal's safety factor is the margin asked of it. Gravity counts; heat
+    does not; the material is read isotropic (a layered process's softer
+    across-layer stiffness is not in it). `directions` are the cases' worst force directions from the
+    stress check (None for a fixed force). None when nothing holds the part."""
+    from .directions import expand
+    from .nonlinear import linear_buckling, solid_submesh
+
+    t0 = time.time()
+    mat = study.material
+    pb = max(pitch, (vol / BUCKLING_CELLS) ** (1.0 / 3.0))
+    solid, origin = voxelize(mesh, pb)
+    hm = HexMesh(np.argwhere(solid), pb, origin)
+    bc = boundary_conditions(study, hm, check_loads=False, tol_floor=0.5 * (contact_band or 0.0) + 0.5 * pb)
+    if not bc.fixed.any() and bc.springs is None:
+        return None
+    fg = gravity_force(hm, np.ones(hm.n_elem), bc.gravity, bc.fixed) if bc.gravity is not None else None
+    spreads = bc.spreads or [None] * len(study.load_cases)
+    rhs, layout = expand(bc.loads, spreads, fg)
+    forces = []
+    for ci, case in enumerate(study.load_cases):
+        idx, d = layout[ci], directions[ci]
+        if len(idx) == 1:
+            f = rhs[idx[0]]
+        else:
+            f = sum(d[j] * rhs[i] for j, i in enumerate(idx[1:]))
+            if idx[0] is not None:
+                f = f + rhs[idx[0]]
+        forces.append(f)
+    springs = mat.E * bc.springs if bc.springs is not None else None
+    # pieces no support holds would float: left out (a pin's springs hold)
+    hold = bc.fixed.copy()
+    if springs is not None:
+        hold |= np.asarray(abs(springs).sum(axis=1)).ravel() > 0
+    sub, el, _, vecs = solid_submesh(hm, np.ones(hm.n_elem, bool), hold, [bc.fixed.astype(float)] + forces)
+    fixed, forces = vecs[0] > 0.5, vecs[1:]
+    loaded = [i for i, f in enumerate(forces) if np.any(f)]
+    cases = [{"name": c.name, "factor": None} for c in study.load_cases]
+    if sub.n_elem and loaded:
+        ks = None
+        if springs is not None:
+            dofs = (3 * hm.node_id(sub.node_ijk)[:, None] + np.arange(3)).ravel()
+            ks = springs[dofs][:, dofs].tocsr()
+        try:
+            # one factorization for every case; three to four digits of the
+            # factor are plenty (tol)
+            res = linear_buckling(sub, mat.nu, mat.E, fixed, [forces[i] for i in loaded], n_modes=1,
+                                  springs=ks, direct_max_dof=10 ** 6, tol=1e-5)
+        except (RuntimeError, ValueError, ArithmeticError) as exc:
+            for i in loaded:
+                cases[i]["error"] = str(exc)
+            res = []
+        for i, r in zip(loaded, res):
+            lam = float(r.factors[0])
+            if np.isfinite(lam):
+                mode = r.modes[0].reshape(-1, 3)
+                cases[i].update(factor=lam, modeAt=sub.node_xyz[int(np.argmax(np.linalg.norm(mode, axis=1)))].tolist())
+    got = [c["factor"] for c in cases if c["factor"] is not None]
+    return {"factor": min(got) if got else None, "cases": cases, "pitch": pb,
+            "cells": int(hm.n_elem), "seconds": time.time() - t0}
+
+
+def verify_part(study: Study, mesh, max_cells: int = 60_000, min_pitch: float | None = None,
+                contact_band: float | None = None, refine: int = 3, fields: bool = False,
+                fractional: bool = False, cut_cells: bool | None = None) -> dict:
+    """Analyze a finished part (trimesh) against the study. Returns a JSON-able
+    report. `contact_band` (mm) is how far from applied loads and supports
+    stress is left out of the peak; it defaults to 1.5 analysis cells, and the
+    study runner sets it to the optimization cell size so the excluded band
+    does not shrink toward zero as the analysis grid gets finer (a clamped
+    edge's stress grows without bound under refinement). `refine` is how many
+    hotspots per load case get a 3x finer submodel (see _submodel_peak).
+    `fields` adds report["fields"]: the analysis nodes and, per load case,
+    nodal von Mises stress and displacement (numpy arrays, not JSON) for
+    stress maps (render.render_stress); with a thermal block, also the
+    temperature per node at the hot moment. `fractional` analyzes the part's
+    surface cells at their filled share of the modulus (the stress formed at
+    the full modulus), so the readings move smoothly with the geometry
+    rather than in whole-cell steps: for searches and live previews, whose
+    neighbouring candidates must compare fairly; the delivered check is
+    whole cells. `cut_cells` (default: use_cut_cells, which is on unless
+    the study says resolution.cutCells false, LOADPATH_CUT_CELLS=0, or
+    it has a pressure load) analyzes the true boundary inside each cell
+    (cutcell.py): sub-cell stiffness, stress read on the surface, and
+    finer submodels on members under 3 cells thick; member thickness no
+    longer rounds to whole cells (GRIP's wrist link struts: whole cells
+    0.35-3.5x of fine tets, cut cells 0.74-1.13x; docs/BENCHMARKS.md)."""
+    from .shapes import manifold_from_trimesh
+
+    t0 = time.time()
+    mat = study.material
+    part = manifold_from_trimesh(mesh)
+    vol = float(part.volume())
+    report = {"volume": vol, "mass": vol * mat.density / 1000.0, "material": mat.to_dict()}
+
+    design = _union(study.design_space + [r.shape for r in study.preserve])
+    keep = _union([r.shape for r in study.keep_out])
+    pres = _union([r.shape for r in study.preserve])
+    envelope = design - keep if keep is not None else design
+    env_vol = float(envelope.volume())
+    report["designSpaceMass"] = env_vol * mat.density / 1000.0
+    report["massReduction"] = 1.0 - vol / env_vol if env_vol > 0 else None
+    report["keepOutIntrusion"] = float((part ^ keep).volume()) if keep is not None else 0.0
+    if pres is not None:
+        # Preserve minus keep-out is what must survive: a boss keeps its bore.
+        pres_eff = pres - keep if keep is not None else pres
+        report["preserveMissing"] = _preserve_missing(pres_eff, part, mesh)
+    else:
+        report["preserveMissing"] = 0.0
+    report["outsideDesignSpace"] = float((part - design).volume())
+    report["boundaryCutArea"] = _boundary_cut_area(study, mesh)
+    report.update(_creases(study, mesh))
+    report["closedBores"] = _closed_bores(study, mesh)
+    # decompose() lists each enclosed cavity too, as a negative volume
+    pieces = [b.volume() for b in part.decompose()]
+    report["bodies"] = sum(1 for v in pieces if v > 0)
+    report["enclosedCavityVolume"] = float(-sum(v for v in pieces if v < 0))
+
+    if study.print_direction is not None:
+        report.update(_overhang(mesh, study.print_direction, study))
+    proc = study.process
+    build = study.print_direction if study.print_direction is not None else \
+        (proc.build if proc is not None and proc.build != "auto" else None)
+    if build is not None:
+        # sliced as a printer would: bridges, islands, support volume, bed
+        from .printcheck import check_print
+
+        report["print"] = check_print(mesh, build, process=proc.kind if proc is not None else "fdm",
+                                      material=mat, bridge_span=getattr(proc, "bridge_span", None))
+
+    pitch = (vol / max_cells) ** (1.0 / 3.0)
+    if min_pitch:
+        pitch = max(pitch, min_pitch)
+    if study.shells:
+        # A wall voxelizes to a whole number of cells, so at two or three
+        # cells through it reads up to a cell thick or thin: bending stress
+        # goes as 1/t^2, and a plenum's 2 mm wall read 2.4 mm and 30% under
+        # its stress at 0.8 mm cells. Four cells through the thinnest wall or
+        # skin, within a cell budget.
+        thin = min(t for _, t in study.shells)
+        pitch = min(pitch, max(thin / _SHELL_CELLS, (vol / _SHELL_MAX_CELLS) ** (1.0 / 3.0)))
+    share = None
+    cut = use_cut_cells(study, cut_cells) and not fractional
+    cg = None
+    if cut:
+        from .cutcell import cut_from_mesh
+
+        cg = cut_from_mesh(mesh, pitch, study.elastic(mat))
+        solid, origin = cg.solid_grid()
+        share = np.zeros(solid.shape)
+        share[tuple(cg.mesh.elem_ijk.T)] = cg.fill
+        report["cutCells"] = int(cg.cut.sum())
+    elif fractional:
+        share, origin = voxelize(mesh, pitch, fractional=True)
+        # a sliver under a twentieth of a cell adds nothing but conditioning
+        solid = share >= 0.05
+    else:
+        solid, origin = voxelize(mesh, pitch)
+    report["analysisPitch"] = pitch
+    report["minMember"], report["p5Member"] = _thickness(solid if share is None else share >= 0.5, pitch)
+
+    # Face connectivity: cells that meet only at an edge or a corner share
+    # two nodes or one, a hinge the stiffness matrix cannot hold, and CG
+    # never converges (GRIP's upper arm: 44 such islands of 4-6 cells at a
+    # 1.04 mm pitch stalled verification for over an hour).
+    lbl, nlab = ndimage.label(solid)
+    elem_ijk = np.argwhere(solid)
+    hm = HexMesh(elem_ijk, pitch, origin)
+    bc = boundary_conditions(study, hm, check_loads=False, tol_floor=0.5 * (contact_band or 0.0) + 0.5 * pitch)
+    # Material not connected to a support would float; it is reported as a
+    # separate body above and left out of the stress analysis.
+    supported_lbls = np.unique(lbl[tuple(elem_ijk[bc.support_nodes[hm.enode].any(axis=1)].T)])
+    keep_el = np.isin(lbl[tuple(elem_ijk.T)], supported_lbls)
+    if not keep_el.all():
+        hm = HexMesh(elem_ijk[keep_el], pitch, origin)
+        bc = boundary_conditions(study, hm, check_loads=False, tol_floor=0.5 * (contact_band or 0.0) + 0.5 * pitch)
+    if cg is not None:
+        cg = cg.restrict(keep_el)
+        hm = cg.mesh
+    support_nodes, fixed = bc.support_nodes, bc.fixed
+    kept_ijk = elem_ijk if keep_el.all() else elem_ijk[keep_el]
+    fill = None if share is None else share[tuple(kept_ijk.T)]
+
+    band = max(1.5 * pitch, contact_band or 0.0)
+    report["contactBand"] = band
+    edges = _user_edges(study, band)
+    on_edge = edges(hm.node_xyz) if edges is not None else None
+    fg = gravity_force(hm, np.ones(hm.n_elem) if fill is None else fill, bc.gravity, fixed) if bc.gravity is not None else None
+    # Heat (the study's thermal block): the part's own temperature, solved on
+    # the part as delivered; each cell's modulus derated by it, the
+    # expansion its neighbours and the supports stop as a load in every
+    # case, and the stress formed from the strain less the free expansion.
+    # Strength falls with the modulus (the same retention curve). The
+    # submodels re-solve without heat, so they are skipped.
+    moduli, eps, g_node = mat.E, None, None
+    if study.thermal is not None:
+        from .thermal import StudyHeat, retention
+
+        heat = StudyHeat(study, hm, study.elastic(mat), fixed, modulus=mat.E)
+        heat.temperature()
+        moduli = mat.E * heat.g
+        if heat.expands:
+            eps = heat.eps
+            fth = heat.load(np.ones(hm.n_elem), mat.E)
+            fg = fth if fg is None else fg + fth
+        g_node = retention(heat.curve, heat.t_node)[0] if heat.curve is not None else np.ones(hm.n_nodes)
+        refine = 0
+        report["thermal"] = {"maxTemperature": float(heat.t_node.max()),
+                             "minRetention": float(heat.g.min()),
+                             "expansion": heat.alpha if heat.expands else 0.0,
+                             "stressFree": heat.t_ref,
+                             "heatIn": float(heat.bc.power)}
+        cyc = heat.cycle_result
+        if cyc is not None:
+            report["thermal"].update(
+                maxTemperature=float(cyc.node_max.max()), minTemperature=float(cyc.node_min.min()),
+                swing=float((cyc.node_max - cyc.node_min).max()), hotAt=cyc.t_hot, coldAt=cyc.t_cold,
+                meanHot=float(cyc.mean.max()), meanCold=float(cyc.mean.min()), periods=cyc.periods,
+                converged=cyc.converged, period=heat.cycle.period, on=heat.cycle.on)
+    # A force of unknown direction is solved along each axis and judged in
+    # the direction that stresses the part most (directions.py).
+    from .directions import expand, worst_stress_direction
+    spreads = bc.spreads or [None] * len(study.load_cases)
+    rhs, layout = expand(bc.loads, spreads, fg)
+    from .simp import _use_mg
+
+    def solve(moduli, rhs):
+        if cg is not None:
+            return _solve_cut(cg, study.elastic(mat), fixed, bc.springs, mat.E, moduli, rhs)
+        if fill is not None:
+            # a part-filled cell is that share as stiff; its stress stays
+            # the material's (nodal_stress at the full modulus)
+            moduli = np.broadcast_to(moduli, (hm.n_elem,)) * fill
+        if _use_mg(hm.n_elem):
+            # From simp.MG_MIN_CELLS up, matrix-free multigrid (as the optimizer
+            # uses): no assembled matrix, a fraction of the memory and time. It
+            # raises RuntimeError on non-convergence like Solver does. It also
+            # carries .mesh and .nu, which is all the stress recovery reads.
+            from .mg import GridElasticity
+
+            stiff = GridElasticity(hm, study.elastic(mat), fixed,
+                                   springs=mat.E * bc.springs if bc.springs is not None else None,
+                                   rtol=1e-6, maxiter=3000)
+            stiff.set_moduli(np.broadcast_to(moduli, (hm.n_elem,)).astype(float))
+            return stiff, stiff.solve_many(rhs)
+        stiff = Stiffness(hm, study.elastic(mat), fixed)
+        k = stiff.assemble(np.broadcast_to(moduli, (hm.n_elem,)).astype(float))
+        if bc.springs is not None:
+            k = (k + mat.E * bc.springs).tocsr()
+        # 1e-6 is three-plus significant figures of stress; 1e-7 cost a third
+        # more iterations. All cases share one multigrid hierarchy and run on
+        # threads.
+        solver = Solver(hm, rtol=1e-6, maxiter=3000, rebuild_after_iters=10_000)
+        return stiff, solver.solve_many(k, rhs)
+
+    stiff, displacements = solve(moduli, rhs)
+    cold = None
+    if study.thermal is not None and heat.cold is not None:
+        # The cycle's coldest moment, solved the same way: a part held at a
+        # hot stress-free temperature is stressed cold, and its swing is what
+        # thermal cycling fatigues (each case keeps its hot worst direction).
+        t_hot = heat.t_node
+        heat.use(heat.cold)
+        mod_c = mat.E * heat.g
+        eps_c = heat.eps if heat.expands else None
+        g_c = retention(heat.curve, heat.cold)[0] if heat.curve is not None else np.ones(hm.n_nodes)
+        fg_c = gravity_force(hm, np.ones(hm.n_elem) if fill is None else fill, bc.gravity, fixed) if bc.gravity is not None else None
+        if heat.expands:
+            fth_c = heat.load(np.ones(hm.n_elem), mat.E)
+            fg_c = fth_c if fg_c is None else fg_c + fth_c
+        rhs_c = expand(bc.loads, spreads, fg_c)[0]
+        stiff_c, disp_c = solve(mod_c, rhs_c)
+        cold = (stiff_c, disp_c, mod_c, eps_c, g_c)
+    from scipy.spatial import cKDTree
+    cases = []
+    worst_sf = np.inf
+    worst_dirs = []
+    env = None   # von Mises per node, the worst over the cases
+    for ci, case in enumerate(study.load_cases):
+        load_nodes = bc.case_load_nodes[ci]
+        # Exclude nodes within the contact band of an applied load or support.
+        contact = support_nodes | load_nodes
+        near = cKDTree(hm.node_xyz[contact]).query(hm.node_xyz, k=1, distance_upper_bound=band)[0] < np.inf
+        if on_edge is not None:
+            near |= on_edge
+        body = ~near
+        idx = layout[ci]
+        direction = None
+        if len(idx) == 1:
+            f, u = rhs[idx[0]], displacements[idx[0]]
+        else:
+            sp = spreads[ci]
+            # the fixed part carries the expansion, the uncertain force none;
+            # stress over retention, so the worst direction is the one
+            # nearest failure where hot material is weak
+            s0 = nodal_stress(stiff, displacements[idx[0]], moduli, eps) if idx[0] is not None else None
+            sb = [nodal_stress(stiff, displacements[i], moduli) for i in idx[1:]]
+            if g_node is not None:
+                kn = 1.0 / np.maximum(g_node, 1e-3)[:, None]
+                s0 = s0 * kn if s0 is not None else None
+                sb = [b * kn for b in sb]
+            direction, _ = worst_stress_direction(sp, s0, sb, body)
+            f = sum(direction[j] * rhs[i] for j, i in enumerate(idx[1:]))
+            u = sum(direction[j] * displacements[i] for j, i in enumerate(idx[1:]))
+            if idx[0] is not None:
+                f, u = f + rhs[idx[0]], u + displacements[idx[0]]
+        worst_dirs.append(direction)
+        vm = nodal_von_mises(stiff, u, moduli, eps)
+        env = vm if env is None else np.maximum(env, vm)
+        if bc.case_pressure_nodes[ci].any():
+            vm = _smooth_wetted(hm.node_xyz, vm, bc.case_pressure_nodes[ci], pitch)
+        # hot material is weaker: the peak is where stress / retention is
+        util = vm if g_node is None else vm / np.maximum(g_node, 1e-3)
+        pk = int(np.argmax(np.where(body, util, -1))) if body.any() else int(np.argmax(util))
+        peak = float(vm[pk])
+        at = hm.node_xyz[pk].tolist()
+        keep = 1.0 if g_node is None else float(g_node[pk])
+        global_peak = peak
+        refined = []
+        if refine and body.any():
+            half = max(8.0 * pitch, 6.0)
+            spots = list(_hotspots(hm.node_xyz, vm, body, peak, half, count=refine))
+            if cg is not None:
+                # members under 3 cells thick read up to ~15% low even cut
+                # (two cells across a diagonal strip are too few to bend
+                # in): the highest of them get a submodel too
+                spots += _thin_spots(hm, solid, origin, pitch, vm, body, peak, half, spots, count=refine)
+
+            def sub(c, u=u, case=case, half=half, contact=contact):
+                return _submodel_peak(study, mesh, hm, u, c, half, pitch / 2.5, mat,
+                                      hm.node_xyz[contact], band, case, edges=edges, cut=cg is not None)
+            if len(spots) > 1:
+                # independent boxes, on threads (the solves release the GIL;
+                # amg_solver sets up one at a time, so the same numbers)
+                from concurrent.futures import ThreadPoolExecutor
+
+                with ThreadPoolExecutor(min(len(spots), 3)) as ex:
+                    subs = list(ex.map(sub, spots))
+            else:
+                subs = [sub(c) for c in spots]
+            for r in subs:
+                if r is None:
+                    continue
+                refined.append({"at": r[1], "peakStress": r[0]})
+                if r[0] > peak:
+                    peak, at = r
+        disp = u.reshape(-1, 3)
+        if fields:
+            if "fields" not in report and study.thermal is not None:
+                # C per node at the hot moment (the cycle's hottest, or the steady state)
+                report["fields"] = {"nodes": hm.node_xyz, "cases": [],
+                                    "temperature": t_hot if cold is not None else heat.t_node}
+            report.setdefault("fields", {"nodes": hm.node_xyz, "cases": []})["cases"].append(
+                {"name": case.name, "vonMises": vm, "displacement": disp, "wetted": bc.case_pressure_nodes[ci]})
+        wet = bc.case_pressure_nodes[ci]
+        if load_nodes.any():
+            defl = float(np.linalg.norm(disp[load_nodes].mean(axis=0)))
+        elif wet.any():
+            # a pressure's deflection is how far its walls bulge: the most any
+            # wetted node moves (relative to the part, when nothing holds it)
+            dw = _rigid_free(hm.node_xyz, u).reshape(-1, 3) if study.self_equilibrated else disp
+            defl = float(np.linalg.norm(dw[wet], axis=1).max())
+        else:
+            defl = 0.0
+        if bc.pressure_imbalance[ci] > 0.02 and study.self_equilibrated:
+            report.setdefault("warnings", []).append(
+                f"{case.name}: the pressure no longer balances on the delivered part "
+                f"({bc.pressure_imbalance[ci]:.1%} net): a wall the cavity relies on is open (a leak)")
+        # The safety factor carries a discretization allowance: on the
+        # plate-with-hole benchmark (tests) refined voxel peaks land within
+        # -12%..+13% of Peterson's Kt, depending on how the grid falls on the
+        # hole. Under-reading stress is the unsafe direction, so the factor
+        # is computed against peak * STRESS_ALLOWANCE.
+        sf = keep * mat.strength / (peak * STRESS_ALLOWANCE) if peak > 0 else np.inf
+        inter = None
+        proc = study.process
+        if proc is not None and proc.build not in (None, "auto") and proc.interlayer < 1.0:
+            # Layered parts part along their layers: the tension pulling
+            # layers apart (the stress normal to them) against the bond's
+            # strength, a fraction of the in-plane one.
+            from .am import build_vector
+
+            nb = build_vector(proc.build)
+            sig = nodal_stress(stiff, u, moduli, eps)
+            sn = sig[:, :3] @ (nb * nb) + 2.0 * (sig[:, 3] * nb[0] * nb[1] + sig[:, 4] * nb[1] * nb[2]
+                                               + sig[:, 5] * nb[2] * nb[0])
+            tens = np.where(body, np.maximum(sn, 0.0), 0.0)
+            ti = int(np.argmax(tens if g_node is None else tens / np.maximum(g_node, 1e-3)))
+            inter = float(tens[ti])
+            k_in = 1.0 if g_node is None else float(g_node[ti])
+            sf_inter = k_in * proc.interlayer * mat.strength / (inter * STRESS_ALLOWANCE) if inter > 0 else np.inf
+            sf = min(sf, sf_inter)
+        cyc_row = {}
+        if cold is not None:
+            stiff_c, disp_c, mod_c, eps_c, g_c = cold
+            if len(idx) == 1:
+                u_c = disp_c[idx[0]]
+            else:
+                u_c = sum(direction[j] * disp_c[i] for j, i in enumerate(idx[1:]))
+                if idx[0] is not None:
+                    u_c = u_c + disp_c[idx[0]]
+            s_h = nodal_stress(stiff, u, moduli, eps) / np.maximum(g_node, 1e-3)[:, None]
+            s_c = nodal_stress(stiff_c, u_c, mod_c, eps_c) / np.maximum(g_c, 1e-3)[:, None]
+            util_c = von_mises(s_c)
+            pk_c = int(np.argmax(np.where(body, util_c, -1))) if body.any() else int(np.argmax(util_c))
+            sf_c = mat.strength / (util_c[pk_c] * STRESS_ALLOWANCE) if util_c[pk_c] > 0 else np.inf
+            sf = min(sf, sf_c)
+            # Thermal-cycling fatigue: durability's design curves read the
+            # cycle's maximum stress (which carries the mean-stress effect for
+            # R up to ~0.3); a stress that barely moves over the cycle is
+            # creep, not fatigue, so above that the swing counts: the
+            # equivalent is min(max, range / 0.7). Stresses over retention,
+            # so they read against room-temperature strength.
+            smax = np.maximum(von_mises(s_h), util_c)
+            rng = von_mises(s_h - s_c)
+            seq = np.where(body, np.minimum(smax, rng / 0.7), 0.0)
+            pc = int(np.argmax(seq))
+            cyc_row = {"coldSafetyFactor": sf_c, "coldPeakStress": float(util_c[pk_c] * g_c[pk_c]),
+                       "cycleStress": float(seq[pc]), "cycleStressRange": float(rng[pc]),
+                       "cycleAt": hm.node_xyz[pc].tolist()}
+        worst_sf = min(worst_sf, sf)
+        cases.append({
+            "name": case.name,
+            "peakStress": peak,
+            "peakAt": at,
+            "globalPeakStress": global_peak,
+            "refined": refined,
+            "p99Stress": float(np.percentile(vm[body] if body.any() else vm, 99)),
+            "contactPeakStress": float(vm.max()),
+            "safetyFactor": sf,
+            **({"peakTemperature": float((t_hot if cold is not None else heat.t_node)[pk]),
+                "strengthRetention": keep}
+               if g_node is not None else {}),
+            **cyc_row,
+            "interlayerStress": inter,
+            "deflection": defl,
+            "maxDisplacement": float(np.linalg.norm(disp, axis=1).max()),
+            "compliance": float(f @ u),
+            **({"pressureImbalance": bc.pressure_imbalance[ci]} if wet.any() else {}),
+            # the uncertain force's most stressful direction, which the
+            # numbers above are for (unit vector)
+            **({"worstDirection": [float(v) for v in direction]} if direction is not None else {}),
+        })
+    report["cases"] = cases
+    report["safetyFactor"] = worst_sf
+    goal_sf = study.goal.safety_factor
+    if goal_sf and not study.self_equilibrated:
+        # the safety factor holds against buckling too (study._margin). Read
+        # for every part, however far under its stress safety factor: the
+        # tet confirm can lift a voxel reading 2.5x (the MBB beam, 0.78 to
+        # 1.97), and a part it lifts must not pass unchecked.
+        try:
+            bk = _buckling(study, mesh, vol, pitch, contact_band, worst_dirs)
+        except (RuntimeError, ValueError, MemoryError) as exc:
+            bk = None
+            report.setdefault("warnings", []).append(f"buckling check failed: {exc}")
+        if bk is not None:
+            report["buckling"] = bk
+            if bk["factor"] is not None:
+                report["bucklingFactor"] = bk["factor"]
+                if bk["factor"] < goal_sf:
+                    worst = min((c for c in bk["cases"] if c["factor"] is not None), key=lambda c: c["factor"])
+                    report.setdefault("warnings", []).append(
+                        f"{worst['name']}: buckles at {bk['factor']:.2f}x its loads (linear buckling), under "
+                        f"the safety factor {goal_sf:g}; the mode is largest near "
+                        f"({', '.join(f'{v:.1f}' for v in worst.get('modeAt', []))}). Thicken or brace the "
+                        "slender member carrying compression there.")
+    if env is not None and len(env):
+        # how evenly the material is worked: mean von Mises over the near
+        # peak (99.9th percentile, so one singular node does not set it).
+        # Low (about 0.1, the wall brackets) means most of the part idles
+        # at a few percent of the peak, which the stress-constrained method
+        # trims (study.py, method auto)
+        pk = float(np.quantile(env, 0.999))
+        report["stressUtilization"] = float(env.mean() / pk) if pk > 0 else None
+    report["stressAllowance"] = STRESS_ALLOWANCE
+    from .durability import active, assess
+    if active(study):
+        # fatigue (cases with cycles), creep and relaxation (hours, preload)
+        report["durability"] = assess(study, cases, STRESS_ALLOWANCE)
+    report["analysisCells"] = int(hm.n_elem)
+    report["seconds"] = time.time() - t0
+    return report