loadpath 0.1.1__py3-none-any.whl

loadpath/lattice_buckling.py

@@ -0,0 +1,245 @@
+"""
+Elastic buckling of a lattice's walls and struts, from a periodic unit-cell
+eigenvalue solve.
+
+The homogenized check reads a lattice's first yield from its walls' linear
+stress. A thin wall or a slender strut can instead buckle first, under a
+compressive macro stress well below the one that yields it, and the linear
+check does not see that. Here a block of `cells`^3 unit cells on a periodic
+voxel grid (the nodes wrap across the block's faces, as lattice_tensors'
+solves do) is put under a unit macro stress, and the linear eigenvalue
+problem
+
+    K phi = lambda (-K_sigma) phi
+
+gives the smallest load factor lambda at which the walls buckle: the macro
+stress, in units of the solid's modulus, at which a perfect infinite lattice
+buckles. A one-cell block finds the modes that repeat every cell, a two-cell
+block also the ones that alternate between neighbours (often lower); the
+long-wave (whole-part, Euler) modes are not in it, a part-level check
+(nonlinear.linear_buckling) covers those.
+
+K uses the element in force (the incompatible-mode hex8, which bends without
+locking at a few voxels through a wall); K_sigma is the trilinear geometric
+stiffness of the linear stress at the Gauss points.
+
+Tables over relative density per cell type and load direction live in
+data/lattice_buckling.json (bench/lattice_buckling.py writes them);
+`buckling_stress` reads them. Real walls are not perfect: printed walls are
+wavy, porous and stair-stepped, and shells lose much of their perfect
+buckling load to that. How the check in homogenized.py knocks the perfect
+value down (with the as-printed stiffness, lattice_print.py) is documented
+there and in docs/VALIDATION.md.
+"""
+from __future__ import annotations
+
+import json
+from functools import lru_cache
+from pathlib import Path
+
+import numpy as np
+
+__all__ = ["unit_cell_buckling", "buckling_stress", "has_buckling", "TABLE_PATH", "DIRECTIONS"]
+
+TABLE_PATH = Path(__file__).resolve().parent / "data" / "lattice_buckling.json"
+
+# macro uniaxial compression directions the tables hold, in the cell's axes
+DIRECTIONS = {"100": (0.0, 0.0, 1.0), "111": (1.0, 1.0, 1.0)}
+
+
+def _grid(kind, wall_over_cell, n, cells):
+    from .lattice import tpms
+    from .struts import is_strut, unit_cell_distance
+
+    m = n * cells
+    h = 1.0 / n
+    axes = (np.arange(m) + 0.5) * h
+    g = np.stack(np.meshgrid(axes, axes, axes, indexing="ij"), -1).reshape(-1, 3)
+    if is_strut(kind):
+        u = g % 1.0
+        solid = unit_cell_distance(kind, u, 0.0) < 0.5 * wall_over_cell
+    else:
+        solid = np.abs(tpms(kind, g, 1.0)) < 0.5 * wall_over_cell
+    return np.argwhere(solid.reshape(m, m, m)), m, h
+
+
+def unit_cell_buckling(kind: str, wall_over_cell: float, direction=(0.0, 0.0, 1.0), n: int | None = None,
+                       cells: int = 1, nu: float = 0.35, n_modes: int = 2, direct_max_dof: int = 60_000) -> dict:
+    """Perfect-lattice elastic buckling under uniaxial macro compression
+    along `direction` (cell axes): the critical macro stress over the
+    solid's modulus (`sigmaOverE`), the relative density of the voxel cell,
+    and its modulus along the direction (over E), for a block of
+    `cells`^3 periodic unit cells, `n` voxels per cell (default: five
+    voxels through the wall or strut, 24-72)."""
+    import time
+
+    import scipy.sparse as sp
+    from scipy.sparse.linalg import LinearOperator, eigsh
+
+    from .fem import CORNERS, elastic_c, hex8_b, hex8_ke
+
+    t0 = time.time()
+    if n is None:
+        n = int(np.clip(np.ceil(5.0 / float(wall_over_cell)), 24, 72))
+    eijk, m, h = _grid(kind, float(wall_over_cell), n, cells)
+    corner = (eijk[:, None, :] + CORNERS[None]) % m
+    eijk, corner = _connected(eijk, corner, m)
+    ne = len(eijk)
+    rho = ne / float(m ** 3)
+    used, inv = np.unique((corner[..., 0] * m + corner[..., 1]) * m + corner[..., 2], return_inverse=True)
+    enode = inv.reshape(ne, 8)
+    nn = len(used)
+    edof = (3 * enode[:, :, None] + np.arange(3)).reshape(ne, 24)
+    rows = np.repeat(edof, 24, axis=1).ravel()
+    cols = np.tile(edof, (1, 24)).ravel()
+    ke = hex8_ke(nu) * h
+    k = sp.csr_matrix((np.tile(ke.ravel(), ne), (rows, cols)), shape=(3 * nn, 3 * nn))
+    # keep the block from floating: hold one node; the rest is periodic
+    free = np.ones(3 * nn, bool)
+    free[:3] = False
+    kf = k[free][:, free].tocsc()
+    nf = int(free.sum())
+    kinv = _factorized(kf, nf <= direct_max_dof)
+    xc = (eijk[:, None, :] + CORNERS[None]) * h
+    c0 = elastic_c(1.0, nu)
+    vol = float(cells ** 3)
+    bc = hex8_b(0.0, 0.0, 0.0, nu) / h
+
+    def macro_solve(e):
+        eps = np.array([[e[0], e[3] / 2, e[5] / 2], [e[3] / 2, e[1], e[4] / 2], [e[5] / 2, e[4] / 2, e[2]]])
+        u0 = (xc @ eps.T).reshape(ne, 24)
+        f = np.zeros(3 * nn)
+        np.add.at(f, edof, -(u0 @ ke.T))
+        u = np.zeros(3 * nn)
+        u[free] = kinv(f[free])
+        ue = u[edof] + u0
+        return ue, ((ue @ bc.T) @ c0.T).sum(axis=0) * h ** 3 / vol
+
+    # effective stiffness, then the macro strain of a unit uniaxial compression
+    C = np.zeros((6, 6))
+    fields = []
+    for comp in range(6):
+        e = np.zeros(6)
+        e[comp] = 1.0
+        ue, s = macro_solve(e)
+        C[:, comp] = s
+        fields.append(ue)
+    d = np.asarray(direction, float)
+    d = d / np.linalg.norm(d)
+    sig = -np.array([d[0] ** 2, d[1] ** 2, d[2] ** 2, d[0] * d[1], d[1] * d[2], d[2] * d[0]])
+    eps = np.linalg.solve(C, sig)
+    ue = sum(eps[c] * fields[c] for c in range(6))
+    e_dir = 1.0 / float(-sig @ np.linalg.solve(C, -sig))     # modulus along d, over E
+    # geometric stiffness of the linear stress at the 2x2x2 Gauss points
+    g = 1.0 / np.sqrt(3.0)
+    s = 2.0 * CORNERS - 1.0
+    w = h ** 3 / 8.0
+    kq = np.zeros((ne, 8, 8))
+    for xi in (-g, g):
+        for eta in (-g, g):
+            for zeta in (-g, g):
+                dn = np.empty((8, 3))
+                dn[:, 0] = 0.125 * s[:, 0] * (1 + eta * s[:, 1]) * (1 + zeta * s[:, 2]) * 2 / h
+                dn[:, 1] = 0.125 * s[:, 1] * (1 + xi * s[:, 0]) * (1 + zeta * s[:, 2]) * 2 / h
+                dn[:, 2] = 0.125 * s[:, 2] * (1 + xi * s[:, 0]) * (1 + eta * s[:, 1]) * 2 / h
+                b = hex8_b(xi, eta, zeta, nu) / h
+                sv = (ue @ b.T) @ c0.T                       # (ne, 6) Voigt, tensor shears
+                st = np.empty((ne, 3, 3))
+                st[:, 0, 0], st[:, 1, 1], st[:, 2, 2] = sv[:, 0], sv[:, 1], sv[:, 2]
+                st[:, 0, 1] = st[:, 1, 0] = sv[:, 3]
+                st[:, 1, 2] = st[:, 2, 1] = sv[:, 4]
+                st[:, 0, 2] = st[:, 2, 0] = sv[:, 5]
+                kq += w * np.einsum("ai,eij,bj->eab", dn, st, dn)
+    kg_e = np.einsum("eab,ij->eaibj", kq, np.eye(3)).reshape(ne, 576)
+    kg = sp.csr_matrix((kg_e.ravel(), (rows, cols)), shape=(3 * nn, 3 * nn))
+    kgf = kg[free][:, free].tocsr()
+    del kg_e, kq
+    op = LinearOperator((nf, nf), matvec=kinv, dtype=float)
+    from scipy.sparse.linalg import ArpackNoConvergence
+
+    try:
+        mu, _ = eigsh(-kgf, k=n_modes, M=kf.tocsr(), Minv=op, which="LA", tol=1e-4, ncv=max(20, 4 * n_modes),
+                      maxiter=600)
+    except ArpackNoConvergence as e:
+        # clustered modes (a cell whose struts buckle in many equal ways):
+        # the converged ones, else the iteration's best estimate
+        mu = e.eigenvalues if len(e.eigenvalues) else np.array([0.0])
+    mu = np.sort(np.atleast_1d(mu))[::-1]
+    lam = float(1.0 / mu[0]) if mu[0] > 1e-14 else float("inf")
+    return {"kind": kind, "wallOverCell": float(wall_over_cell), "direction": d.tolist(), "cells": cells, "n": n,
+            "rho": rho, "elements": ne, "dof": nf, "sigmaOverE": lam, "modulusOverE": e_dir,
+            "strainAtBuckling": lam / e_dir, "seconds": time.time() - t0}
+
+
+def _connected(eijk, corner, m):
+    """The voxels of the largest piece joined through shared nodes (a thin
+    strut can voxelize into islands that would float)."""
+    import scipy.sparse as sp
+    from scipy.sparse.csgraph import connected_components
+
+    ne = len(eijk)
+    key = ((corner[..., 0] * m + corner[..., 1]) * m + corner[..., 2]).ravel()
+    _, node = np.unique(key, return_inverse=True)
+    inc = sp.csr_matrix((np.ones(ne * 8), (np.repeat(np.arange(ne), 8), node)), shape=(ne, node.max() + 1))
+    _, lab = connected_components(inc @ inc.T, directed=False)
+    big = lab == np.argmax(np.bincount(lab))
+    return eijk[big], corner[big]
+
+
+def _factorized(kf, direct):
+    """x = K^-1 r: PARDISO (pypardiso, nested-dissection ordering, threaded)
+    when installed, else SuperLU for small systems and AMG-preconditioned
+    CG above `direct_max_dof` (SuperLU's orderings fill in badly on 3D
+    grids: a 170k-dof sheet cell took over 10 minutes and 8 GB)."""
+    import scipy.sparse as sp
+
+    try:
+        import pypardiso
+
+        a = sp.csr_matrix(kf)
+        solver = pypardiso.PyPardisoSolver()
+        solver.factorize(a)
+        return lambda r: solver.solve(a, np.ascontiguousarray(r, float))
+    except ImportError:
+        pass
+    if direct:
+        from scipy.sparse.linalg import splu
+
+        return splu(kf.tocsc(), permc_spec="MMD_AT_PLUS_A").solve
+    import pyamg
+    from scipy.sparse.linalg import cg
+
+    ml = pyamg.smoothed_aggregation_solver(sp.csr_matrix(kf), symmetry="hermitian", max_coarse=400,
+                                           coarse_solver="splu")
+    pre = ml.aspreconditioner()
+    return lambda r: cg(kf, r, rtol=1e-10, maxiter=4000, M=pre)[0]
+
+
+@lru_cache(maxsize=1)
+def _table() -> dict:
+    if not TABLE_PATH.exists():
+        return {}
+    return json.loads(TABLE_PATH.read_text())
+
+
+def has_buckling(kind: str) -> bool:
+    return kind in _table().get("cells", {})
+
+
+def buckling_stress(kind: str, rho, direction: str | None = None) -> np.ndarray:
+    """Perfect-lattice buckling stress over the solid's modulus at relative
+    densities `rho`: the table's least over its directions (or the one
+    named), log-log in rho between rows, the end rows' power law beyond."""
+    row = _table()["cells"][kind]
+    xs, keep = np.unique(np.asarray(row["rho"], float), return_index=True)
+    dirs = [direction] if direction else list(row["sigmaOverE"])
+    ys = np.min([np.asarray(row["sigmaOverE"][dd], float)[keep] for dd in dirs], axis=0)
+    lr, ly = np.log(xs), np.log(ys)
+    x = np.log(np.clip(np.atleast_1d(np.asarray(rho, float)), 1e-4, 1.0))
+    out = np.interp(x, lr, ly)
+    if len(xs) > 1:
+        lo = (ly[1] - ly[0]) / (lr[1] - lr[0])
+        hi = (ly[-1] - ly[-2]) / (lr[-1] - lr[-2])
+        out = np.where(x < lr[0], ly[0] + lo * (x - lr[0]), out)
+        out = np.where(x > lr[-1], ly[-1] + hi * (x - lr[-1]), out)
+    return np.exp(out)

loadpath/lattice_grade.py

@@ -0,0 +1,325 @@
+"""
+Lattice walls graded to the stress, for field-graph lattices, together
+with the cells' direction.
+
+`grade_lattice` replaces a lattice node's constant `thickness` with a
+`density` field (a grid node) sized by fully stressed iteration on the
+homogenized check (homogenized.py, anisotropic tensors):
+
+1. analyze the part with the current density; every lattice cell's macro
+   stress per load case comes back in global axes;
+2. holding that stress, each cell takes the least density (of 28
+   candidates between the wall limits, log-interpolated) whose wall stress
+   surface, in the cell's own frame, stays under the allowable in every
+   case; cells where lattice meets a skin carry the skin-junction factor,
+   as the check does;
+3. the requirement spreads over a quarter cell (a peak spreads over a cell
+   before the lattice can follow it), moves at most halving or doubling a
+   pass, and the allowable is tightened or eased by how far the analysis
+   lands from the target, as lattice.lattice_infill's sizing does.
+
+With `orient` the cells are turned too: "uniform" one direction for the
+whole lattice, an integer k for k zones (stress_zones). The direction is
+chosen for the least material the sized lattice needs, not for the peak:
+holding each cell's macro stress, every candidate rotation's per-cell need
+is a few matrix products away (the quartic features of the turned stress
+dotted with every candidate density's surface), so hundreds of rotations
+per zone are scored by the mass they would leave. Sizing and turning
+alternate for `rounds` rounds.
+
+The density is a grid (`op: grid`, `source` while sizing; written to an
+.npz the result's graph points at), so `loadpath field` meshes the graded
+lattice as sized. Stretched (`aspect`) cells and graded (warp) cells are not
+graded here yet.
+"""
+from __future__ import annotations
+
+import copy
+import time
+
+import numpy as np
+
+__all__ = ["grade_lattice", "need_density"]
+
+SOURCE = "lattice-density"
+N_CAND = 28
+
+
+def _cand_tensors(kind, rho_min, rho_max, aspect=None):
+    from .lattice_tensors import tensors_at
+
+    cand = np.geomspace(rho_min, rho_max, N_CAND)
+    C, P, Q, F = tensors_at(kind, cand, aspect)
+    return cand, P, Q, F
+
+
+def _surfaces(sc, P, Q, F):
+    """Wall stress surface of stresses sc (n, 6), in the cells' axes, for
+    every candidate density's (P, Q, F): (n, J)."""
+    from .lattice_tensors import quartic_features
+
+    f = quartic_features(sc)
+    q4 = f @ Q.T
+    quad = np.sqrt(np.maximum(np.einsum("na,jab,nb->nj", sc, P, sc), 0.0))
+    return np.maximum(np.maximum(q4, 0.0) ** 0.25, F[None, :] * quad)
+
+
+def need_density(worst, cand, allow, over):
+    """Least candidate density with worst (n, J) <= allow, log-interpolated
+    between candidates; `over` where none is."""
+    ok = worst <= allow
+    first = np.where(ok.any(axis=1), ok.argmax(axis=1), len(cand))
+    need = np.full(len(worst), float(over))
+    at = first < len(cand)
+    need[at] = cand[first[at]]
+    mid = at & (first > 0)
+    j = first[mid]
+    w0 = np.maximum(worst[mid, j - 1], 1e-30)
+    w1 = np.maximum(worst[mid, j], 1e-30)
+    t = np.clip((np.log(w0) - np.log(allow)) / np.maximum(np.log(w0) - np.log(w1), 1e-12), 0.0, 1.0)
+    need[mid] = np.exp(np.log(cand[j - 1]) + t * (np.log(cand[j]) - np.log(cand[j - 1])))
+    return need
+
+
+def _cell_stress(fl, mask, frames=None):
+    """Per case the lattice macro stress of the masked cells in their own
+    axes: frames (n, 3, 3) columns the cell axes, or the check's own."""
+    from .lattice_tensors import stress_rotation
+
+    fr = fl["frames"] if frames is None else frames
+    out = []
+    for sig in fl["latticeStress"]:
+        s = sig[mask]
+        if fr is not None:
+            s = np.einsum("eab,eb->ea", stress_rotation(fr[mask] if fr.ndim == 3 else fr), s)
+        out.append(s)
+    return out
+
+
+def _grid_of(centers, values, origin, pitch):
+    """A dense grid (origin at the first cell centre) of per-cell values,
+    cells with none filled from their nearest neighbour."""
+    from scipy import ndimage
+
+    ijk = np.round((centers - origin) / pitch).astype(int)
+    dims = ijk.max(axis=0) + 1
+    grid = np.zeros(tuple(dims))
+    have = np.zeros(tuple(dims), bool)
+    grid[tuple(ijk.T)] = values
+    have[tuple(ijk.T)] = True
+    if not have.all():
+        idx = ndimage.distance_transform_edt(~have, return_distances=False, return_indices=True)
+        grid = grid[tuple(idx)]
+    return grid
+
+
+def grade_lattice(doc, study, target_sf=None, wall_min=None, wall_max=None, cells: int = 15_000,
+                  iterations: int = 12, orient=None, rounds: int = 2, base_dir=None, node=None,
+                  progress=None, n_rot: int = 800, seam: float = 1.0, confirm: str = "auto") -> dict:
+    """Grade the graph's lattice wall to the stress (module docstring).
+    Returns {"doc" (density as a grid node reading the in-memory source),
+    "density": {"origin", "pitch", "values"}, "best" (the lightest analyzed
+    design that met the target), "history", "orient", "seconds"}. `seam`:
+    zones only, mm of solid plate between zones (orient.seam; 0 for none).
+    `confirm`: with "auto" (default) a lattice cut open at bare faces
+    (latticeExposed over lattice_orient.EXPOSED_LIMIT) is graded but not
+    turned, and "guard" says why (lattice_orient.optimize_orientation);
+    "none" turns it on the homogenized reading. Check a turned graded
+    design yourself with resolved.resolved_check."""
+    from scipy import ndimage
+
+    from .fields import FieldGraph, expand_groups
+    from .homogenized import SKIN_JUNCTION, homogenized_check, lattice_nodes
+    from .lattice import relative_density
+    from .lattice_orient import (_cell_group, _rotvec_deg, _smallest, candidate_rotations,
+                                 dominant_directions, stress_zones)
+    from .lattice_tensors import has_tensors, stress_rotation, tensors_at
+    from .struts import is_strut
+    from .verify import STRESS_ALLOWANCE
+
+    t0 = time.time()
+    say = progress or (lambda *_: None)
+    full = expand_groups(doc)
+    name = node or full.get("output") or list(full["nodes"])[-1]
+    g = FieldGraph({**full, "output": name}, base_dir=base_dir)
+    lats = lattice_nodes(g, name)
+    if len(lats) != 1:
+        raise ValueError(f"grading needs one lattice node in {name!r} (found {len(lats)})")
+    lat = lats[0]
+    spec = full["nodes"][lat]
+    kind = spec.get("type", "gyroid")
+    if "aspect" in spec:
+        raise ValueError(f"lattice {lat!r}: grading a stretched (aspect) cell is not supported yet")
+    if not isinstance(spec.get("cell", 8.0), (int, float)):
+        raise ValueError(f"lattice {lat!r}: grading needs a constant cell")
+    if not has_tensors(kind):
+        raise ValueError(f"lattice {lat!r} ({kind}) has no cell tensors to grade by")
+    cell = float(spec.get("cell", 8.0))
+    target = float(target_sf or (study.goal.safety_factor if getattr(study, "goal", None) else 2.0) or 2.0)
+    proc = getattr(study, "process", None)
+    wmin = float(wall_min if wall_min is not None else max(getattr(proc, "min_feature", 0.0) or 0.0, 0.6))
+    lo_lim = 0.02 if is_strut(kind) else 0.05
+    rho_min = float(np.clip(relative_density(kind, wmin, cell), lo_lim, 0.95))
+    rho_max = float(np.clip(relative_density(kind, wall_max, cell), rho_min, 0.95)) if wall_max else 0.6
+    cand, Pc, Qc, Fc = _cand_tensors(kind, rho_min, rho_max)
+    allow = study.material.strength / (target * STRESS_ALLOWANCE)
+    group = _cell_group(kind)
+
+    work = copy.deepcopy(full)
+    ls = work["nodes"][lat]
+    rho0 = float(np.clip(relative_density(kind, float(ls.get("thickness", 1.0)), cell), rho_min, rho_max)) \
+        if not isinstance(ls.get("thickness"), str) else 0.5 * (rho_min + rho_max)
+    ls.pop("thickness", None)
+    dens = f"{lat}__density"
+    ls["density"] = dens
+    work["nodes"][dens] = {"op": "grid", "source": SOURCE}
+    if isinstance(orient, (int, np.integer)) and orient > 1 or orient == "uniform":
+        ls.pop("orient", None)
+
+    def analyze(values, origin, pitch, fields=True):
+        src = {SOURCE: {"origin": origin, "pitch": pitch, "values": values}}
+        return homogenized_check(copy.deepcopy(work), study, node=name, base_dir=base_dir, cells=cells,
+                                 fields=fields, sources=src)
+
+    # the grid: the check's own, from one analysis at the uniform start
+    probe = {SOURCE: {"origin": np.zeros(3), "pitch": 1e3, "values": np.full((2, 2, 2), rho0)}}
+    rep = homogenized_check(copy.deepcopy(work), study, node=name, base_dir=base_dir, cells=cells, fields=True,
+                            sources=probe)
+    fl = rep["fields"]
+    pitch = float(rep["analysisPitch"])
+    origin = fl["centers"].min(axis=0)
+    dims = np.round((fl["centers"].max(axis=0) - origin) / pitch).astype(int) + 1
+    G = np.full(tuple(dims), rho0)            # the density grid (cell centres)
+    history, best = [], None
+    grow = max(1, int(round(0.25 * cell / pitch)))
+
+    def ijk_of(c):
+        return np.clip(np.round((c - origin) / pitch).astype(int), 0, dims - 1)
+
+    def size(G, fl, allow):
+        """The grid's next density from the analysis `fl` of it."""
+        c = fl["centers"]
+        ijk = ijk_of(c)
+        rho = G[tuple(ijk.T)]
+        latc = fl["fc"] > 0.05
+        junction = (fl["fs"] > 0.05) & latc
+        worst = np.zeros((len(c), len(cand)))
+        for sc in _cell_stress(fl, np.ones(len(c), bool)):
+            worst = np.maximum(worst, _surfaces(sc, Pc, Qc, Fc))
+        worst = np.where(junction[:, None], worst * SKIN_JUNCTION, worst)
+        need = np.where(latc, need_density(worst, cand, allow, rho_max), 0.0)
+        g3 = np.zeros(tuple(dims))
+        g3[tuple(ijk.T)] = need
+        g3 = ndimage.maximum_filter(g3, size=2 * grow + 1)
+        need = np.where(latc, g3[tuple(ijk.T)], rho)
+        new = G.copy()
+        new[tuple(ijk.T)] = np.clip(np.clip(need, 0.5 * rho, 2.0 * rho), rho_min, rho_max)
+        return new
+
+    def run_sizing(G, fl, allow, tag):
+        nonlocal best
+        for it in range(iterations):
+            new = size(G, fl, allow)
+            rep = analyze(new, origin, pitch)
+            fl = rep["fields"]
+            sf = float(rep["safetyFactor"])
+            latc = fl["fc"] > 0.05
+            r_now = new[tuple(ijk_of(fl["centers"][latc]).T)]
+            row = {"stage": tag, "iteration": it, "mass": rep["mass"], "safetyFactor": sf,
+                   "densityRange": [float(r_now.min()), float(r_now.max())] if len(r_now) else None,
+                   "latticeTurnedExposed": rep.get("latticeTurnedExposed")}
+            if rep.get("warnings"):
+                row["warnings"] = rep["warnings"]
+            history.append(row)
+            say({"stage": "lattice-grade", **row})
+            if sf >= target * 0.995 and (best is None or rep["mass"] < best["mass"]):
+                best = {**row, "values": new.copy(), "orient": copy.deepcopy(work["nodes"][lat].get("orient"))}
+            short = sf / target
+            if it >= 1:
+                allow *= float(np.clip(short, 0.85, 1.15)) ** 0.5
+            converged = np.allclose(new, G, rtol=0.02, atol=0.003) and abs(short - 1.0) < 0.03
+            G = new
+            if converged:
+                break
+        return G, fl, allow
+
+    G, fl, allow = run_sizing(G, fl, allow, "size")
+    guard = None
+    if orient:
+        from .lattice_orient import _guard
+
+        if confirm not in ("auto", "none"):
+            raise ValueError("grade_lattice confirm is 'auto' or 'none' (check a turned design with resolved_check)")
+        exposed = float(rep.get("latticeExposed") or 0.0)
+        guard = _guard(confirm, exposed, True, None, None, study, "safetyFactor", name, base_dir)
+        if guard is not None:
+            say({"stage": "lattice-grade-guard", "reason": guard["reason"]})
+            orient = None
+    if orient:
+        # zones start from the best single direction: one uniform round first
+        k_z = 1 if orient == "uniform" else int(orient)
+        plan = [1] * rounds if k_z == 1 else [1] + [k_z] * rounds
+        current = [np.eye(3)]
+        at = None
+        for rnd, k in enumerate(plan):
+            centers = fl["centers"]
+            latc = fl["fc"] > 0.05
+            w = fl["fc"] * fl["fill"] * pitch ** 3
+            rho = G[tuple(ijk_of(centers).T)]
+            if k > 1:
+                from .fields import zone_weights
+
+                if at is None:
+                    _, at = stress_zones(centers[latc], [s[latc] for s in fl["latticeStress"]], w[latc], k,
+                                         spatial=2.0)
+                    current = [current[0]] * k
+                own = np.argmax(zone_weights(at, cell, centers), axis=1)
+            else:
+                own = np.zeros(len(centers), int)
+            rho_mid = float(np.median(rho[latc]))
+            C = tensors_at(kind, [rho_mid])[0][0]
+            rots = []
+            for i in range(k):
+                m = (own == i) & latc
+                dirs, _ = dominant_directions([s[m] for s in fl["latticeStress"]], w[m])
+                # the zone's current turn first (cost[0]): it is kept unless beaten
+                R = np.concatenate([[current[i]], candidate_rotations(C, dirs, n_random=n_rot, seed=17 * rnd + i)])
+                sig = [s[m] for s in fl["latticeStress"]]
+                junction = (fl["fs"][m] > 0.05)
+                vol = w[m]
+                cost = np.empty(len(R))
+                for j, r in enumerate(R):
+                    t = stress_rotation(r)
+                    worst = np.zeros((m.sum(), len(cand)))
+                    for s in sig:
+                        worst = np.maximum(worst, _surfaces(s @ t.T, Pc, Qc, Fc))
+                    worst = np.where(junction[:, None], worst * SKIN_JUNCTION, worst)
+                    need = need_density(worst, cand, allow, 2.0 * rho_max)
+                    cost[j] = float((vol * need).sum())
+                rots.append(_smallest(R[int(np.argmin(cost))], group))
+                say({"stage": "lattice-grade-orient", "zone": i, "screened": len(R),
+                     "massNeeded": float(cost.min()), "asLaid": float(cost[0])})
+            current = rots
+            if k > 1:
+                work["nodes"][lat]["orient"] = {"zones": [{"at": [round(float(v), 3) for v in a],
+                                                           "rotate": [round(float(v), 3) for v in _rotvec_deg(r)]}
+                                                          for a, r in zip(at, rots)], "blend": cell}
+                if seam:
+                    work["nodes"][lat]["orient"]["seam"] = float(seam)
+            else:
+                work["nodes"][lat]["orient"] = [round(float(v), 3) for v in _rotvec_deg(rots[0])]
+            # re-read the stresses in the turned lattice before sizing on
+            rep = analyze(G, origin, pitch)
+            fl = rep["fields"]
+            G, fl, allow = run_sizing(G, fl, allow, f"size-after-orient-{rnd}")
+    out = copy.deepcopy(work)
+    if best is not None and best.get("orient") is not None:
+        out["nodes"][lat]["orient"] = best["orient"]
+    elif best is not None:
+        out["nodes"][lat].pop("orient", None)
+    return {"doc": out, "lattice": lat, "densityNode": dens, "source": SOURCE,
+            "density": None if best is None else {"origin": origin.tolist(), "pitch": pitch,
+                                                  "values": best["values"]},
+            "best": None if best is None else {k: v for k, v in best.items() if k != "values"},
+            "target": target, "densityLimits": [rho_min, rho_max], "history": history, "guard": guard,
+            "seconds": time.time() - t0}