loadpath 0.1.1__py3-none-any.whl

loadpath/benchmarks/problems.py

@@ -0,0 +1,140 @@
+"""
+The benchmark problems: the textbook topology-optimization cases, each
+defined once on a unit voxel grid so the same boundary conditions drive the
+published reference code (top88, top3d, run in Octave), loadpath, and the
+evaluator that scores every design.
+
+Grid convention is loadpath's: cell (i, j, k) along x, y, z with z up, unit
+cells, unit Young's modulus, nu = 0.3. A plane (2D) problem has one cell in y
+and is solved in plane stress by the reference and the evaluator; loadpath
+optimizes it as a one-cell slab extruded along y.
+
+Boundary conditions are node sets in grid coordinates:
+    fixed: [(nodes (N, 3) int, "xz")]          components held at zero
+    loads: [(nodes (N, 3) int, "z", value)]    force per node
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import numpy as np
+
+__all__ = ["Problem", "PROBLEMS", "get"]
+
+
+def _nodes(i, j, k):
+    """Every node (i, j, k) of the given index ranges (ints or iterables)."""
+    ii, jj, kk = np.meshgrid(np.atleast_1d(i), np.atleast_1d(j), np.atleast_1d(k), indexing="ij")
+    return np.stack([ii.ravel(), jj.ravel(), kk.ravel()], axis=1).astype(np.int64)
+
+
+@dataclass
+class Problem:
+    name: str
+    title: str
+    source: str
+    dims: tuple                 # cells (nx, ny, nz)
+    volfrac: float              # of the whole box, as top88/top3d count it
+    rmin: float                 # filter radius, cells
+    fixed: list
+    loads: list
+    references: list            # reference solver ids (reference.SOLVERS)
+    plane: bool = False
+    void: np.ndarray | None = None    # bool (nx, ny, nz): passive void cells
+    # The reference model is the half of a symmetric part cut at x = 0 (the
+    # half MBB beam). loadpath models the whole part with mirror symmetry, as
+    # a study would; `full` is that problem and the delivered design's
+    # x >= nx half is the one scored.
+    full: "Problem | None" = None
+    symmetry: list = field(default_factory=list)
+    # Also score peak von Mises and run loadpath's stress-constrained
+    # minimum-mass formulation against the reference's peak.
+    stress: bool = False
+    notes: str = ""
+
+    @property
+    def active(self) -> np.ndarray:
+        a = np.ones(self.dims, bool)
+        if self.void is not None:
+            a &= ~self.void
+        return a
+
+    @property
+    def active_volfrac(self) -> float:
+        """The same amount of material as a share of the cells that exist."""
+        return self.volfrac * float(np.prod(self.dims)) / float(self.active.sum())
+
+
+def mbb_2d(nx=150, nz=50, volfrac=0.5, rmin=2.0):
+    """Half MBB beam exactly as top88 ships it: symmetry line on the left,
+    roller at the bottom right, unit load down at the top left."""
+    half = Problem(
+        name="mbb-2d", title=f"MBB beam, 2D half model ({nx}x{nz})",
+        source="Andreassen et al. 2011, 'Efficient topology optimization in MATLAB using 88 lines of code' "
+               "(top88.m, default load case)",
+        dims=(nx, 1, nz), volfrac=volfrac, rmin=rmin, plane=True,
+        fixed=[(_nodes(0, 0, range(nz + 1)), "x"), (_nodes(nx, 0, 0), "z")],
+        loads=[(_nodes(0, 0, nz), "z", -1.0)],
+        references=["top88-ft1", "top88-ft2"])
+    # whole beam: x in [0, 2nx], the half above sits at x >= nx
+    half.full = Problem(
+        name="mbb-2d-full", title="MBB beam, whole", source=half.source,
+        dims=(2 * nx, 1, nz), volfrac=volfrac, rmin=rmin, plane=True,
+        fixed=[(_nodes(0, 0, 0), "xz"), (_nodes(2 * nx, 0, 0), "z")],
+        loads=[(_nodes(nx, 0, nz), "z", -2.0)],
+        references=[], symmetry=["x"])
+    return half
+
+
+def lbracket_2d(n=100, cut=0.6, volfrac_active=0.4, rmin=2.0):
+    """L-bracket: the 2D stress benchmark (Le et al. 2010 and most stress
+    papers since). Clamped along the top edge, loaded down on the top of the
+    free arm's tip, the re-entrant corner is where compliance designs
+    concentrate stress."""
+    c = int(round(n * (1 - cut)))                 # arm width, cells
+    void = np.zeros((n, 1, n), bool)
+    void[c:, :, c:] = True
+    tip = 6
+    active = n * n - (n - c) ** 2
+    return Problem(
+        name="lbracket-2d", title=f"L-bracket, 2D ({n}x{n}, {n - c}x{n - c} cut out)",
+        source="Le, Norato, Bruns, Ha & Tortorelli 2010, 'Stress-based topology optimization for continua' "
+               "(geometry); reference design from top88.m with passive voids (Andreassen et al. 2011, sec. 5.2)",
+        dims=(n, 1, n), volfrac=volfrac_active * active / (n * n), rmin=rmin, plane=True, void=void,
+        fixed=[(_nodes(range(c + 1), 0, n), "xz")],
+        loads=[(_nodes(n, 0, range(c - tip + 1, c + 1)), "z", -1.0 / tip)],
+        references=["top88-ft2"], stress=True)
+
+
+def cantilever_3d(nx=60, ny=4, nz=20, volfrac=0.3, rmin=1.5):
+    """top3d's default problem: clamped at x = 0, a unit load per node down
+    along the bottom edge of the free end."""
+    return Problem(
+        name="cantilever-3d", title=f"Cantilever beam, 3D ({nx}x{nz}x{ny})",
+        source="Liu & Tovar 2014, 'An efficient 3D topology optimization code written in Matlab' "
+               "(top3d.m, default load case, top3d(60,20,4,0.3,3,1.5))",
+        dims=(nx, ny, nz), volfrac=volfrac, rmin=rmin,
+        fixed=[(_nodes(0, range(ny + 1), range(nz + 1)), "xyz")],
+        loads=[(_nodes(nx, range(ny + 1), 0), "z", -1.0)],
+        references=["top3d"])
+
+
+def bridge_3d(nx=48, ny=12, nz=16, volfrac=0.15, rmin=1.5):
+    """A deck bridge: pinned along the bottom edges at both ends, a uniform
+    load over the whole top face."""
+    top = _nodes(range(nx + 1), range(ny + 1), nz)
+    return Problem(
+        name="bridge-3d", title=f"Bridge, 3D ({nx}x{ny}x{nz}, deck load)",
+        source="Classic 3D bridge benchmark (e.g. Aage et al. 2017 giga-voxel bridge, coarse); "
+               "reference design from top3d.m with these supports and loads",
+        dims=(nx, ny, nz), volfrac=volfrac, rmin=rmin,
+        fixed=[(_nodes([0, nx], range(ny + 1), 0), "xyz")],
+        loads=[(top, "z", -100.0 / len(top))],
+        references=["top3d"], symmetry=["x", "y"])
+
+
+PROBLEMS = {p.name: p for p in (mbb_2d(), lbracket_2d(), cantilever_3d(), bridge_3d())}
+
+
+def get(name: str) -> Problem:
+    return PROBLEMS[name]

loadpath/benchmarks/reference.py

@@ -0,0 +1,138 @@
+"""
+The reference optimizers: line-for-line NumPy ports of the published
+educational codes, run on each benchmark's own supports and loads.
+
+- top88: Andreassen, Clausen, Schevenels, Lazarov & Sigmund 2011, "Efficient
+  topology optimization in MATLAB using 88 lines of code". 2D, SIMP p = 3,
+  Emin = 1e-9, OC with move 0.2, sensitivity filter (ft=1) or density filter
+  (ft=2), stops when no density moves more than 0.01. Passive void cells as in
+  the paper's section 5.2.
+- top3d: Liu & Tovar 2014, "An efficient 3D topology optimization code
+  written in Matlab". The same scheme in 3D with the density filter and at
+  most 200 iterations.
+
+What is ported: the filter (truncated cone, normalized by its row sums),
+the sensitivities, the OC bisection (l2 = 1e9, tolerance 1e-3 relative), the
+volume measured on physical densities and the stopping rule. The finite
+elements are the evaluator's, which are the same elements (top88's 4-node
+plane-stress square, top3d's 8-node brick).
+
+The designs are stored under reference/ as grids in loadpath's layout, so the
+suite only re-runs a reference when asked to.
+"""
+from __future__ import annotations
+
+import os
+import time
+
+import numpy as np
+import scipy.sparse as sp
+
+from .evaluate import E_VOID, Evaluator
+from .problems import Problem
+
+__all__ = ["SOLVERS", "run_reference", "load_reference", "reference_path"]
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SOLVERS = {
+    "top88-ft1": "top88, sensitivity filter (Andreassen et al. 2011)",
+    "top88-ft2": "top88, density filter (Andreassen et al. 2011)",
+    "top3d": "top3d, density filter (Liu & Tovar 2014)",
+}
+# top88 itself has no iteration cap; this one only keeps a chattering run
+# bounded. top3d ships with 200.
+TOP88_MAXIT = 1000
+TOP3D_MAXIT = 200
+
+
+def _filter(ev: Evaluator, rmin: float):
+    """top88's H and Hs: weights rmin - distance to every cell within
+    ceil(rmin) - 1 cells per axis, normalized by the row sum."""
+    ijk = np.stack(ev.cell, axis=1)
+    dims = np.asarray(ev.p.dims)
+    lut = np.full(ev.p.dims, -1, np.int64)
+    lut[tuple(ijk.T)] = np.arange(len(ijk))
+    reach = int(np.ceil(rmin)) - 1
+    span = [range(-reach, reach + 1) if d > 1 else range(1) for d in dims]
+    rows, cols, vals = [], [], []
+    for dx in span[0]:
+        for dy in span[1]:
+            for dz in span[2]:
+                w = rmin - np.sqrt(dx * dx + dy * dy + dz * dz)
+                if w <= 0:
+                    continue
+                nb = ijk + (dx, dy, dz)
+                ok = np.all((nb >= 0) & (nb < dims), axis=1)
+                rows.append(np.flatnonzero(ok))
+                cols.append(lut[tuple(nb[ok].T)])
+                vals.append(np.full(int(ok.sum()), w))
+    n = len(ijk)
+    h = sp.csr_matrix((np.concatenate(vals), (np.concatenate(rows), np.concatenate(cols))), shape=(n, n))
+    return h, np.asarray(h.sum(axis=1)).ravel()
+
+
+def optimize_reference(p: Problem, solver: str, on_iter=None) -> dict:
+    ev = Evaluator(p)
+    ft = 1 if solver == "top88-ft1" else 2
+    maxit = TOP3D_MAXIT if solver == "top3d" else TOP88_MAXIT
+    penal, move = 3.0, 0.2
+    h, hs = _filter(ev, p.rmin)
+    passive = ~ev.active
+    n = len(hs)
+    x = np.full(n, p.volfrac)
+    x[passive] = 0.0
+    xphys = x.copy()
+    t0 = time.time()
+    change, loop, c = 1.0, 0, 0.0
+    while change > 0.01 and loop < maxit:
+        loop += 1
+        u = ev.solve(E_VOID + xphys ** penal * (1 - E_VOID))
+        ue = u[ev.edof]
+        ce = np.einsum("ij,jk,ik->i", ue, ev.ke, ue)
+        c = float(np.sum((E_VOID + xphys ** penal * (1 - E_VOID)) * ce))
+        dc = -penal * (1 - E_VOID) * xphys ** (penal - 1) * ce
+        dv = np.ones(n)
+        if ft == 1:
+            dc = (h @ (x * dc)) / hs / np.maximum(1e-3, x)
+        else:
+            dc = h @ (dc / hs)
+            dv = h @ (dv / hs)
+        l1, l2 = 0.0, 1e9
+        while (l2 - l1) / (l1 + l2) > 1e-3:
+            lmid = 0.5 * (l2 + l1)
+            xnew = np.maximum(0, np.maximum(x - move, np.minimum(1, np.minimum(x + move, x * np.sqrt(-dc / dv / lmid)))))
+            xnew[passive] = 0.0
+            xphys = xnew if ft == 1 else (h @ xnew) / hs
+            xphys = np.where(passive, 0.0, xphys)
+            if xphys.sum() > p.volfrac * n:
+                l1 = lmid
+            else:
+                l2 = lmid
+        change = float(np.abs(xnew - x).max())
+        x = xnew
+        if on_iter is not None:
+            on_iter(loop, c, change)
+    grid = np.zeros(p.dims)
+    grid[ev.cell] = xphys
+    return dict(x=grid, iterations=loop, compliance_reported=c, seconds=time.time() - t0, solver=solver)
+
+
+def reference_path(p: Problem, solver: str) -> str:
+    return os.path.join(HERE, "reference", f"{p.name}.{solver}.npz")
+
+
+def run_reference(p: Problem, solver: str, on_iter=None) -> dict:
+    rec = optimize_reference(p, solver, on_iter)
+    os.makedirs(os.path.dirname(reference_path(p, solver)), exist_ok=True)
+    np.savez_compressed(reference_path(p, solver), x=rec["x"].astype(np.float32), iterations=rec["iterations"],
+                        compliance_reported=rec["compliance_reported"], seconds=rec["seconds"])
+    return rec
+
+
+def load_reference(p: Problem, solver: str) -> dict | None:
+    path = reference_path(p, solver)
+    if not os.path.exists(path):
+        return None
+    z = np.load(path)
+    return dict(x=z["x"].astype(float), iterations=int(z["iterations"]),
+                compliance_reported=float(z["compliance_reported"]), seconds=float(z["seconds"]), solver=solver)

loadpath/benchmarks/run.py

@@ -0,0 +1,301 @@
+"""
+Benchmark suite: loadpath against the published topology-optimization codes
+on the textbook problems (problems.py), scored by one evaluator
+(evaluate.py). Separate from the GRIP evals: those ask "is this part good
+enough to print", this asks "how close to the optimum does the optimizer get".
+
+For each problem:
+- the reference designs (top88 / top3d ports, reference.py), stored, rerun
+  with --refresh;
+- loadpath's optimizer as a study would run it (robust erosion, Heaviside
+  projection, the padded filter for 3D, pruning, pinned load cells), and
+  "plain" with erosion, padding and pruning off: the same formulation as the
+  references, which separates what the solver does from what loadpath's
+  printability choices cost;
+- stress problems also run loadpath's minimum-mass stress-constrained
+  formulation (constrained.py) with the reference design's peak as the limit.
+
+Scores (evaluate.py): compliance as delivered (penalized, p = 3) and
+black-and-white at the target volume; the headline is the lower of the two
+(lower is stiffer). loadpath's volume fraction is lowered by its pinned load
+and support cells so every design uses the same total material. Stress
+problems add the peak von Mises of the black-and-white design. The ratio
+column is each design over the best reference.
+
+Run:  python -m loadpath.benchmarks.run [problem ...] --out bench-out/
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import time
+
+import numpy as np
+
+from ..constrained import Limits, optimize_constrained
+from ..domain import build_domain
+from ..simp import SimpOptions, optimize
+from ..spec import study_from_dict
+from .evaluate import Evaluator, binarize
+from .problems import PROBLEMS, Problem
+from .reference import SOLVERS, load_reference, run_reference
+
+NU = 0.3
+VARIANTS = {
+    "loadpath": {},
+    "loadpath-plain": {"erode": 0.0, "prune": False, "pad_filter": False},
+}
+
+
+def _box(nodes, plane):
+    lo = nodes.min(axis=0) - 0.25
+    hi = nodes.max(axis=0) + 0.25
+    if plane:
+        lo[1], hi[1] = -0.25, 1.25
+    return {"type": "box", "min": lo.tolist(), "max": hi.tolist()}
+
+
+def _slab(nodes, plane):
+    """A plane problem's node set on both faces of the one-cell slab."""
+    if not plane:
+        return nodes
+    other = nodes.copy()
+    other[:, 1] = 1
+    return np.concatenate([nodes, other])
+
+
+def domain_for(p: Problem):
+    """loadpath's Domain for a benchmark, built the way a study builds it (so
+    load and support cells are pinned and symmetry is mirrored as in real
+    use), with the supports and loads then set exactly to the problem's."""
+    nx, ny, nz = p.dims
+    d = {
+        "designSpace": [{"type": "box", "min": [0, 0, 0], "max": [nx, ny, nz]}],
+        "supports": [{"shape": _box(n, p.plane), "fix": "".join(sorted(c))} for n, c in p.fixed],
+        "loadCases": [{"name": "load", "loads": [
+            {"shape": _box(n, p.plane), "force": [v * len(n) if a == c else 0.0 for a in "xyz"]}
+            for n, c, v in p.loads]}],
+        "material": {"name": "unit", "E": 1.0, "nu": NU, "strength": 1.0, "density": 1.0},
+        "goal": {"volumeFraction": p.active_volfrac},
+        "resolution": {"pitch": 1.0},
+    }
+    if p.symmetry:
+        d["symmetry"] = list(p.symmetry)
+    if p.plane:
+        d["extrusion"] = "y"
+    if p.void is not None:
+        # the cut-out as keep-out boxes, one per void column run
+        ii, _, kk = np.nonzero(p.void)
+        d["keepOut"] = [{"id": "cut", "shape": {"type": "box", "min": [float(ii.min()), -1, float(kk.min())],
+                                                  "max": [float(ii.max() + 1) + 1, ny + 1, float(kk.max() + 1) + 1]},
+                         "bore": False}]
+    study = study_from_dict(d)
+    dom = build_domain(study, pitch=1.0)
+    if tuple(dom.dims) != tuple(p.dims) or np.abs(dom.origin).max() > 1e-9:
+        raise RuntimeError(f"{p.name}: loadpath grid {dom.dims} at {dom.origin} does not match {p.dims}")
+    mesh = dom.mesh
+    fixed = np.zeros(mesh.n_dof, bool)
+    f = np.zeros(mesh.n_dof)
+    for nodes, comps in p.fixed:
+        ids = mesh.node_id(_slab(nodes, p.plane))
+        for c in comps:
+            fixed[3 * ids + "xyz".index(c)] = True
+    for nodes, c, v in p.loads:
+        all_n = _slab(nodes, p.plane)
+        share = v * len(nodes) / len(all_n)
+        np.add.at(f, 3 * mesh.node_id(all_n) + "xyz".index(c), share)
+    if p.plane:
+        # the slab is half of a plate symmetric about y = 0: holds y there
+        fixed[3 * np.flatnonzero(mesh.node_ijk[:, 1] == 0) + 1] = True
+    dom.fixed, dom.loads, dom.springs = fixed, [f], None
+    return dom, study
+
+
+def _grid(dom, values):
+    g = np.zeros(dom.dims)
+    g[tuple(dom.mesh.elem_ijk.T)] = values
+    return g
+
+
+def _scored_grid(p: Problem, g):
+    """The part of a loadpath design the problem scores (the half of a
+    mirrored whole)."""
+    if p.full is not None:
+        return g[p.dims[0]:]
+    return g
+
+
+def design_volfrac(q: Problem, dom) -> float:
+    """loadpath's volume fraction counts design cells only; pinned (load,
+    support) cells come on top. This is the fraction of the rest that gives
+    the same total material as the references."""
+    n, pres = dom.mesh.n_elem, int(dom.preserve.sum())
+    return max(0.01, (q.active_volfrac * n - pres) / (n - pres))
+
+
+def run_loadpath(p: Problem, variant: str, log=print):
+    q = p.full or p
+    dom, study = domain_for(q)
+    opts = SimpOptions(volume_fraction=design_volfrac(q, dom), filter_radius=q.rmin,
+                       extrusion=1 if q.plane else None, **VARIANTS[variant])
+    t0 = time.time()
+    res = optimize(dom, NU, opts)
+    log(f"  {variant}: {res.iterations} iterations, {time.time() - t0:.0f}s, c {res.compliance:.4g}")
+    return dict(x=_scored_grid(p, _grid(dom, res.xphys)), iterations=res.iterations, seconds=time.time() - t0,
+                compliance_reported=res.compliance)
+
+
+def run_constrained(p: Problem, limit: float, log=print):
+    q = p.full or p
+    dom, _ = domain_for(q)
+    # Started from (nearly) solid, a feasible design, as Le et al. 2010 do.
+    # Since the fixes in constrained.py (q = 1, a guarded MMA step, the
+    # blueprint delivered) it also converges from the reference's volume.
+    opts = SimpOptions(volume_fraction=0.95, filter_radius=q.rmin,
+                       extrusion=1 if q.plane else None, max_iterations=200)
+    t0 = time.time()
+    res = optimize_constrained(dom, NU, opts, Limits(stress=limit, deflection=None, modulus=1.0))
+    log(f"  stress-constrained: {res.iterations} iterations, {time.time() - t0:.0f}s, vol {res.volume_fraction:.3f}")
+    return dict(x=_scored_grid(p, _grid(dom, res.xphys)), iterations=res.iterations, seconds=time.time() - t0,
+                compliance_reported=res.compliance)
+
+
+def bench_problem(p: Problem, refresh=False, log=print) -> dict:
+    ev = Evaluator(p)
+    target = p.active_volfrac
+    designs, rows = {}, []
+    for solver in p.references:
+        rec = None if refresh else load_reference(p, solver)
+        if rec is None:
+            log(f"  running {solver} ...")
+            rec = run_reference(p, solver)
+        designs[solver] = rec
+    for v in VARIANTS:
+        designs[v] = run_loadpath(p, v, log)
+    for name, rec in designs.items():
+        s = ev.score(rec["x"], target)
+        s.update(design=name, iterations=rec["iterations"], seconds=round(rec["seconds"], 1),
+                 compliance_reported=rec["compliance_reported"])
+        rows.append(s)
+    refs = [r for r in rows if r["design"] in p.references]
+    best = min(refs, key=lambda r: r["compliance"])
+    for r in rows:
+        r["ratio"] = r["compliance"] / best["compliance"]
+    out = {"problem": p.name, "title": p.title, "source": p.source, "dims": list(p.dims),
+           "volfrac": target, "rmin": p.rmin, "rows": rows, "best_reference": best["design"]}
+    if p.stress:
+        limit = best["peak_von_mises"]
+        try:
+            rec = run_constrained(p, limit, log)
+        except Exception as exc:  # noqa: BLE001 - a failing formulation is a result
+            log(f"  stress-constrained failed: {type(exc).__name__}: {exc}")
+            out["stress"] = {"limit": limit, "reference_volume": target, "error": f"{type(exc).__name__}: {exc}"}
+            out["_designs"] = designs
+            return out
+        designs["loadpath-stress"] = rec
+        x = ev.cells(rec["x"])
+        vol = float(x[ev.active].mean())
+        b = np.zeros(p.dims)
+        b[ev.cell] = binarize(x, ev.active, vol)
+        vm = ev.von_mises(b)
+        vm[ev.load_cells()] = 0.0
+        out["stress"] = {"limit": limit, "reference_volume": target, "volume": vol,
+                         "peak_von_mises": float(vm.max()), "compliance": ev.compliance(b),
+                         "iterations": rec["iterations"], "seconds": round(rec["seconds"], 1)}
+    out["_designs"] = designs
+    return out
+
+
+def _render(res: dict, path: str):
+    import matplotlib
+    matplotlib.use("Agg")
+    import matplotlib.pyplot as plt
+
+    designs = res["_designs"]
+    names = list(designs)
+    plane = res["dims"][1] == 1
+    fig = plt.figure(figsize=(3.6 * len(names), 2.6 if plane else 3.2))
+    for k, name in enumerate(names):
+        g = designs[name]["x"]
+        row = next((r for r in res["rows"] if r["design"] == name), None)
+        label = name if row is None else f"{name}\nc = {row['compliance']:.4g}"
+        if name == "loadpath-stress":
+            label = f"{name}\nvol {res['stress']['volume']:.3f}, peak {res['stress']['peak_von_mises']:.3g}"
+        if plane:
+            ax = fig.add_subplot(1, len(names), k + 1)
+            ax.imshow(1 - g[:, 0, :].T, cmap="gray", origin="lower", vmin=0, vmax=1, interpolation="nearest")
+            ax.set_axis_off()
+        else:
+            from scipy import ndimage
+            from skimage.measure import marching_cubes
+            ax = fig.add_subplot(1, len(names), k + 1, projection="3d")
+            # light smoothing so the voxel steps do not read as the design
+            pad = ndimage.gaussian_filter(np.pad(g, 1), 0.6)
+            v, f, _, _ = marching_cubes(pad, 0.5)
+            ax.plot_trisurf(v[:, 0], v[:, 1], f, v[:, 2], color="#c9c4bc", edgecolor="none", shade=True)
+            ax.set_box_aspect(np.array(g.shape) + 2)
+            ax.view_init(24, -58)
+            ax.set_axis_off()
+        ax.set_title(label, fontsize=9)
+    fig.tight_layout()
+    fig.savefig(path, dpi=110)
+    plt.close(fig)
+
+
+def markdown(results: list) -> str:
+    lines = ["| problem | design | compliance | vs best reference | as delivered (p=3) | black/white at target "
+             "volume | volume | greyness | iterations | seconds |",
+             "|---|---|---|---|---|---|---|---|---|---|"]
+    for res in results:
+        for r in res["rows"]:
+            lines.append(f"| {res['problem']} | {r['design']} | {r['compliance']:.4g} | {r['ratio']:.3f} | "
+                         f"{r['compliance_grey']:.4g} | {r['compliance_matched']:.4g} | "
+                         f"{r['volume']:.3f} | {r['greyness']:.3f} | {r['iterations']} | {r['seconds']:.0f} |")
+    stress = [r for r in results if "stress" in r]
+    if stress:
+        lines += ["", "| problem | reference peak von Mises (limit) | reference volume | "
+                      "loadpath stress-constrained volume | its peak von Mises |", "|---|---|---|---|---|"]
+        for res in stress:
+            s = res["stress"]
+            if "error" in s:
+                lines.append(f"| {res['problem']} | {s['limit']:.4g} | {s['reference_volume']:.3f} | "
+                             f"failed: {s['error']} | |")
+                continue
+            lines.append(f"| {res['problem']} | {s['limit']:.4g} | {s['reference_volume']:.3f} | {s['volume']:.3f} | "
+                         f"{s['peak_von_mises']:.4g} |")
+    return "\n".join(lines) + "\n"
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0])
+    ap.add_argument("problems", nargs="*", help=f"subset of {sorted(PROBLEMS)}")
+    ap.add_argument("--out", default="bench-out")
+    ap.add_argument("--refresh", action="store_true", help="rerun the reference codes")
+    ap.add_argument("--no-render", action="store_true")
+    a = ap.parse_args(argv)
+    names = a.problems or list(PROBLEMS)
+    os.makedirs(a.out, exist_ok=True)
+    results = []
+    for name in names:
+        p = PROBLEMS[name]
+        print(f"{name}: {p.title}", flush=True)
+        res = bench_problem(p, refresh=a.refresh, log=lambda s: print(s, flush=True))
+        np.savez_compressed(os.path.join(a.out, f"{name}.designs.npz"),
+                            **{k: v["x"].astype(np.float32) for k, v in res["_designs"].items()})
+        if not a.no_render:
+            _render(res, os.path.join(a.out, f"{name}.png"))
+        results.append(res)
+    clean = [{k: v for k, v in r.items() if not k.startswith("_")} for r in results]
+    with open(os.path.join(a.out, "benchmarks.json"), "w") as fh:
+        json.dump(clean, fh, indent=1)
+    md = markdown(clean)
+    with open(os.path.join(a.out, "benchmarks.md"), "w") as fh:
+        fh.write(md)
+    print(md)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())