loadpath 0.1.1__py3-none-any.whl

loadpath/thermal.py

@@ -0,0 +1,1691 @@
+"""
+Steady heat conduction on the voxel grid, and topology optimization with it:
+conductors and heat sinks on their own, and parts that have to carry load
+and get rid of heat at once (a NEMA 17 bracket next to a 60 C motor).
+
+The analysis is the scalar twin of fem.py: 8-node hexahedra, all the same
+cube, one element conduction matrix scaled per cell by its conductivity.
+Boundary conditions are the three a printed part sees:
+
+- fixed temperature (Dirichlet) on nodes: a sink bolted to a frame, a motor
+  face held at its case temperature;
+- heat input in W, spread over a region's nodes or cells: a die, a coil, a
+  contact patch;
+- convection h (T - T_fluid) on cell faces, with a per-face coefficient and
+  fluid temperature. The faces that convect are the part's own surface, so
+  under optimization they move with the design: every face between two
+  cells convects in proportion to how different their densities are, and a
+  face on the grid's outside in proportion to its cell's density. A crisp
+  solid part therefore convects exactly on its skin, and the optimizer
+  sees what adding a fin buys (Yoon & Kim's smeared-interface idea, with a
+  smooth |.| so the gradient exists).
+
+Temperatures are solved relative to `ambient`, so ambient-temperature sinks
+and fluids add nothing to the right-hand side.
+
+Optimization is SIMP on conductivity, k(x) = kmin + x^3 (1 - kmin), with the
+density filter, Heaviside continuation and robust erosion of simp.py, and
+MMA (mma.py) because with convection the sensitivities change sign: a fin
+in the wrong place hides surface that was convecting. Objectives are the
+mean temperature rise of a region (default: power-weighted over the heat
+inputs, i.e. thermal compliance divided by the power), so the adjoint is
+one extra solve, or none when it equals the state.
+
+Thermo-mechanical coupling (`optimize_thermomechanical`) is one-way:
+temperature softens the polymer. Each cell's modulus is derated by the
+material's retention curve at its temperature (PETG keeps about 60% of its
+stiffness at 65 C), the design's own temperature field decides where, and
+the compliance gradient carries the thermal adjoint, so the optimizer knows
+that material near the motor is both hot and soft, and that material which
+conducts heat into the structure softens it. A weighted temperature term
+can be added to the objective as well.
+
+Thermal expansion (`alpha=` on optimize_thermomechanical, and
+`thermoelastic` to rate a design): each cell wants to grow by
+alpha (T - t_ref), fem.thermal_load turns what stops it into nodal forces,
+and the stress comes off the elastic part of the strain. The objective is
+then twice the elastic strain energy, which is the compliance without
+expansion: f.u would count the work of free growth and pay the optimizer
+to cut whatever hot material moves most. The load depends on density and
+on the design's temperature, so the gradient takes a mechanical adjoint
+besides the thermal one. Checked against a bar held between rollers
+(sigma = -E alpha dT exactly) and Timoshenko's bimetal strip (within 2.5%
+at 4 cells per layer); bench/thermal_expansion.py runs the motor mount.
+
+A study's `thermal` block (spec.Thermal) comes in through StudyHeat:
+build_domain hangs one on the Domain, simp's loop re-solves the design's
+temperature every iteration and folds softening, expansion and their
+gradients (mechanical and thermal adjoints, as above) into the ordinary
+optimizer, and verify_part solves the delivered part's temperature, derates
+moduli and strength by it and takes the free expansion off the stress.
+
+Heat-up and cool-down (`transient`, `solve_cycle`): backward Euler on the
+same conduction system with a lumped capacity (density times the card's
+specific heat, SPECIFIC_HEAT). A duty cycle (Cycle: heat on for `on` s of
+every `period`) is solved to its repeating state from the steady state at
+the mean power, which takes a few periods rather than the part's warm-up.
+Checked against the Fourier series for a bar heated at one end (0.3% at 50
+steps, first order) and the closed form for a lumped block under a square
+wave (0.2%).
+
+Units: mm, W, K (or C) throughout; conductivity is given in W/(m K) and
+convection in W/(m^2 K) at the edges, as datasheets quote them, and
+converted here.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+
+import numpy as np
+import scipy.sparse as sp
+from scipy.sparse.linalg import cg
+
+from .fem import CORNERS, HexMesh
+from .material_library import LIBRARY as _LIBRARY
+from .mma import MMA
+
+__all__ = [
+    "CONDUCTIVITY", "MODULUS_RETENTION", "conductivity", "retention", "hex8_kt", "ThermalGrid",
+    "thermal_grid", "grid_from_domain", "Faces", "Conduction", "ScalarSolver", "ThermalBC",
+    "Convection", "nodes_in", "cells_in", "thermal_bc", "solve_temperature", "ThermalResult",
+    "ThermalOptions", "ThermalOptResult", "optimize_thermal", "optimize_thermomechanical",
+    "EXPANSION", "expansion", "thermoelastic", "StudyHeat", "study_heat", "study_thermal_bc",
+    "SPECIFIC_HEAT", "specific_heat", "node_capacity", "transient", "Cycle", "CycleResult", "solve_cycle",
+]
+
+# W/(m K), dense printed parts, in plane, from the material library's cards
+# (material_library.py cites each: Tychanicz-Kwiecien et al. 2025 for PLA
+# and PETG, the AddUp sheets for AlSi10Mg and 316L, estimates otherwise).
+# FDM conducts 10-30% worse across layers.
+CONDUCTIVITY = {k: float(c["values"]["conductivity"][0]) for k, c in _LIBRARY.items()
+                if "conductivity" in c["values"]}
+
+# Fraction of room-temperature modulus kept at temperature (C), piecewise
+# linear, from the cards' `retention` (read off typical DMA curves and
+# checked against each card's heat deflection temperature; approximate,
+# and the cliff at the glass transition is where sources disagree most).
+MODULUS_RETENTION = {k: [tuple(p) for p in c["values"]["retention"][0]] for k, c in _LIBRARY.items()
+                     if "retention" in c["values"]}
+
+# Linear thermal expansion, 1/K, near room temperature, from the cards'
+# `cte` (um/(m K); Formlabs and AddUp sheets where they give it, estimates
+# for the filaments, whose datasheets don't). FDM parts in plane, PA-CF
+# along the fibres it is laid with. Printed polymers grow 5-10x more than
+# aluminium, which is what loads a plastic part bolted to a metal frame
+# when the motor beside it warms up.
+EXPANSION = {k: float(c["values"]["cte"][0]) / 1e6 for k, c in _LIBRARY.items() if "cte" in c["values"]}
+
+# J/(kg K) near room temperature, from the cards' `specificHeat` (polymer
+# handbook values for the families, the alloy handbook for metals): with
+# density it sets how fast a part heats up and cools down.
+SPECIFIC_HEAT = {k: float(c["values"]["specificHeat"][0]) for k, c in _LIBRARY.items()
+                 if "specificHeat" in c["values"]}
+
+K_MIN = 1e-3          # void conductivity, relative to the material's
+C_MIN = 1e-3          # void heat capacity, relative to the material's
+PENALTY = 3.0
+_SMOOTH = 0.05        # smoothing of |rho_i - rho_j| on interface faces
+
+
+def _material_key(material) -> str:
+    name = getattr(material, "name", material)
+    from .materials import _ALIASES
+    key = str(name).strip().lower()
+    return _ALIASES.get(key, key)
+
+
+def conductivity(material) -> float:
+    """W/(m K) for a material name (or Material), from CONDUCTIVITY."""
+    key = _material_key(material)
+    if key not in CONDUCTIVITY:
+        raise ValueError(f"no conductivity for {material!r}; known: {sorted(CONDUCTIVITY)} (or pass k)")
+    return CONDUCTIVITY[key]
+
+
+def expansion(material) -> float:
+    """1/K for a material name (or Material), from EXPANSION."""
+    key = _material_key(material)
+    if key not in EXPANSION:
+        raise ValueError(f"no expansion coefficient for {material!r}; known: {sorted(EXPANSION)} (or pass a number)")
+    return EXPANSION[key]
+
+
+def specific_heat(material) -> float:
+    """J/(kg K) for a material name (or Material), from SPECIFIC_HEAT."""
+    key = _material_key(material)
+    if key not in SPECIFIC_HEAT:
+        raise ValueError(f"no specific heat for {material!r}; known: {sorted(SPECIFIC_HEAT)} (or pass one)")
+    return SPECIFIC_HEAT[key]
+
+
+def retention(material, t: np.ndarray):
+    """(modulus retention, its derivative per K) at temperatures t (C)."""
+    pts = MODULUS_RETENTION[_material_key(material)] if not isinstance(material, (list, tuple)) else material
+    tt = np.array([p[0] for p in pts], float)
+    gg = np.array([p[1] for p in pts], float)
+    t = np.asarray(t, float)
+    g = np.interp(t, tt, gg)
+    seg = np.clip(np.searchsorted(tt, t) - 1, 0, len(tt) - 2)
+    slope = (gg[seg + 1] - gg[seg]) / (tt[seg + 1] - tt[seg])
+    dg = np.where((t > tt[0]) & (t < tt[-1]), slope, 0.0)
+    return g, dg
+
+
+def hex8_kt() -> np.ndarray:
+    """Conduction matrix (8x8) of a unit cube with k = 1, 2x2x2 Gauss. For side
+    h and conductivity k the element matrix is k * h * this."""
+    s = 2.0 * CORNERS - 1.0
+    g = 1.0 / np.sqrt(3.0)
+    kt = np.zeros((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.25 * s[:, 0] * (1 + eta * s[:, 1]) * (1 + zeta * s[:, 2])
+                dn[:, 1] = 0.25 * s[:, 1] * (1 + xi * s[:, 0]) * (1 + zeta * s[:, 2])
+                dn[:, 2] = 0.25 * s[:, 2] * (1 + xi * s[:, 0]) * (1 + eta * s[:, 1])
+                kt += dn @ dn.T * 0.125
+    return 0.5 * (kt + kt.T)
+
+
+# Consistent face matrix of a bilinear square of area 1, corners in cyclic
+# order: int N_i N_j dA.
+_FACE_M = np.array([[4, 2, 1, 2], [2, 4, 2, 1], [1, 2, 4, 2], [2, 1, 2, 4]], float) / 36.0
+
+
+def _face_corners(axis: int, side: int) -> list:
+    b, c = [a for a in range(3) if a != axis]
+    out = []
+    for u, v in ((0, 0), (1, 0), (1, 1), (0, 1)):
+        out.append((side << axis) | (u << b) | (v << c))
+    return out
+
+
+# ---------------------------------------------------------------- the grid
+
+
+@dataclass
+class ThermalGrid:
+    """What the thermal solver and optimizer need of a voxel domain. Duck-
+    types simp.Domain for simp.density_filter (mesh, pitch, dims)."""
+    pitch: float
+    origin: np.ndarray
+    dims: tuple
+    mesh: HexMesh
+    preserve: np.ndarray            # bool per element
+    mirror: dict = field(default_factory=dict)
+
+    @property
+    def n_elem(self):
+        return self.mesh.n_elem
+
+    def full_grid(self, values, fill=0.0):
+        g = np.full(self.dims, fill, float)
+        g[tuple(self.mesh.elem_ijk.T)] = values
+        return g
+
+
+def thermal_grid(design_space, pitch: float, preserve=(), keep_out=(), symmetry=()) -> ThermalGrid:
+    """Voxelize shapes (lists of shapes.Shape) the way domain.build_domain
+    does, without the supports a mechanical domain needs."""
+    from .domain import _fraction
+
+    design_space = list(design_space) if isinstance(design_space, (list, tuple)) else [design_space]
+    lo = np.min([s.bounds()[0] for s in design_space], axis=0)
+    hi = np.max([s.bounds()[1] for s in design_space], axis=0)
+    dims = np.maximum(np.ceil((hi - lo) / pitch - 1e-9).astype(int), 1)
+    origin = 0.5 * (lo + hi) - 0.5 * dims * pitch
+    ii, jj, kk = np.meshgrid(*[np.arange(d) for d in dims], indexing="ij")
+    ijk = np.stack([ii.ravel(), jj.ravel(), kk.ravel()], axis=1)
+    centers = origin + (ijk + 0.5) * pitch
+    design_f = _fraction(design_space, centers, pitch)
+    pres_f = _fraction(list(preserve), centers, pitch)
+    keep_f = _fraction(list(keep_out), centers, pitch)
+    pres = (pres_f >= 0.5) & (keep_f < 0.5)
+    active = pres | ((design_f >= 0.5) & (keep_f == 0))
+    if not active.any():
+        raise ValueError("the design space is empty after removing keep-outs")
+    mesh = HexMesh(ijk[active], pitch, origin)
+    mirror = {}
+    for axis in symmetry:
+        a = "xyz".index(axis)
+        m_ijk = mesh.elem_ijk.copy()
+        m_ijk[:, a] = dims[a] - 1 - m_ijk[:, a]
+        lut = np.full(dims, -1, np.int64)
+        lut[tuple(mesh.elem_ijk.T)] = np.arange(mesh.n_elem)
+        mirror[axis] = lut[tuple(m_ijk.T)]
+    return ThermalGrid(float(pitch), origin, tuple(int(d) for d in dims), mesh, pres[active], mirror)
+
+
+def grid_from_domain(domain) -> ThermalGrid:
+    """The thermal view of a mechanical simp.Domain: same cells, same nodes."""
+    return ThermalGrid(domain.pitch, domain.origin, domain.dims, domain.mesh, domain.preserve.copy(),
+                       dict(domain.mirror))
+
+
+def nodes_in(mesh: HexMesh, shape, tol: float | None = None) -> np.ndarray:
+    """Bool per node: inside `shape` or within `tol` (default half a cell)."""
+    tol = 0.5 * mesh.pitch if tol is None else tol
+    return shape.sdf(mesh.node_xyz) <= tol
+
+
+def cells_in(mesh: HexMesh, shape) -> np.ndarray:
+    return shape.sdf(mesh.elem_centers()) <= 0
+
+
+# ------------------------------------------------------------- the faces
+
+
+class Faces:
+    """Every cell face that can convect: faces between two active cells
+    (`b` >= 0) and faces on the outside of the active set (`b` == -1).
+
+    a, b: the cells on either side (normal points from a to b); nodes: (nf, 4)
+    in cyclic order; center, normal: (nf, 3)."""
+
+    def __init__(self, mesh: HexMesh):
+        ijk = mesh.elem_ijk
+        dims = mesh.node_dims - 1
+        lut = np.full(tuple(dims), -1, np.int64)
+        lut[tuple(ijk.T)] = np.arange(mesh.n_elem)
+        a_l, b_l, n_l, c_l, nrm_l = [], [], [], [], []
+        for axis in range(3):
+            for side in (0, 1):
+                nb = ijk.copy()
+                nb[:, axis] += 2 * side - 1
+                ok = (nb[:, axis] >= 0) & (nb[:, axis] < dims[axis])
+                j = np.full(mesh.n_elem, -1, np.int64)
+                j[ok] = lut[tuple(nb[ok].T)]
+                # internal faces once (from the lower cell), boundary faces always
+                take = (j < 0) | ((j >= 0) & (side == 1))
+                ii = np.nonzero(take)[0]
+                corners = _face_corners(axis, side)
+                a_l.append(ii)
+                b_l.append(j[ii])
+                n_l.append(mesh.enode[ii][:, corners])
+                cen = mesh.origin + (ijk[ii] + 0.5) * mesh.pitch
+                cen[:, axis] += (side - 0.5) * mesh.pitch
+                c_l.append(cen)
+                nrm = np.zeros((len(ii), 3))
+                nrm[:, axis] = 2 * side - 1
+                nrm_l.append(nrm)
+        self.a = np.concatenate(a_l)
+        self.b = np.concatenate(b_l)
+        self.nodes = np.concatenate(n_l)
+        self.center = np.concatenate(c_l)
+        self.normal = np.concatenate(nrm_l)
+        self.area = mesh.pitch ** 2
+        self.boundary = self.b < 0
+
+    def __len__(self):
+        return len(self.a)
+
+    def exposure(self, rho: np.ndarray):
+        """Per face: how much of it is solid-against-void (0..1) at densities
+        rho, and its derivatives with respect to rho_a and rho_b."""
+        ra = rho[self.a]
+        rb = np.where(self.boundary, 0.0, rho[np.maximum(self.b, 0)])
+        d = ra - rb
+        e = _SMOOTH
+        norm = np.sqrt(1 + e * e) - e
+        r = np.sqrt(d * d + e * e)
+        s = (r - e) / norm
+        ds = d / r / norm
+        s = np.where(self.boundary, ra, s)
+        ds_a = np.where(self.boundary, 1.0, ds)
+        ds_b = np.where(self.boundary, 0.0, -ds)
+        return s, ds_a, ds_b
+
+
+@dataclass
+class Convection:
+    """Convection to a fluid at `fluid_t` with coefficient `h` W/(m^2 K) on the
+    faces `where` selects: None (all), a Shape (face centers within half a cell
+    of it), or a callable (centers, normals) -> bool. `boundary` / `internal`
+    restrict it to the grid's outside or to faces between cells (the surface
+    the design grows)."""
+    h: float
+    fluid_t: float | None = None     # None: ambient
+    where: object = None
+    boundary: bool = True
+    internal: bool = True
+
+
+@dataclass
+class ThermalBC:
+    ambient: float                     # C; temperatures are solved relative to it
+    fixed: np.ndarray                  # bool per node
+    fixed_t: np.ndarray                # C per node (used where fixed)
+    heat: np.ndarray                   # W per node
+    face_h: np.ndarray                 # W/(mm^2 K) per face (0: none)
+    face_t: np.ndarray                 # fluid C per face
+    faces: Faces
+    heat_nodes: np.ndarray             # bool per node: where heat goes in
+
+    @property
+    def power(self):
+        return float(self.heat.sum())
+
+
+def thermal_bc(mesh: HexMesh, *, ambient: float = 25.0, temperatures=(), heat=(), convection=(),
+               faces: Faces | None = None) -> ThermalBC:
+    """Assemble boundary conditions.
+
+    temperatures: [(Shape or node mask, C)]; heat: [(Shape / node mask, W)] or
+    [(Shape / cell mask, W, "volume")] spread over the region's cells by
+    volume; convection: [Convection]."""
+    faces = faces or Faces(mesh)
+    nn = mesh.n_nodes
+    fixed = np.zeros(nn, bool)
+    fixed_t = np.full(nn, float(ambient))
+    for region, t in temperatures:
+        m = region if isinstance(region, np.ndarray) else nodes_in(mesh, region)
+        if not m.any():
+            raise ValueError("a fixed temperature touches no node of the grid")
+        fixed |= m
+        fixed_t[m] = float(t)
+    q = np.zeros(nn)
+    heat_nodes = np.zeros(nn, bool)
+    for item in heat:
+        region, watts = item[0], float(item[1])
+        if len(item) > 2 and item[2] == "volume":
+            cm = region if isinstance(region, np.ndarray) else cells_in(mesh, region)
+            if not cm.any():
+                raise ValueError("a volume heat source covers no cell of the grid")
+            per = watts / cm.sum() / 8.0
+            np.add.at(q, mesh.enode[cm].ravel(), per)
+            heat_nodes[mesh.enode[cm].ravel()] = True
+        else:
+            m = region if isinstance(region, np.ndarray) else nodes_in(mesh, region)
+            if not m.any():
+                raise ValueError("a heat input touches no node of the grid")
+            # weighted by the cells each node touches, so a flux over a face
+            # is spread as the face's area is (corners a quarter, edges a half)
+            w = np.bincount(mesh.enode.ravel(), minlength=nn).astype(float) * m
+            q += watts * w / w.sum()
+            heat_nodes |= m
+    face_h = np.zeros(len(faces))
+    face_t = np.full(len(faces), float(ambient))
+    for cv in convection:
+        sel = np.ones(len(faces), bool)
+        if cv.where is not None:
+            if callable(cv.where) and not hasattr(cv.where, "sdf"):
+                sel = np.asarray(cv.where(faces.center, faces.normal), bool)
+            else:
+                sel = cv.where.sdf(faces.center) <= 0.5 * mesh.pitch
+        if not cv.boundary:
+            sel &= ~faces.boundary
+        if not cv.internal:
+            sel &= faces.boundary
+        face_h[sel] = float(cv.h) * 1e-6
+        face_t[sel] = float(ambient if cv.fluid_t is None else cv.fluid_t)
+    return ThermalBC(float(ambient), fixed, fixed_t, q, face_h, face_t, faces, heat_nodes)
+
+
+# ---------------------------------------------------------- the assembly
+
+
+class Conduction:
+    """CSR layout for a HexMesh's scalar conduction matrix. `assemble(k, rho)`
+    takes per-element conductivity k (W/(mm K)) and densities rho (which set
+    the convecting surface) and returns (matrix with Dirichlet rows, rhs).
+
+    `porous`: while a design is still grey, a uniform field has no interfaces
+    and so no convecting surface, and the only faces that convect are on the
+    grid's outside: the optimizer then pushes everything there (a ring of pins
+    round the edge of a heat sink). A grey cell is treated as a porous medium
+    instead, with 4 rho (1 - rho) * `porous` faces' worth of wetted area,
+    which is gone once the design is crisp. Set by the optimizer; 0 for
+    analysis."""
+
+    def __init__(self, mesh: HexMesh, bc: ThermalBC, porous: float = 0.0):
+        self.mesh = mesh
+        self.bc = bc
+        self.kt = hex8_kt() * mesh.pitch
+        nn = mesh.n_nodes
+        en = mesh.enode
+        rows = np.repeat(en, 8, axis=1).ravel()
+        cols = np.tile(en, (1, 8)).ravel()
+        keys = rows * nn + cols
+        uniq, self._inv = np.unique(keys, return_inverse=True)
+        self._inv = self._inv.astype(np.int64)
+        self.indices = (uniq % nn).astype(np.int32)
+        r = uniq // nn
+        self.indptr = np.concatenate([[0], np.cumsum(np.bincount(r, minlength=nn))]).astype(np.int32)
+        self.nnz = len(uniq)
+        self._kflat = self.kt.ravel()
+        # face node pairs -> slots (always within one element, so present)
+        faces = bc.faces
+        fn = faces.nodes
+        conv = np.nonzero(bc.face_h > 0)[0]
+        self.conv = conv
+        frow = np.repeat(fn[conv], 4, axis=1).ravel()
+        fcol = np.tile(fn[conv], (1, 4)).ravel()
+        self._fslot = np.searchsorted(uniq, frow * nn + fcol)
+        self._fm = _FACE_M.ravel() * faces.area
+        # porous convection: per cell, the strongest internal convection of
+        # its faces (lumped onto its corners' diagonal)
+        inner = conv[~faces.boundary[conv]]
+        self.cell_h = np.zeros(mesh.n_elem)
+        self.cell_dt = np.zeros(mesh.n_elem)
+        for side in (faces.a[inner], faces.b[inner]):
+            take = bc.face_h[inner] > self.cell_h[side]
+            self.cell_h[side[take]] = bc.face_h[inner][take]
+            self.cell_dt[side[take]] = bc.face_t[inner][take] - bc.ambient
+        self._dslot = np.searchsorted(uniq, en.ravel() * nn + en.ravel()).reshape(-1, 8)
+        self.porous = float(porous)
+        fixed = bc.fixed
+        self._keep = ~(fixed[r] | fixed[self.indices])
+        self._diag_fixed = np.nonzero((r == self.indices) & fixed[r])[0]
+        self.theta_fixed = np.where(fixed, bc.fixed_t - bc.ambient, 0.0)
+
+    def _porous(self, rho):
+        a = self.porous * self.mesh.pitch ** 2
+        return a * 4 * rho * (1 - rho), a * 4 * (1 - 2 * rho)
+
+    def _data(self, k, rho):
+        data = np.bincount(self._inv, weights=(np.asarray(k, float)[:, None] * self._kflat).ravel(),
+                           minlength=self.nnz)
+        if len(self.conv):
+            s = self.bc.faces.exposure(rho)[0]
+            w = (self.bc.face_h[self.conv] * s[self.conv])[:, None] * self._fm
+            data += np.bincount(self._fslot, weights=w.ravel(), minlength=self.nnz)
+        if self.porous > 0:
+            sv = self._porous(rho)[0] * self.cell_h / 8.0
+            data += np.bincount(self._dslot.ravel(), weights=np.repeat(sv, 8), minlength=self.nnz)
+        return data
+
+    def load(self, rho):
+        """Right-hand side before Dirichlet lifting: heat in plus convection
+        from fluids that are not at ambient."""
+        f = self.bc.heat.copy()
+        c = self.conv
+        if len(c):
+            s = self.bc.faces.exposure(rho)[0]
+            dt = self.bc.face_t[c] - self.bc.ambient
+            w = self.bc.face_h[c] * s[c] * dt * self.bc.faces.area / 4.0
+            if np.any(w):
+                np.add.at(f, self.bc.faces.nodes[c].ravel(), np.repeat(w, 4))
+        if self.porous > 0 and np.any(self.cell_dt):
+            w = self._porous(rho)[0] * self.cell_h * self.cell_dt / 8.0
+            np.add.at(f, self.mesh.enode.ravel(), np.repeat(w, 8))
+        return f
+
+    def has_sink(self, rho):
+        if self.bc.fixed.any():
+            return True
+        s = self.bc.faces.exposure(rho)[0]
+        return bool(np.any(self.bc.face_h * s > 0)) or bool(self.porous > 0 and np.any(self.cell_h > 0))
+
+    def assemble(self, k, rho):
+        nn = self.mesh.n_nodes
+        data = self._data(k, rho)
+        f = self.load(rho)
+        if self.bc.fixed.any():
+            full = sp.csr_matrix((data, self.indices, self.indptr), shape=(nn, nn))
+            f = f - full @ self.theta_fixed
+            # Identity rows scaled like the rest of the matrix (k h is ~1e-4
+            # W/K for a polymer at 1 mm): unscaled, the fixed values dominate
+            # the residual norm and CG stops before the free rows converge.
+            dval = float(np.mean(full.diagonal()))
+            f[self.bc.fixed] = dval * self.theta_fixed[self.bc.fixed]
+            data = data * self._keep
+            data[self._diag_fixed] = dval
+        mat = sp.csr_matrix((data, self.indices, self.indptr), shape=(nn, nn))
+        mat.has_sorted_indices = True
+        return mat, f
+
+    def residual(self, k, rho, theta):
+        """K theta - f without Dirichlet rows: at fixed nodes, minus the heat
+        they inject."""
+        nn = self.mesh.n_nodes
+        full = sp.csr_matrix((self._data(k, rho), self.indices, self.indptr), shape=(nn, nn))
+        return full @ theta - self.load(rho)
+
+    def elem_energy(self, lam, theta):
+        """Per element lam_e^T Kt theta_e at unit conductivity."""
+        en = self.mesh.enode
+        return np.einsum("ij,jk,ik->i", lam[en], self.kt, theta[en])
+
+    def convection_gradient(self, rho, lam, theta):
+        """Per element d(lam^T R)/d rho from the convection terms."""
+        g = np.zeros(len(rho))
+        c = self.conv
+        if len(c):
+            faces = self.bc.faces
+            _, ds_a, ds_b = faces.exposure(rho)
+            fn = faces.nodes[c]
+            a = faces.area
+            fe = np.einsum("ij,jk,ik->i", lam[fn], _FACE_M * a, theta[fn])
+            fe -= lam[fn].sum(axis=1) * (self.bc.face_t[c] - self.bc.ambient) * a / 4.0
+            fe *= self.bc.face_h[c]
+            g += np.bincount(faces.a[c], weights=fe * ds_a[c], minlength=len(rho))
+            inner = faces.b[c] >= 0
+            g += np.bincount(faces.b[c][inner], weights=(fe * ds_b[c])[inner], minlength=len(rho))
+        if self.porous > 0:
+            en = self.mesh.enode
+            dsv = self._porous(rho)[1]
+            pe = (lam[en] * theta[en]).sum(axis=1) - lam[en].sum(axis=1) * self.cell_dt
+            g += dsv * self.cell_h / 8.0 * pe
+        return g
+
+
+class ScalarSolver:
+    """CG + smoothed-aggregation AMG for a scalar diffusion matrix, keeping
+    the hierarchy across solves while it still works (as fem.Solver)."""
+
+    def __init__(self, rtol=1e-8, maxiter=2000, rebuild_after_iters=40):
+        self.rtol, self.maxiter, self.rebuild_after_iters = rtol, maxiter, rebuild_after_iters
+        self._ml = None
+        self.last_iters = 0
+
+    def invalidate(self):
+        self._ml = None
+
+    def _precond(self, mat):
+        if self._ml is None:
+            from .fem import amg_solver
+            self._ml = amg_solver(mat, symmetry="hermitian", max_coarse=400, coarse_solver="splu")
+        return self._ml.aspreconditioner(cycle="V")
+
+    def solve(self, mat, f, x0=None):
+        count = [0]
+
+        def cb(_):
+            count[0] += 1
+
+        # the system is scaled by the conductivity, which can be tiny (W/mm K)
+        scale = float(np.abs(f).max()) or 1.0
+        t, info = cg(mat, f / scale, x0=None if x0 is None else x0 / scale, rtol=self.rtol,
+                     maxiter=self.maxiter, M=self._precond(mat), callback=cb)
+        if info != 0:
+            self._ml = None
+            count[0] = 0
+            t, info = cg(mat, f / scale, x0=t, rtol=self.rtol, maxiter=self.maxiter,
+                         M=self._precond(mat), callback=cb)
+        self.last_iters = count[0]
+        if count[0] > self.rebuild_after_iters:
+            self._ml = None
+        if info != 0:
+            raise RuntimeError(f"thermal solve did not converge ({count[0]} iterations); is any heat "
+                               "path to a fixed temperature or a convecting face?")
+        return t * scale
+
+
+@dataclass
+class ThermalResult:
+    temperature: np.ndarray          # C per node
+    elem_temperature: np.ndarray     # C per element (mean of its nodes)
+    max_t: float
+    heat_in: float                   # W
+    heat_out_fixed: float            # W leaving through fixed temperatures (negative: entering)
+    heat_out_convection: float       # W leaving by convection
+    resistance: float                # K/W: mean rise over the heat inputs per W (nan without heat)
+
+    def mean_t(self, nodes):
+        return float(self.temperature[nodes].mean())
+
+
+def solve_temperature(mesh: HexMesh, k, bc: ThermalBC, density=None, solver: ScalarSolver | None = None,
+                      conduction: Conduction | None = None) -> ThermalResult:
+    """Steady temperatures on `mesh`. k: conductivity in W/(m K), scalar or per
+    element; density (per element, default solid) scales it SIMP-wise and
+    sets which faces convect."""
+    rho = np.ones(mesh.n_elem) if density is None else np.asarray(density, float)
+    kk = np.broadcast_to(np.asarray(k, float) * 1e-3, (mesh.n_elem,))
+    ke = kk * (K_MIN + rho ** PENALTY * (1 - K_MIN))
+    cond = conduction or Conduction(mesh, bc)
+    if not cond.has_sink(rho):
+        raise ValueError("no heat path out: add a fixed temperature or convection")
+    mat, f = cond.assemble(ke, rho)
+    theta = (solver or ScalarSolver()).solve(mat, f)
+    t = theta + bc.ambient
+    # heat balance: reaction at the fixed nodes, convection integral
+    out_fixed = -float(cond.residual(ke, rho, theta)[bc.fixed].sum())
+    c = cond.conv
+    s = bc.faces.exposure(rho)[0]
+    th_face = theta[bc.faces.nodes[c]].mean(axis=1)
+    out_conv = float(np.sum(bc.face_h[c] * s[c] * bc.faces.area * (th_face - (bc.face_t[c] - bc.ambient))))
+    q = bc.heat
+    res = float((q @ theta) / q.sum() ** 2) if q.sum() > 0 else float("nan")
+    return ThermalResult(t, t[mesh.enode].mean(axis=1), float(t.max()), float(q.sum()), out_fixed, out_conv, res)
+
+
+# ------------------------------------------------------------ transient
+
+
+def node_capacity(mesh: HexMesh, volumetric, density=None) -> np.ndarray:
+    """Lumped heat capacity per node, J/K: volumetric heat capacity
+    (J/(mm^3 K), rho c_p; scalar or per element) times each cell's volume,
+    a corner holding an eighth, linear in density down to C_MIN."""
+    rho = np.ones(mesh.n_elem) if density is None else np.asarray(density, float)
+    ce = np.broadcast_to(np.asarray(volumetric, float), (mesh.n_elem,)) * mesh.pitch ** 3 \
+        * (C_MIN + rho * (1 - C_MIN))
+    return np.bincount(mesh.enode.ravel(), weights=np.repeat(ce / 8.0, 8), minlength=mesh.n_nodes)
+
+
+class _Stepper:
+    """Backward Euler on the conduction system with a lumped capacity:
+    (K + C/dt) theta_n+1 = C/dt theta_n + f, with the heat inputs scaled
+    (switched on and off by a duty cycle). Temperatures relative to ambient;
+    fixed temperatures held. One CG solver per step size, warm-started from
+    the last step."""
+
+    def __init__(self, mesh, k, bc, capacity, density=None, conduction=None):
+        rho = np.ones(mesh.n_elem) if density is None else np.asarray(density, float)
+        kk = np.broadcast_to(np.asarray(k, float) * 1e-3, (mesh.n_elem,))
+        ke = kk * (K_MIN + rho ** PENALTY * (1 - K_MIN))
+        cond = conduction or Conduction(mesh, bc)
+        self.mat, self.f = cond.assemble(ke, rho)
+        self.free = ~bc.fixed
+        self.heat = np.where(bc.fixed, 0.0, bc.heat)
+        self.c = np.where(self.free, np.asarray(capacity, float), 0.0)
+        self.sink = cond.has_sink(rho)
+        self._sys = {}
+
+    def rhs(self, scale):
+        return self.f - (1.0 - scale) * self.heat
+
+    def steady(self, scale=1.0, x0=None):
+        if not self.sink:
+            raise ValueError("no heat path out: add a fixed temperature or convection")
+        if "steady" not in self._sys:
+            self._sys["steady"] = ScalarSolver(rtol=1e-9)
+        return self._sys["steady"].solve(self.mat, self.rhs(scale), x0)
+
+    def step(self, theta, dt, scale=1.0):
+        key = round(float(dt), 12)
+        if key not in self._sys:
+            self._sys[key] = (self.mat + sp.diags(self.c / dt)).tocsr(), ScalarSolver(rtol=1e-9)
+        a, solver = self._sys[key]
+        return solver.solve(a, self.rhs(scale) + self.c / dt * theta, theta)
+
+
+def transient(mesh: HexMesh, k, bc: ThermalBC, capacity, dts, theta0=None, scales=1.0, density=None):
+    """Temperatures (C per node) after each step of sizes `dts` (s), from
+    theta0 (C per node; default ambient, with fixed temperatures applied at
+    once), heat inputs scaled by `scales` (one per step, or one number).
+    `capacity` is per node (node_capacity). Backward Euler: first order in
+    time and unconditionally stable."""
+    st = _Stepper(mesh, k, bc, capacity, density)
+    theta = np.zeros(mesh.n_nodes) if theta0 is None else np.asarray(theta0, float) - bc.ambient
+    scales = np.broadcast_to(np.asarray(scales, float), (len(dts),))
+    out = []
+    for dt, sc in zip(dts, scales):
+        theta = st.step(theta, dt, sc)
+        out.append(theta + bc.ambient)
+    return out
+
+
+@dataclass
+class Cycle:
+    """A duty cycle: every `period` seconds the heat inputs are on for the
+    first `on` seconds and off for the rest (fixed temperatures and fluids
+    hold). `cycles`: how many the part sees over its life (thermal-cycling
+    fatigue), or None. `steps` per period."""
+    period: float
+    on: float
+    cycles: float | None = None
+    steps: int = 48
+    # weight of the hot-to-cold swing in the optimizer's objective, relative
+    # to the hot moment's at the start (StudyHeat.sensitivities); 0: design
+    # for the hot moment alone
+    fatigue_weight: float = 0.0
+    # or instead: hold the swing's stress under the fatigue strength at
+    # `cycles` over this safety factor, a constraint (MMA in simp.optimize)
+    fatigue_sf: float | None = None
+
+
+@dataclass
+class CycleResult:
+    times: np.ndarray            # s, the steps of one period (0 = heat switching on)
+    hot: np.ndarray              # C per node at the hottest moment (highest mean over the part)
+    cold: np.ndarray             # C per node at the coldest moment
+    t_hot: float                 # s into the period
+    t_cold: float
+    node_max: np.ndarray         # C per node, highest over the period
+    node_min: np.ndarray
+    mean: np.ndarray             # C, mean over the part's nodes at each step
+    periods: int                 # periods simulated to reach the repeating cycle
+    converged: bool
+    change: float                # K: largest change over the last period
+
+
+def solve_cycle(mesh: HexMesh, k, bc: ThermalBC, capacity, cycle: Cycle, density=None, tol=0.05,
+                max_periods=60) -> CycleResult:
+    """The repeating (periodic steady) temperature cycle under a duty cycle.
+
+    Starts from the steady state at the mean power (duty times the heat):
+    modes much slower than a period sit at their mean there already, and
+    the faster ones settle within a few periods, so the cycle repeats to
+    `tol` K after a handful of periods instead of the part's full warm-up
+    (hours for a plastic bracket)."""
+    if not 0 < cycle.on < cycle.period:
+        raise ValueError("a duty cycle's heat is on for part of each period: 0 < on < period")
+    st = _Stepper(mesh, k, bc, capacity, density)
+    duty = cycle.on / cycle.period
+    theta = st.steady(duty)
+    n_on = int(np.clip(round(cycle.steps * duty), 2, cycle.steps - 2))
+    n_off = max(2, cycle.steps - n_on)
+    dts = [cycle.on / n_on] * n_on + [(cycle.period - cycle.on) / n_off] * n_off
+    sc = [1.0] * n_on + [0.0] * n_off
+    rho = np.ones(mesh.n_elem) if density is None else np.asarray(density, float)
+    part = np.zeros(mesh.n_nodes, bool)
+    part[mesh.enode[rho > 0.5].ravel()] = True
+    if not part.any():
+        part[:] = True
+    change, conv, p = np.inf, False, 0
+    for p in range(1, max_periods + 1):
+        hist = [theta]
+        for dt, s_ in zip(dts, sc):
+            theta = st.step(theta, dt, s_)
+            hist.append(theta)
+        change = float(np.abs(theta - hist[0]).max())
+        if change < tol:
+            conv = True
+            break
+    h = np.array(hist) + bc.ambient
+    mean = h[:, part].mean(axis=1)
+    times = np.concatenate([[0.0], np.cumsum(dts)])
+    ih, ic = int(np.argmax(mean)), int(np.argmin(mean))
+    return CycleResult(times, h[ih], h[ic], float(times[ih]), float(times[ic]), h.max(axis=0), h.min(axis=0),
+                       mean, p, conv, change)
+
+
+# --------------------------------------------------------- optimization
+
+
+@dataclass
+class ThermalOptions:
+    volume_fraction: float
+    filter_radius: float               # mm (simp.filter_radius gives one from a min member)
+    k: float = 0.2                     # W/(m K) of the solid
+    max_iterations: int = 100
+    beta_max: float = 16.0
+    beta_every: int = 12
+    eta: float = 0.5
+    # Robust erosion as simp.SimpOptions (physics on the eroded design, the
+    # opening delivered). Off by default here: on a 40 mm convective sink it
+    # left the die 35-75% hotter than the same run without it (36 vs 24 K,
+    # 37 vs 21 K with porous grey), since the optimizer is paid for surface
+    # and erosion takes surface away; the filter still sets the member size.
+    # Use 0.15 for load-bearing parts.
+    erode: float = 0.0
+    move: float = 0.1
+    tol: float = 0.01
+    # objective: mean temperature rise over these nodes, or None for the
+    # power-weighted rise over the heat inputs (thermal compliance / power)
+    target: np.ndarray | None = None
+    # pin cells touching fixed temperatures and heat inputs solid
+    anchor: bool = True
+    x0: np.ndarray | None = None
+    # Axis index the part is extruded along (2.5D: a spreader cut from plate),
+    # or None. Also turns off the filter's boundary padding, which would
+    # otherwise thin a plate a few cells thick to nothing.
+    extrusion: int | None = None
+    # grey cells convect as a porous medium with this many faces' worth of
+    # wetted area at rho = 0.5 (see Conduction); 0 turns it off
+    # (on the same sink: 21.0 K with it, 23.7 K without; a hand-laid forest
+    # of 2 mm pins at the same mass reads 23.0 K)
+    porous: float = 1.0
+
+
+@dataclass
+class ThermalOptResult:
+    x: np.ndarray
+    xphys: np.ndarray                  # delivered design: 0/1, connected to a heat path
+    objective: float                   # mean temperature rise, K (thermal), or the weighted sum
+    temperature: ThermalResult         # of the delivered design
+    volume_fraction: float
+    iterations: int
+    converged: bool
+    seconds: float
+    compliance: float = float("nan")   # thermo-mechanical: weighted compliance at temperature, N mm
+    case_compliance: list = field(default_factory=list)
+    history: list = field(default_factory=list)
+
+
+class _Thermal:
+    """State, objective and gradient (with respect to the eroded density) of
+    the thermal problem inside an optimization loop."""
+
+    def __init__(self, grid: ThermalGrid, bc: ThermalBC, k: float, target, porous: float = 0.0):
+        self.grid, self.bc = grid, bc
+        self.mesh = grid.mesh
+        self.k = float(k) * 1e-3
+        self.cond = Conduction(grid.mesh, bc, porous)
+        self.solver = ScalarSolver(rtol=1e-7)
+        if target is None:
+            if bc.power <= 0:
+                raise ValueError("no heat input: pass a target region to measure")
+            self.l = bc.heat / bc.power
+        else:
+            tg = np.asarray(target, bool)
+            self.l = tg / tg.sum()
+        self.l = np.where(bc.fixed, 0.0, self.l)
+        # self-adjoint when the objective weights are the loads and nothing
+        # is lifted: then lambda = theta / power
+        self.self_adjoint = target is None and not np.any(self.cond.theta_fixed) and \
+            not np.any((bc.face_h > 0) & (bc.face_t != bc.ambient)) and not np.any(self.cond.cell_dt)
+        self.theta = None
+        self.lam = None
+
+    def solve(self, rho):
+        ke = self.k * (K_MIN + rho ** PENALTY * (1 - K_MIN))
+        if not self.cond.has_sink(rho):
+            raise ValueError("no heat path out: add a fixed temperature or convection")
+        mat, f = self.cond.assemble(ke, rho)
+        self.theta = self.solver.solve(mat, f, self.theta)
+        self._mat = mat
+        return self.theta
+
+    def objective(self):
+        return float(self.l @ self.theta)
+
+    def adjoint(self, rhs, x0=None):
+        rhs = np.where(self.bc.fixed, 0.0, rhs)
+        return self.solver.solve(self._mat, rhs, x0)
+
+    def gradient(self, rho, lam):
+        """d(lam-weighted residual)/d rho: -lam^T dR/drho, i.e. the gradient of
+        a functional whose adjoint is lam."""
+        dk = self.k * PENALTY * rho ** (PENALTY - 1) * (1 - K_MIN)
+        g = -dk * self.cond.elem_energy(lam, self.theta)
+        return g - self.cond.convection_gradient(rho, lam, self.theta)
+
+    def objective_gradient(self, rho):
+        if self.self_adjoint:
+            lam = self.theta / self.bc.power
+        else:
+            self.lam = self.adjoint(self.l, self.lam)
+            lam = self.lam
+        return self.gradient(rho, lam)
+
+
+def _anchor_cells(grid, bc):
+    """Cells touching a fixed temperature or a heat input, pinned solid when
+    that is a small patch (a sink pad, a die): the boundary-padded filter
+    would otherwise make them too expensive to fill. A distributed source
+    (heat generated everywhere) is left to the optimizer."""
+    out = np.zeros(grid.mesh.n_elem, bool)
+    for nodes in (bc.fixed, bc.heat_nodes):
+        touch = nodes[grid.mesh.enode].any(axis=1)
+        if touch.sum() <= 0.03 * grid.mesh.n_elem:
+            out |= touch
+    return out
+
+
+class _Design:
+    """Filter, projection, erosion and symmetry shared by both optimizers."""
+
+    def __init__(self, grid, opts, pres):
+        from .simp import density_filter
+        self.h, self.hs = density_filter(grid, opts.filter_radius, pad=opts.extrusion is None)
+        self.ht = self.h.T.tocsr()
+        self.opts = opts
+        self.pres = pres
+        self.design = ~pres
+        self.mirror = grid.mirror
+        self.columns = None
+        if opts.extrusion is not None:
+            others = [i for i in range(3) if i != opts.extrusion]
+            ij = grid.mesh.elem_ijk[:, others]
+            _, self.columns = np.unique(ij[:, 0] * (grid.dims[others[1]] + 1) + ij[:, 1], return_inverse=True)
+
+    def tie(self, v):
+        """Symmetry and extrusion applied to a design-variable field."""
+        from .simp import _extrude, _symmetrize
+        if self.mirror:
+            v = _symmetrize(v, self.mirror)
+        return _extrude(v, self.columns, self.design)
+
+    def fields(self, x, beta):
+        from .simp import _dproject, _project
+        o = self.opts
+        xt = (self.h @ x) / self.hs
+        xp = _project(xt, beta, o.eta)
+        xe = _project(xt, beta, o.eta + o.erode)
+        dpb = _dproject(xt, beta, o.eta)
+        dpe = _dproject(xt, beta, o.eta + o.erode)
+        for v in (xp, xe):
+            v[self.pres] = 1.0
+        for v in (dpb, dpe):
+            v[self.pres] = 0.0
+        return xp, xe, dpb, dpe
+
+    def back(self, g, dp):
+        return self.tie(self.ht @ (g * dp / self.hs))
+
+    def deliver(self, x, beta):
+        from .simp import _project
+        o = self.opts
+        xt = (self.h @ x) / self.hs
+        if o.erode > 0:
+            xe = _project(xt, beta, o.eta + o.erode)
+            xe[self.pres] = 1.0
+            xp = _project((self.h @ xe) / self.hs, beta, o.eta - o.erode)
+        else:
+            xp = _project(xt, beta, o.eta)
+        xp[self.pres] = 1.0
+        return xp
+
+
+def _crisp_connected(grid, xp, bc, pres):
+    """The delivered part: cells above half density, minus pieces that touch
+    no heat input, fixed temperature or preserved cell. Convective designs
+    keep grey shells the projection never quite clears (40% of the non-void
+    cells on the 40 mm sink at beta 16), and floating specks; analysed crisp
+    and connected, the same sinks read 1-2 K different and lighter."""
+    from scipy import ndimage
+    mesh = grid.mesh
+    solid = (xp > 0.5) | pres
+    lbl, _ = ndimage.label(grid.full_grid(solid) > 0.5, structure=np.ones((3, 3, 3), bool))
+    el = lbl[tuple(mesh.elem_ijk.T)]
+    anchor = solid & ((bc.fixed | bc.heat_nodes)[mesh.enode].any(axis=1) | pres)
+    keep = np.isin(el, np.unique(el[anchor]))
+    return (solid & keep & (el > 0)).astype(float)
+
+
+def _mma_loop(grid, opts, pres, evaluate, on_iter=None, should_stop=None):
+    """Volume-constrained MMA with projection continuation. evaluate(xe) ->
+    (objective, d objective / d xe, record)."""
+    t0 = time.time()
+    n = grid.mesh.n_elem
+    design = ~pres
+    free = np.flatnonzero(design)
+    if len(free) == 0:
+        raise ValueError("nothing to optimize: every cell is preserved")
+    dz = _Design(grid, opts, pres)
+    x = np.full(n, opts.volume_fraction)
+    if opts.x0 is not None:
+        x = np.clip(np.asarray(opts.x0, float), 0.0, 1.0)
+    x[pres] = 1.0
+    x = dz.tie(x)
+    mma = MMA(len(free), 1, move=opts.move)
+    beta, since_beta = 1.0, 0
+    f_ref = None
+    history = []
+    converged = False
+    it = 0
+    for it in range(1, opts.max_iterations + 1):
+        if should_stop is not None and should_stop():
+            break
+        xp, xe, dpb, dpe = dz.fields(x, beta)
+        obj, g_xe, rec = evaluate(xe)
+        if f_ref is None:
+            f_ref = abs(obj) or 1.0
+        f0 = 10.0 * obj / f_ref
+        df0 = dz.back(10.0 * g_xe / f_ref, dpe)
+        vol = float(xp[design].mean())
+        con = vol / opts.volume_fraction - 1.0
+        dcon = dz.back(design / design.sum() / opts.volume_fraction, dpb)
+        xn = mma.update(x[free], f0, df0[free], np.array([con]), dcon[free][None, :])
+        x_new = x.copy()
+        x_new[free] = xn
+        x_new = dz.tie(x_new)
+        change = float(np.abs(x_new - x)[design].max())
+        x = x_new
+        since_beta += 1
+        rec = {"iteration": it, "objective": obj, "volume": vol, "beta": beta, "change": change,
+               "seconds": time.time() - t0, **rec}
+        history.append(rec)
+        if on_iter is not None:
+            on_iter(rec, xp)
+        if beta < opts.beta_max and (since_beta >= opts.beta_every or change < 2 * opts.tol):
+            beta = min(2 * beta, opts.beta_max)
+            since_beta = 0
+        elif beta >= opts.beta_max and since_beta >= 5 and con < 0.02:
+            if change < opts.tol or (len(history) > 6 and
+                                     abs(history[-1]["objective"] - history[-7]["objective"])
+                                     < 2e-3 * abs(history[-7]["objective"])):
+                converged = True
+                break
+    return x, dz.deliver(x, beta), it, converged, history, time.time() - t0
+
+
+def optimize_thermal(grid: ThermalGrid, bc: ThermalBC, opts: ThermalOptions, on_iter=None,
+                     should_stop=None) -> ThermalOptResult:
+    """Lay out `volume_fraction` of the design cells to minimize the mean
+    temperature rise (of opts.target, or over the heat inputs)."""
+    pres = grid.preserve.copy()
+    if opts.anchor:
+        pres |= _anchor_cells(grid, bc)
+    th = _Thermal(grid, bc, opts.k, opts.target, opts.porous)
+
+    def evaluate(xe):
+        th.solve(xe)
+        return th.objective(), th.objective_gradient(xe), {"cgIterations": th.solver.last_iters}
+
+    x, xp, it, conv, hist, secs = _mma_loop(grid, opts, pres, evaluate, on_iter, should_stop)
+    xp = _crisp_connected(grid, xp, bc, pres)
+    res = solve_temperature(grid.mesh, opts.k, bc, density=xp)
+    obj = float(th.l @ (res.temperature - bc.ambient))
+    return ThermalOptResult(x=x, xphys=xp, objective=obj, temperature=res,
+                            volume_fraction=float(xp[~pres].mean()), iterations=it, converged=conv,
+                            seconds=secs, history=hist)
+
+
+def optimize_thermomechanical(domain, nu: float, bc: ThermalBC, opts: ThermalOptions, material="petg",
+                              thermal_weight: float = 0.0, on_iter=None, should_stop=None, alpha=None,
+                              t_ref=None, modulus=None) -> ThermalOptResult:
+    """Minimize the weighted compliance of a mechanical simp.Domain whose
+    moduli are derated by temperature (`material`'s MODULUS_RETENTION, or a
+    list of (C, retention) points), plus `thermal_weight` times the mean
+    temperature rise (normalized by its starting value), for a volume.
+
+    The temperature field is the design's own: solved on the same cells with
+    `bc` every iteration, and the compliance gradient includes its adjoint.
+
+    `alpha` adds thermal expansion: True for the material's EXPANSION, a
+    number (1/K), or one per cell (a metal insert in a polymer part: the
+    mismatch warps it). Each cell then wants to grow by alpha (T - t_ref)
+    (t_ref, the stress-free temperature, defaults to bc.ambient), and
+    wherever the supports, the loads' fixtures or its neighbours stop it,
+    that is a load. It is applied in every load case, scales with the
+    cell's (derated) stiffness, so it depends on the design, and its
+    gradient (through density and through temperature) is in the
+    sensitivities. `modulus` (MPa) defaults to the material's E."""
+    from .simp import E_MIN
+
+    grid = grid_from_domain(domain)
+    mesh = domain.mesh
+    pres = grid.preserve.copy()
+    if opts.anchor:
+        pres |= _anchor_cells(grid, bc)
+    evaluate, fe, th = _thermomech_evaluator(domain, nu, bc, opts, material, thermal_weight, alpha=alpha,
+                                             t_ref=t_ref, modulus=modulus)
+    weights = np.asarray(domain.case_weights, float)
+
+    x, xp, it, conv, hist, secs = _mma_loop(grid, opts, pres, evaluate, on_iter, should_stop)
+    xp = _crisp_connected(grid, xp, bc, pres | (domain.support_nodes | domain.load_nodes)[mesh.enode].any(axis=1))
+    res = solve_temperature(mesh, opts.k, bc, density=xp)
+    ev = thermoelastic(domain, nu, xp, res.elem_temperature, material, alpha=alpha,
+                       t_ref=bc.ambient if t_ref is None else t_ref, modulus=modulus, fe=fe)
+    comp = float(np.dot(weights, ev["caseCompliance"]))
+    tobj = float(th.l @ (res.temperature - bc.ambient))
+    out = ThermalOptResult(x=x, xphys=xp, objective=tobj, temperature=res,
+                           volume_fraction=float(xp[~pres].mean()), iterations=it, converged=conv,
+                           seconds=secs, compliance=comp, case_compliance=ev["caseCompliance"], history=hist)
+    out.thermoelastic = ev
+    return out
+
+
+def _alpha_cells(alpha, material, n):
+    if alpha is None or alpha is False:
+        return None
+    a = expansion(material) if alpha is True else alpha
+    return np.asarray(a, float) * np.ones(n)
+
+
+def _modulus(material, modulus):
+    if modulus is not None:
+        return float(modulus)
+    from .materials import material_from_spec
+
+    return float(material_from_spec(material).E)
+
+
+def thermoelastic(domain, nu, xp, elem_temperature, material="petg", alpha=True, t_ref=25.0, modulus=None,
+                  fe=None, rtol=1e-6):
+    """Solve a design (densities xp) at a temperature field (per cell, C):
+    the load cases plus the thermal expansion load (alpha as in
+    optimize_thermomechanical; None for none), moduli derated by
+    temperature. Returns per-case displacements (mm), compliance (N mm),
+    twice the elastic strain energy (N mm: the optimizer's
+    objective with expansion, the compliance without), von Mises stress per cell (MPa, the expansion strain taken off) and the
+    largest displacement."""
+    from .fem import elastic_c, hex8_b_center, thermal_load, von_mises
+    from .simp import E_MIN, _Analysis
+
+    mesh = domain.mesh
+    fe = fe or _Analysis(domain, nu, rtol)
+    E0 = _modulus(material, modulus)
+    te = np.asarray(elem_temperature, float)
+    g, _ = retention(material, te)
+    e = (E_MIN + xp ** 3 * (1 - E_MIN)) * g
+    a = _alpha_cells(alpha, material, mesh.n_elem)
+    loads = list(domain.loads)
+    if a is not None:
+        # in fe's units (stiffness at E = 1, so u scaled by E0): E0 E_e eps
+        eps = a * (te - t_ref)
+        fth = thermal_load(mesh, nu, E0 * xp ** 3 * (1 - E_MIN) * g, eps, domain.fixed)
+        loads = [f + fth for f in loads] if loads else [fth]
+    us = fe.solve(e, xp, [None] * len(loads), rtol=rtol, loads=loads)
+    b = hex8_b_center() / mesh.pitch
+    c = elastic_c(1.0, nu)
+    vm = np.zeros(mesh.n_elem)
+    for u in us:
+        strain = u[mesh.edof] @ b.T / E0
+        if a is not None:
+            strain[:, :3] -= eps[:, None]
+        sig = (strain @ c.T) * (E0 * e)[:, None]
+        vm = np.maximum(vm, von_mises(sig))
+    # twice the elastic strain energy, exactly: u.(f_m - f_th) + sum E eps^2 m^T C m V
+    energy = [float(u @ f) / E0 for f, u in zip(loads, us)]
+    if a is not None:
+        cm = float(np.array([1, 1, 1, 0, 0, 0]) @ c @ np.array([1, 1, 1, 0, 0, 0])) * mesh.pitch ** 3
+        self_e = float(np.sum(E0 * xp ** 3 * (1 - E_MIN) * g * eps * eps)) * cm
+        energy = [float(u @ (f - 2 * fth)) / E0 + self_e for f, u in zip(loads, us)]
+    solid = xp > 0.5
+    disp = [np.linalg.norm(u.reshape(-1, 3), axis=1) / E0 for u in us]
+    return {"displacement": [u / E0 for u in us], "caseCompliance": [float(f @ u) / E0 for f, u in zip(loads, us)],
+            "strainEnergy2": energy, "vonMises": vm, "maxVonMises": float(vm[solid].max()) if solid.any() else 0.0,
+            "maxDisplacement": float(max(d.max() for d in disp)), "thermal": a is not None}
+
+
+def _thermomech_evaluator(domain, nu, bc, opts, material, thermal_weight, rtol=1e-4, alpha=None, t_ref=None,
+                          modulus=None):
+    """evaluate(xe) -> (objective, gradient w.r.t. xe, record) for
+    optimize_thermomechanical; normalized by the first evaluation."""
+    from .fem import elastic_c, hex8_fth
+    from .simp import ALIVE, E_MIN, _Analysis
+
+    mesh = domain.mesh
+    fe = _Analysis(domain, nu, rtol)
+    th = _Thermal(grid_from_domain(domain), bc, opts.k, opts.target, opts.porous)
+    weights = np.asarray(domain.case_weights, float)
+    a = _alpha_cells(alpha, material, mesh.n_elem)
+    tr = bc.ambient if t_ref is None else float(t_ref)
+    E0 = _modulus(material, modulus) if a is not None else 1.0
+    vth = hex8_fth(nu) * mesh.pitch ** 2
+    # m^T C0 m V: a free-growth strain's energy density at E = 1, times the cell
+    cm = float(np.array([1, 1, 1, 0, 0, 0]) @ elastic_c(1.0, nu) @ np.array([1, 1, 1, 0, 0, 0])) * mesh.pitch ** 3
+    ncase = max(1, len(domain.loads)) if a is not None else len(domain.loads)
+    state = {"us": [None] * ncase}
+    refs = {}
+
+    def evaluate(xe):
+        theta = th.solve(xe)
+        te = (theta + bc.ambient)[mesh.enode].mean(axis=1)
+        g, dg = retention(material, te)
+        estiff = E_MIN + xe ** 3 * (1 - E_MIN)
+        loads = list(domain.loads)
+        if a is not None:
+            # expansion load per cell: E0 p(x) g(T) alpha (T - t_ref) vth,
+            # p = x^3 without the void floor, and none from cells the
+            # solve leaves out (their share is ~x^3, nothing)
+            live = xe > ALIVE
+            pth = np.where(live, xe ** 3 * (1 - E_MIN), 0.0)
+            eps = a * (te - tr)
+            w = E0 * pth * g * eps
+            fth = np.bincount(mesh.edof.ravel(), weights=(w[:, None] * vth[None, :]).ravel(), minlength=mesh.n_dof)
+            fth[domain.fixed] = 0.0
+            loads = [f + fth for f in loads] if loads else [fth]
+        us = fe.solve(estiff * g, xe, state["us"], rtol=rtol, loads=loads)
+        state["us"] = us
+        cw = weights if len(weights) == len(loads) else np.ones(len(loads))
+        if a is None:
+            comp = 0.0
+            w_e = np.zeros(mesh.n_elem)           # sum_c w_c u_e^T K0 u_e
+            for ci, f in enumerate(loads):
+                comp += cw[ci] * float(f @ us[ci])
+                w_e += cw[ci] * fe.strain_energy(us[ci])
+            refs.setdefault("c", comp)
+            # explicit part, at fixed temperature
+            g_xe = -(3 * xe ** 2 * (1 - E_MIN)) * g * w_e / refs["c"]
+            # through temperature: dC/dT_e = -E_e g'(T_e) w_e, a node holds 1/8
+            # of each of its cells' temperature
+            dc_dte = -estiff * dg * w_e / refs["c"]
+        else:
+            # With expansion the objective is twice the elastic strain energy,
+            # sum_e E_e (eps - eps_th)^T C0 (eps - eps_th) V, not f.u: free
+            # growth does work on its load without stressing anything, and
+            # f.u would pay the optimizer to cut the hot material that moves
+            # most rather than the material that is fought over. Without
+            # expansion it is the compliance. In fe's units:
+            # J = u.f_m - u.f_th + E0^2 sum_e p_e g_e eps_e^2 cm V, adjoint
+            # K lam = f_m - f_th.
+            # (loads already carry f_th: f_m - f_th = f - 2 f_th)
+            lams = fe.resolve([f - 2 * fth for f in loads], state.get("lams"))
+            state["lams"] = lams
+            comp = 0.0
+            m_e = np.zeros(mesh.n_elem)           # sum_c w_c lam_e^T K0 u_e
+            q_e = np.zeros(mesh.n_elem)           # sum_c w_c (lam_e - u_e) . vth
+            self_e = E0 * E0 * eps * eps * cm
+            for ci, f in enumerate(loads):
+                u, lam = us[ci], lams[ci]
+                comp += cw[ci] * (float(u @ (f - 2 * fth)) + float(np.sum(pth * g * self_e)))
+                m_e += cw[ci] * 0.25 * (fe.strain_energy(lam + u) - fe.strain_energy(lam - u))
+                q_e += cw[ci] * ((lam - u)[mesh.edof] @ vth)
+            refs.setdefault("c", comp)
+            dp = np.where(live, 3 * xe ** 2 * (1 - E_MIN), 0.0)
+            sw = cw.sum()
+            g_xe = (-(3 * xe ** 2 * (1 - E_MIN)) * g * m_e + E0 * dp * g * eps * q_e
+                    + sw * dp * g * self_e) / refs["c"]
+            dc_dte = (-estiff * dg * m_e + E0 * pth * (dg * eps + g * a) * q_e
+                      + sw * E0 * E0 * pth * cm * (dg * eps * eps + 2 * g * eps * a)) / refs["c"]
+        rhs = np.bincount(mesh.enode.ravel(), weights=np.repeat(dc_dte / 8.0, 8), minlength=mesh.n_nodes)
+        obj = comp / refs["c"]
+        if thermal_weight > 0:
+            tj = th.objective()
+            refs.setdefault("t", abs(tj) or 1.0)
+            obj += thermal_weight * tj / refs["t"]
+            rhs = rhs + thermal_weight * th.l / refs["t"]
+        if np.any(rhs):
+            th.lam = th.adjoint(rhs, th.lam)
+            g_xe = g_xe + th.gradient(xe, th.lam)
+        rec = {"compliance" if a is None else "strainEnergy2": comp / E0, "maxT": float(theta.max() + bc.ambient),
+               "minRetention": float(g[xe > 0.5].min()) if np.any(xe > 0.5) else 1.0}
+        return obj, g_xe, rec
+
+    return evaluate, fe, th
+
+
+# ------------------------------------------------- a study's thermal block
+
+
+def study_thermal_bc(study, mesh: HexMesh) -> ThermalBC:
+    """ThermalBC on `mesh` from a study's `thermal` block (spec.Thermal):
+    region ids resolve to the study's preserve / keepOut shapes."""
+    th = study.thermal
+
+    def shape(region, sh):
+        return sh if sh is not None else study.region_shape(region)[0]
+
+    temps = [(shape(r, s), t) for r, s, t in th.temperatures]
+    heat = [(shape(r, s), w, "volume") if spread == "volume" else (shape(r, s), w)
+            for r, s, w, spread in th.heat]
+    conv = [Convection(h, fluid, None if r is None and s is None else shape(r, s))
+            for r, s, h, fluid in th.convection if h > 0]
+    if heat:
+        for (r, s, w, spread), (sh, *_) in zip(th.heat, heat):
+            if spread == "volume" and not cells_in(mesh, sh).any():
+                raise ValueError(f"thermal heat into {r or 'a shape'}: no cell of the grid is inside it")
+    return thermal_bc(mesh, ambient=th.ambient, temperatures=temps, heat=heat, convection=conv)
+
+
+class StudyHeat:
+    """A study's thermal block on a mechanical mesh, for the optimizer
+    (simp) and for verification: solve the temperature at a density, then
+    each cell's retention g(T), expansion strain eps = alpha (T - t_ref)
+    and expansion load.
+
+    In the optimizer the objective with expansion is twice the elastic
+    strain energy (see optimize_thermomechanical) and the gradient carries
+    the mechanical adjoint and the thermal one, so material that conducts
+    heat into the structure is charged for softening and growing it.
+
+    With a duty cycle (spec.Thermal.cycle) the temperature is the repeating
+    cycle's hottest moment (solve_cycle) and `cold` its coldest. A cycle is
+    dozens of solves, too many for every iteration, and holding its
+    temperature fixed between solves hid from the optimizer that cutting
+    the material round the heat makes the rest hotter (on the motor mount
+    that design ran 6 K hotter and lost 13% of its hot safety factor to the
+    one designed cold). So the hot moment is carried as a node-by-node
+    share r of the steady temperature rise at full power, hot = r * steady,
+    with r (in [0, 1]: a duty cycle never outruns full power) refreshed from
+    a cycle solve every REFRESH calls; the steady solve and its adjoint run
+    every iteration, so the gradient follows the heat path with r held.
+    Verification solves the cycle on the delivered part."""
+
+    REFRESH = 5
+
+    def __init__(self, study, mesh: HexMesh, nu, fixed, modulus: float | None = None):
+        th = study.thermal
+        mat = study.material
+        self.mesh, self.nu, self.fixed = mesh, nu, fixed
+        self.t_ref = float(th.t_ref)
+        self.k = th.conductivity if th.conductivity is not None else _card(conductivity, mat, "conductivity")
+        self.curve = _card(lambda m: MODULUS_RETENTION[_material_key(m)], mat, "retention") if th.soften else None
+        a = th.expansion
+        self.alpha = (_card(expansion, mat, "expansion coefficient") if a is True else float(a)) if a else None
+        self.E0 = float(mat.E if modulus is None else modulus)
+        self.bc = study_thermal_bc(study, mesh)
+        self.cycle = th.cycle
+        if self.cycle is not None:
+            cp = th.specific_heat if th.specific_heat is not None else _card(specific_heat, mat, "specific heat")
+            self.rho_cp = mat.density * 1e-6 * cp          # J/(mm^3 K)
+        self.vth = None
+        self.th = None
+        self.te = None
+        self.cold = None
+        self.cycle_result = None
+        self.r = None
+        self.r_cold = None
+        # cells left out of the swing's stress p-norm: those by supports and
+        # loads, whose stress verification leaves out of the peak too (a
+        # bolted face restraining expansion is a singular corner)
+        self.near = None
+        self._calls = 0
+        # weight of the thermal-cycling swing in the optimizer's objective
+        # (relative to the hot objective at the first iteration)
+        self.swing_weight = float(th.cycle.fatigue_weight) if th.cycle is not None else 0.0
+        # or the swing as a constraint: the largest swing stress range over
+        # retention (MPa) allowed, from the fatigue strength at the cycle
+        # count over the safety factor. Fatigue SF S means damage
+        # n/N(sigma) <= S^-k, so sigma <= fatigue strength at n S^k
+        # cycles; durability reads the cycle stress as range / 0.7.
+        self.swing_limit = None
+        if th.cycle is not None and th.cycle.fatigue_sf is not None:
+            from .durability import durability_data, fatigue_strength
+
+            dur = getattr(study, "durability", None)
+            data = durability_data(mat, dur.overrides if dur is not None else None)
+            n_eq = float(th.cycle.cycles) * float(th.cycle.fatigue_sf) ** data.fatigue_slope
+            # / SWING_ALLOWANCE: verification reads the surface of the meshed
+            # part, about 1.2-1.3x what the cells' corners read on the grid
+            # (motor mount, first pass: 1.24 at 12k cells, 1.19-1.26 at 45k)
+            self.swing_limit = 0.7 * fatigue_strength(data, mat.strength, n_eq) / self.SWING_ALLOWANCE
+
+    @property
+    def expands(self):
+        return self.alpha is not None and self.alpha > 0
+
+    def temperature(self, rho=None, reuse=False):
+        """Solve at densities rho (default solid): per-element C, and sets
+        g, dg, eps. With a duty cycle: the cycle's hottest moment (and
+        self.cold, its coldest), held over REFRESH calls when `reuse`."""
+        rho = np.ones(self.mesh.n_elem) if rho is None else np.asarray(rho, float)
+        if self.th is None:
+            grid = ThermalGrid(self.mesh.pitch, self.mesh.origin, (0, 0, 0), self.mesh,
+                               np.zeros(self.mesh.n_elem, bool))
+            target = None if self.bc.power > 0 else np.ones(self.mesh.n_nodes, bool)
+            self.th = _Thermal(grid, self.bc, self.k, target)
+        if self.bc.fixed.all():
+            # every node held: nothing to solve, and nothing depends on rho
+            theta = self.bc.fixed_t - self.bc.ambient
+        else:
+            theta = self.th.solve(rho)
+        if self.cycle is not None:
+            self._calls += 1
+            if not (reuse and self.r is not None and (self._calls - 1) % self.REFRESH):
+                res = solve_cycle(self.mesh, self.k, self.bc, node_capacity(self.mesh, self.rho_cp, rho),
+                                  self.cycle, density=rho)
+                self.cycle_result, self.cold = res, res.cold
+                big = np.abs(theta) > 1e-9 * max(np.abs(theta).max(), 1e-300)
+                den = np.where(big, theta, 1.0)
+                self.r = np.where(big, np.clip((res.hot - self.bc.ambient) / den, 0, 1), 1.0)
+                self.r_cold = np.where(big, np.clip((res.cold - self.bc.ambient) / den, 0, 1), 1.0)
+            self.theta_s = theta
+            theta = self.r * theta
+        return self.use(theta + self.bc.ambient)
+
+    def use(self, t_node):
+        """Take a temperature field (C per node): sets te, g, dg, eps."""
+        self.t_node = np.asarray(t_node, float)
+        self.te = self.t_node[self.mesh.enode].mean(axis=1)
+        if self.curve is not None:
+            self.g, self.dg = retention(self.curve, self.te)
+        else:
+            self.g, self.dg = np.ones(self.mesh.n_elem), np.zeros(self.mesh.n_elem)
+        self.eps = self.alpha * (self.te - self.t_ref) if self.expands else np.zeros(self.mesh.n_elem)
+        return self.te
+
+    def load(self, p, scale=1.0):
+        """Expansion load at stiffness interpolation p per cell (no void
+        floor), times scale (the modulus: E0 in the optimizer's units)."""
+        from .fem import hex8_fth
+
+        if not self.expands:
+            return np.zeros(self.mesh.n_dof)
+        if self.vth is None:
+            self.vth = hex8_fth(self.nu) * self.mesh.pitch ** 2
+        w = scale * p * self.g * self.eps
+        f = np.bincount(self.mesh.edof.ravel(), weights=(w[:, None] * self.vth[None, :]).ravel(),
+                        minlength=self.mesh.n_dof)
+        f[self.fixed] = 0.0
+        return f
+
+    def sensitivities(self, fe, xe, rhs, us, fth, weights, gravity=None, state=None, layout=None,
+                      spreads=None, smooth=None):
+        """(objective, per-case objective, gradient w.r.t. xe, per-case worst
+        direction or None) of the weighted cases at the last temperature(xe),
+        in fe's units (forces in N, u scaled by E0). `rhs` (directions.expand,
+        with `layout` and `spreads`; one per case without them) already carry
+        fth and self-weight. Without expansion the objective is the
+        compliance; with it, twice the elastic strain energy:
+        J = u.(f - 2 fth) + E0^2 sum p g eps^2 cm V, adjoint
+        K lam = f - 2 fth. Self-weight (gravity, N/mm^3 linear in xe) adds
+        (lam + u) . df/dx.
+
+        A force of unknown direction (directions.py) keeps J quadratic in the
+        direction d: with the case's fixed part f0 (fth in it) and the
+        uncertain force b_j along each axis, J(d) = J0 + 2 g.d + d'Ad with
+        g_j = b_j.(u0 + lam0) / 2 and A_ij = b_i.u_j, since the basis loads
+        carry no expansion (their adjoints are their displacements). The
+        worst d is the same 3x3 problem as for compliance, and the gradient
+        is the soft maximum over directions that directions.collapse uses,
+        with lam = lam0 + U d beside u = u0 + U d."""
+        from .directions import SMOOTH, _cap_samples, worst_direction
+        from .fem import elastic_c
+        from .simp import ALIVE, E_MIN, PENALTY
+
+        mesh = self.mesh
+        state = state if state is not None else {}
+        smooth = SMOOTH if smooth is None else smooth
+        layout = layout if layout is not None else [(i,) for i in range(len(rhs))]
+        spreads = spreads or [None] * len(layout)
+        g, dg, eps = self.g, self.dg, self.eps
+        live = xe > ALIVE
+        pth = np.where(live, xe ** PENALTY * (1 - E_MIN), 0.0)
+        dp = np.where(live, PENALTY * xe ** (PENALTY - 1) * (1 - E_MIN), 0.0)
+        estiff = E_MIN + xe ** PENALTY * (1 - E_MIN)
+        dE = PENALTY * xe ** (PENALTY - 1) * (1 - E_MIN)
+        S = 0.0
+        if self.expands:
+            if self.vth is None:
+                self.load(pth)
+            # adjoints of the right-hand sides that carry the expansion: every
+            # plain case, and each spread case's fixed part
+            fixed_part = [idx[0] for idx in layout if idx[0] is not None]
+            sol = fe.resolve([rhs[i] - 2 * fth for i in fixed_part], state.get("lams"))
+            state["lams"] = sol
+            lams = list(us)
+            for i, lam in zip(fixed_part, sol):
+                lams[i] = lam
+            cm = float(np.array([1, 1, 1, 0, 0, 0]) @ elastic_c(1.0, self.nu)
+                       @ np.array([1, 1, 1, 0, 0, 0])) * mesh.pitch ** 3
+            self_e = self.E0 ** 2 * eps * eps * cm
+            S = float(np.sum(pth * g * self_e))
+        else:
+            lams = us
+        rmod = [r - 2 * fth if self.expands else r for r in rhs]
+        case_j, dirs, j = [], [], 0.0
+        m_e = np.zeros(mesh.n_elem)           # sum_c w_c lam_e^T K0 u_e
+        q_e = np.zeros(mesh.n_elem)           # sum_c w_c (lam_e - u_e) . vth
+        grav = np.zeros(mesh.n_elem)
+        for ci, idx in enumerate(layout):
+            if len(idx) == 1:
+                i = idx[0]
+                jc = float(us[i] @ rmod[i]) + S
+                pairs = [(1.0, lams[i], us[i])]
+                lam_m, u_m, d = lams[i], us[i], None
+            else:
+                i0, ib = idx[0], idx[1:]
+                ub = [us[i] for i in ib]
+                bb = [rhs[i] for i in ib]
+                a = np.array([[bb[i] @ ub[k] for k in range(3)] for i in range(3)])
+                a = 0.5 * (a + a.T)
+                if i0 is None:
+                    u0 = lam0 = np.zeros_like(ub[0])
+                    c00, gv = S, np.zeros(3)
+                else:
+                    u0, lam0 = us[i0], lams[i0]
+                    c00 = float(u0 @ rmod[i0]) + S
+                    gv = 0.5 * np.array([bk @ (u0 + lam0) for bk in bb])
+                sp = spreads[ci]
+                d, jc = worst_direction(c00, gv, a, sp.nominal, sp.cos_half)
+                cand = np.vstack([_cap_samples(sp), d[None]])
+                vals = c00 + 2.0 * cand @ gv + np.einsum("ij,jk,ik->i", cand, a, cand)
+                w = np.exp(smooth * (vals - jc) / max(abs(jc), 1e-300))
+                w /= w.sum()
+                dd = np.column_stack([np.ones(len(cand)), cand])
+                mu, q = np.linalg.eigh((dd * w[:, None]).T @ dd)
+                uu, ll = [u0] + ub, [lam0] + ub
+                pairs = [(float(m), sum(q[k, n] * ll[k] for k in range(4)), sum(q[k, n] * uu[k] for k in range(4)))
+                         for n, m in enumerate(mu) if m > 1e-9 * mu[-1]]
+                mean = dd.T @ w
+                lam_m = sum(mean[k] * ll[k] for k in range(4))
+                u_m = sum(mean[k] * uu[k] for k in range(4))
+            for m, lam, u in pairs:
+                if lam is u:
+                    m_e += weights[ci] * m * fe.strain_energy(u)
+                else:
+                    m_e += weights[ci] * m * 0.25 * (fe.strain_energy(lam + u) - fe.strain_energy(lam - u))
+            if self.expands:
+                q_e += weights[ci] * ((lam_m - u_m)[mesh.edof] @ self.vth)
+            if gravity is not None:
+                s = (lam_m + u_m).reshape(-1, 3)[mesh.enode].sum(axis=1)
+                grav += weights[ci] * (s @ gravity) * mesh.pitch ** 3 / 8.0
+            case_j.append(jc)
+            dirs.append(d)
+            j += weights[ci] * jc
+        sw = float(np.sum(weights[:len(layout)]))
+        dx = -dE * g * m_e + grav
+        # temperature derivatives per cell, split by path: through the
+        # retention g (the hot moment's temperature) and through the
+        # expansion strain (whose nodal temperature may be another field)
+        dte_g = -estiff * dg * m_e
+        dte_e = np.zeros(mesh.n_elem)
+        r_e = self.r
+        if self.expands:
+            dx += self.E0 * dp * g * eps * q_e + sw * dp * g * self_e
+            dte_g += self.E0 * pth * dg * eps * q_e + sw * self.E0 ** 2 * pth * cm * dg * eps * eps
+            dte_e += self.E0 * pth * g * self.alpha * q_e + sw * self.E0 ** 2 * pth * cm * 2 * g * eps * self.alpha
+        if self.swing_weight > 0 and self.expands and self.r is not None:
+            # Thermal cycling: the swing from the cold moment to the hot one
+            # as an expansion problem of its own, eps_s = alpha (T_hot -
+            # T_cold) at the hot moduli with no mechanical load, measured by
+            # a p-norm of its von Mises stress over strength retention (what
+            # the fatigue check reads, durability.py). Twice its strain energy
+            # was tried first and made parts worse: the energy of a thermal
+            # load falls as material near the heat goes, which concentrates
+            # the stress fatigue cares about (motor mount, 12k cells: fatigue
+            # SF 2.48 -> 1.29 at weight 0.1). Weighted so that at the first
+            # iteration it is swing_weight times the hot objective.
+            j_s, dx_s, dte_gs, dte_s = self._swing_pnorm(fe, xe, state, pth, dp, estiff, dE, g, dg)
+            if "swing_scale" not in state:
+                state["swing_scale"] = self.swing_weight * abs(j) / max(abs(j_s), 1e-300)
+            k_s = state["swing_scale"]
+            state["swing"] = j_s
+            j += k_s * j_s
+            dx += k_s * dx_s
+            dte_g += k_s * dte_gs
+            dte_s = k_s * dte_s
+        elif self.swing_limit is not None and self.expands and self.r is not None:
+            # Thermal cycling as a constraint (simp.optimize runs MMA): the
+            # swing's p-norm and its full gradient, temperature path
+            # included through an adjoint of its own, kept apart from the
+            # objective
+            j_s, dx_s, dte_gs, dte_s1 = self._swing_pnorm(fe, xe, state, pth, dp, estiff, dE, g, dg)
+            if not self.bc.fixed.all():
+                def nodes1(v):
+                    return np.bincount(mesh.enode.ravel(), weights=np.repeat(v / 8.0, 8), minlength=mesh.n_nodes)
+                rhs_s = nodes1(dte_gs) * self.r + nodes1(dte_s1) * (self.r - self.r_cold)
+                state["lam_swing"] = self.th.adjoint(rhs_s, state.get("lam_swing"))
+                dx_s = dx_s + self.th.gradient(xe, state["lam_swing"])
+            state["swing"] = j_s
+            state["swing_grad"] = dx_s
+            dte_s = None
+        else:
+            dte_s = None
+        # through temperature: a node holds 1/8 of each of its cells' T, and
+        # a duty cycle's hot moment is r * the steady rise (its cold one
+        # r_cold * it)
+        if (np.any(dte_g) or np.any(dte_e) or (dte_s is not None and np.any(dte_s))) and not self.bc.fixed.all():
+            def nodes(v):
+                return np.bincount(mesh.enode.ravel(), weights=np.repeat(v / 8.0, 8), minlength=mesh.n_nodes)
+            rhs_t = nodes(dte_g + dte_e)
+            if r_e is not None:
+                rhs_t = rhs_t * r_e
+            if dte_s is not None:
+                rhs_t = rhs_t + nodes(dte_s) * (self.r - self.r_cold)
+            self.th.lam = self.th.adjoint(rhs_t, self.th.lam)
+            dx = dx + self.th.gradient(xe, self.th.lam)
+        return j, case_j, dx, dirs
+
+    SWING_P = 8.0       # p of the swing's stress p-norm
+    SWING_ALLOWANCE = 1.25     # verified / optimizer swing peak, for the constraint's limit
+    SWING_POINTS = "corners"   # where the swing's stress is sampled: "corners" or "center"
+    SWING_Q = 0.5       # grey cells' stress relaxation, x^q (Bruggi's qp)
+
+    def _swing_pnorm(self, fe, xe, state, pth, dp, estiff, dE, g, dg):
+        """(P, dP/dx, dP/dT through g per cell, dP/deps_s-weighted per cell for
+        the swing's nodal temperature) of the p-norm of the thermal swing's
+        cell-centre von Mises stress over retention,
+        s_e = x^q C0 (B u_e - E0 eps_e m), K u = f_s (fe's units), with its
+        adjoint K mu = dP/du."""
+        from .directions import _VM
+        from .fem import elastic_c, hex8_b_center
+
+        mesh = self.mesh
+        p, q = self.SWING_P, self.SWING_Q
+        eps = self.alpha * ((self.r - self.r_cold) * self.theta_s)[mesh.enode].mean(axis=1)
+        w = pth * g * eps * self.E0
+        f = np.bincount(mesh.edof.ravel(), weights=(w[:, None] * self.vth[None, :]).ravel(), minlength=mesh.n_dof)
+        f[self.fixed] = 0.0
+        u = fe.resolve([f], state.get("u_swing"))[0]
+        state["u_swing"] = [u]
+        c0 = elastic_c(1.0, self.nu)
+        m = np.array([1.0, 1, 1, 0, 0, 0])
+        cm = c0 @ m
+        eta = np.maximum(xe, 1e-9) ** q
+        keep = (~self.near) if self.near is not None else np.ones(mesh.n_elem, bool)
+        # sample points: the cell centre, or its 8 corners (SWING_POINTS):
+        # a member's bending puts its peak at the surface, which the centre
+        # of a cell spanning it reads low
+        if self.SWING_POINTS == "corners":
+            # (hex8_b: with the incompatible-mode element part of the
+            # bending strain lives in its condensed bubbles, which the plain
+            # trilinear B misses at the corners)
+            from .fem import hex8_b
+            pts = [(a, b_, c) for a in (-1.0, 1.0) for b_ in (-1.0, 1.0) for c in (-1.0, 1.0)]
+            cbs = [c0 @ (hex8_b(*pt, self.nu) / mesh.pitch) for pt in pts]
+        else:
+            cbs = [c0 @ (hex8_b_center() / mesh.pitch)]
+        ue = u[mesh.edof]
+        sigs, vss, vms = [], [], []
+        for cb in cbs:
+            sig = ue @ cb.T - (self.E0 * eps)[:, None] * cm[None, :]
+            sk = eta[:, None] * sig * keep[:, None]
+            vs = sk @ _VM
+            sigs.append(sig)
+            vss.append(vs)
+            vms.append(np.sqrt(np.maximum(np.einsum("ij,ij->i", sk, vs), 1e-300)))
+        big = max(float(v.max()) for v in vms)
+        state["swing_max"] = big
+        sp = float(sum(np.sum((v / big) ** p) for v in vms))     # scaled against overflow
+        P = big * sp ** (1.0 / p)
+        gu = np.zeros(mesh.n_dof)
+        dxq = np.zeros(mesh.n_elem)
+        dsc = np.zeros(mesh.n_elem)
+        for cb, sig, vs, vm in zip(cbs, sigs, vss, vms):
+            dpv = sp ** (1.0 / p - 1.0) * (vm / big) ** (p - 1.0)   # dP/dvm
+            ds = (dpv / vm)[:, None] * vs                            # dP/ds
+            dsig = eta[:, None] * ds                                 # dP/dsig
+            gu += np.bincount(mesh.edof.ravel(), weights=(dsig @ cb).ravel(), minlength=mesh.n_dof)
+            dxq += np.einsum("ij,ij->i", ds, sig)
+            dsc += dsig @ cm
+        gu[self.fixed] = 0.0
+        mu = fe.resolve([gu], state.get("mu_swing"))[0]
+        state["mu_swing"] = [mu]
+        mk = 0.25 * (fe.strain_energy(mu + u) - fe.strain_energy(mu - u))     # mu_e^T K0 u_e
+        mv = mu[mesh.edof] @ self.vth                                          # mu_e . vth
+        # P(x, u(x)): explicit + mu^T (df/dx - dK/dx u)
+        dx = q * np.maximum(xe, 1e-9) ** (q - 1) * dxq \
+            + self.E0 * dp * g * eps * mv - dE * g * mk
+        # through the swing strain: explicit, and mu . df/deps
+        de = -self.E0 * dsc + self.E0 * pth * g * mv
+        # through the hot moment's retention: K and f_s both carry g
+        dgv = dg * (self.E0 * pth * eps * mv - estiff * mk)
+        return P, dx, dgv, de * self.alpha
+
+
+def _card(get, material, what):
+    try:
+        return get(material)
+    except (KeyError, ValueError):
+        raise ValueError(f"thermal: no {what} for {getattr(material, 'name', material)!r}; give it in the "
+                         "thermal block (conductivity, expansion) or set soften false") from None
+
+
+def study_heat(study, mesh: HexMesh, nu, fixed, modulus: float | None = None, near=None):
+    """StudyHeat for a study with a thermal block, else None. `near`: cells
+    by supports and loads, left out of the swing's stress (StudyHeat.near)."""
+    if getattr(study, "thermal", None) is None:
+        return None
+    heat = StudyHeat(study, mesh, nu, fixed, modulus)
+    if near is not None:
+        heat.near = np.asarray(near, bool)
+    return heat