cuwave 0.1.0__py3-none-any.whl

cuwave/elastic.py

@@ -0,0 +1,342 @@
+"""Isotropic elasticity on a staggered grid, a sibling of `PressureWave` on the same march.
+
+Component `c` lives half a node up its own axis, so every strain lands on a natural
+point: the normal strains on the nodes, the shear `(k, l)` half a node up both of its
+axes. Each is a pure per-axis staggered difference, which is what carries the cross
+terms a per-axis flux cannot and keeps the cost linear in the stencil radius, where the
+cell gather of `AnisotropicElasticWave` pays `(2r)**(2 ndim)`. The operator is
+`-B^T C B` with the material sampled on the stress points, so it stays the exact
+transpose at every order.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+import cupy as cp
+import cupy.typing as cpt
+import numpy as np
+import numpy.typing as npt
+
+from .boundary import Clamped, Traction, face_mask, faces_with
+from .wave import (
+    PAIRS,
+    Simulation,
+    apply_cell_weights,
+    axis_geometry,
+    component_weights,
+    grid_block,
+    pair_average,
+    pair_average_adjoint,
+    pair_weights,
+    point_average,
+    point_average_adjoint,
+)
+
+KERNEL_PATH = Path(__file__).parent / "kernels" / "elastic.cu"
+SENSITIVITY_PATH = Path(__file__).parent / "kernels" / "elastic_sensitivity.cu"
+
+
+# -------------------------------------- helpers --------------------------------------
+def voigt(ndim: int, lame: float, shear: float, plane: str = "strain") -> npt.NDArray:
+    """Isotropic Voigt stiffness matrix, `plane` selecting strain or stress in 2D."""
+    if ndim == 1:
+        return np.array([[lame + 2.0 * shear]])
+    if ndim == 2:
+        lam = lame if plane == "strain" else 2.0 * lame * shear / (lame + 2.0 * shear)
+        return np.array(
+            [
+                [lam + 2.0 * shear, lam, 0.0],
+                [lam, lam + 2.0 * shear, 0.0],
+                [0.0, 0.0, shear],
+            ]
+        )
+    C = np.full((6, 6), 0.0)
+    C[:3, :3] = lame
+    for i in range(3):
+        C[i, i] = lame + 2.0 * shear
+        C[3 + i, 3 + i] = shear
+    return C
+
+
+# ------------------------------- discretization setup --------------------------------
+@dataclass
+class ElasticWave(Simulation):
+    """Staggered isotropic elasticity, parametrized by a density-scaling indicator gamma.
+
+    Both wave speeds are held fixed and gamma scales the density, so
+    `C = gamma * rho0 * C` scales inertia and stiffness alike and the stable timestep
+    does not move with the design. This is the parametrization ultrasonic full waveform
+    inversion reaches for, since a void is a density contrast at unchanged speeds.
+    """
+
+    density: float = None  # background density rho0
+    wavespeed_p: float = None  # pressure wave speed
+    wavespeed_s: float = None  # shear wave speed
+    plane: str = "strain"  # "strain" or "stress", 2D only
+
+    kernel_path = KERNEL_PATH
+    sensitivity_path = SENSITIVITY_PATH
+    default_boundary = Traction
+    gradient_names = ("mass", "stiff")
+
+    @property
+    def ncomp(self) -> int:
+        """One displacement component per axis."""
+        return self.ndim
+
+    @property
+    def component_offsets(self) -> npt.NDArray[np.float64]:
+        """Component `c` sits half a node up axis `c`: the staggering itself."""
+        return 0.5 * np.eye(self.ndim)
+
+    @property
+    def nvoigt(self) -> int:
+        """Stress components: `ndim` normal ones plus one per axis pair."""
+        return len(PAIRS[self.ndim])
+
+    @property
+    def npairs(self) -> int:
+        """Shear components, one per axis pair."""
+        return self.nvoigt - self.ndim
+
+    def __post_init__(self) -> None:
+        """Validate the material, the 2D plane assumption and the faces, then derive the grid."""
+        super().__post_init__()
+        if None in (self.density, self.wavespeed_p, self.wavespeed_s):
+            raise ValueError("ElasticWave requires density, wavespeed_p, wavespeed_s")
+        if self.plane not in ("strain", "stress"):
+            raise ValueError(f"plane must be strain or stress: {self.plane}")
+        if self.ndim == 3 and self.plane != "strain":
+            raise ValueError("plane stress is a 2D reduction, not a 3D one")
+        if self.wavespeed_s >= self.wavespeed_p:
+            raise ValueError(
+                f"wavespeed_s must be below wavespeed_p: "
+                f"{self.wavespeed_s} >= {self.wavespeed_p}"
+            )
+        for pair in self.boundary:
+            for condition in pair:
+                if condition not in (Traction, Clamped):
+                    raise ValueError(f"elastic faces are Traction or Clamped: {pair}")
+
+    @property
+    def radius(self) -> int:
+        """Half the stencil width, so `space_order` is twice it."""
+        return self.space_order // 2
+
+    @property
+    def reach(self) -> int:
+        """The strain reach compounds with the divergence one: `2 radius - 1` nodes."""
+        return 2 * self.radius - 1
+
+    @property
+    def lame(self) -> float:
+        """First Lame parameter `rho0 * (c_p**2 - 2 c_s**2)`, reduced under plane stress."""
+        lam = self.density * (self.wavespeed_p**2 - 2.0 * self.wavespeed_s**2)
+        if self.plane == "stress":
+            return 2.0 * lam * self.shear / (lam + 2.0 * self.shear)
+        return lam
+
+    @property
+    def shear(self) -> float:
+        """Second Lame parameter `rho0 * c_s**2`."""
+        return self.density * self.wavespeed_s**2
+
+    def inverse_inertia(self, indicator: cpt.NDArray) -> cpt.NDArray:
+        """Nodal `1 / (gamma rho0 W)`, what a sponge scales its damping by."""
+        mass = (
+            indicator
+            * self.density
+            * apply_cell_weights(self, cp.ones(self.Nx_padded, dtype=self.dtype))
+        )
+        return 1.0 / cp.maximum(mass, cp.finfo(self.dtype).tiny)
+
+    def build_materials(self, indicator: cpt.NDArray) -> dict:
+        """Point inverse inertia per component and the design field on the stress points."""
+        gamma = cp.ascontiguousarray(indicator, dtype=self.dtype)
+        minv = cp.zeros((self.ncomp, *self.Nx_padded), dtype=self.dtype)
+        for c in range(self.ncomp):
+            mass = (
+                self.density
+                * component_weights(self, c)
+                * point_average(self, gamma, c)
+            )
+            minv[c] = 1.0 / cp.maximum(mass, cp.finfo(self.dtype).tiny)
+        for face in faces_with(self, Clamped):
+            wall = [slice(None)] * self.ndim
+            wall[face // 2] = 1 if face % 2 == 0 else self.Nx[face // 2] - 2
+            for c in range(self.ncomp):
+                if c != face // 2:
+                    minv[(c, *wall)] = 0.0
+        mat = {
+            "minv": cp.ascontiguousarray(minv),
+            "gnode": apply_cell_weights(self, gamma.copy()),
+            "gamma": gamma,
+        }
+        if self.ndim > 1:
+            gshear = cp.zeros((self.npairs, *self.Nx_padded), dtype=self.dtype)
+            for p, axes in enumerate(PAIRS[self.ndim][self.ndim :]):
+                gshear[p] = pair_weights(self, axes) * pair_average(self, gamma, axes)
+            mat["gshear"] = cp.ascontiguousarray(gshear)
+        if self.damping is not None:
+            mat["damping"] = self.damping
+        return mat
+
+    def define_step(self, kernels: cp.RawModule, mat: dict) -> Callable:
+        """Closure launching the stress kernel and then the update over (u0, u1, u2)."""
+        stress_kernel = kernels.get_function("stress_kernel")
+        fd_kernel = kernels.get_function("fd_kernel")
+        grid, block = grid_block(self)
+        # the stress scratch outlives the closure, its ghost region never written
+        sigma = cp.zeros((self.nvoigt, *self.Nx_padded), dtype=self.dtype)
+        clamped = face_mask(self, Clamped)
+        material = [self.dtype(self.lame), self.dtype(self.shear)]
+        inv_dx = [self.dtype(1.0 / d) for d in self.dx]
+        sargs = [None, sigma, mat["gnode"]]
+        if self.ndim > 1:
+            sargs.append(mat["gshear"])
+        sargs += [
+            *material,
+            clamped,
+            np.int32(self.comp_stride),
+            *axis_geometry(self, inv_dx),
+        ]
+        uargs = [None, None, None, sigma, mat["minv"]]
+        if self.damping is not None:
+            uargs += [mat["damping"], self.dtype(self.dt)]
+        uargs += [
+            clamped,
+            np.int32(self.comp_stride),
+            *axis_geometry(self, self.step_factors()),
+        ]
+
+        def fd_step(u0, u1, u2):
+            sargs[0] = u1
+            stress_kernel(grid, block, sargs)
+            uargs[0], uargs[1], uargs[2] = u0, u1, u2
+            fd_kernel(grid, block, uargs)
+            return u2
+
+        return fd_step
+
+    def excitation_weights(
+        self, mat: dict, lin_index: cpt.NDArray[cp.int32]
+    ) -> cpt.NDArray:
+        """Source weights `dt**2 / (inertia V)`: the kernel inertia leaves the volume out."""
+        volume = self.dtype(1.0 / float(np.prod(self.dx)))
+        weight = mat["minv"].ravel()[lin_index] * volume
+        if self.damping is not None:
+            node = lin_index % np.int32(self.comp_stride)
+            beta = 0.5 * weight * mat["damping"].ravel()[node] * self.dt
+            weight = weight / (1.0 + beta)
+        return (self.dtype(self.dt**2 * self.source_factor()) * weight).astype(
+            self.dtype
+        )
+
+    def parametrization_jacobian(self, indicator: cpt.NDArray) -> tuple:
+        """Gamma scales inertia and stiffness alike, so both derivatives are 1."""
+        return 1.0, 1.0
+
+    def step_factors(self) -> list:
+        """Per-axis update factors `dt**2 / dx`, the strain carrying the other `1 / dx`."""
+        return [self.dtype(self.dt**2 / d) for d in self.dx]
+
+    def source_factor(self) -> float:
+        """Source scaling, unscaled since rho0 is already folded into the point inertia."""
+        return 1.0
+
+    def adjoint_weights(self, sensors: cpt.NDArray[cp.int32]) -> cpt.NDArray:
+        """`1 / V`: dJ/du is nodal, so it undoes the volume the source weights divide by."""
+        volume = self.dtype(1.0 / float(np.prod(self.dx)))
+        return cp.full(sensors.shape[1], volume, dtype=self.dtype)
+
+    def gradient_fields(self, mat: dict) -> dict[str, cpt.NDArray]:
+        """Accumulators on the component and stress points, plus the design they chain to."""
+        grads = {
+            "mass": cp.zeros((self.ncomp, *self.Nx_padded), dtype=self.dtype),
+            "normal": cp.zeros(self.Nx_padded, dtype=self.dtype),
+        }
+        if self.ndim > 1:
+            grads["shear"] = cp.zeros((self.npairs, *self.Nx_padded), dtype=self.dtype)
+        # the point averages have a design dependent chain rule, so keep the field
+        grads["design"] = mat["gamma"]
+        return grads
+
+    def finalize_gradients(self, grads: dict, kernels: cp.RawModule) -> dict:
+        """Chain the point densities through the averages onto the nodal design field."""
+        gamma = grads["design"]
+        g_mass = cp.zeros(self.Nx_padded, dtype=self.dtype)
+        for c in range(self.ncomp):
+            density = grads["mass"][c] * component_weights(self, c) * self.density
+            g_mass += point_average_adjoint(self, density, c)
+        # the normal density sits on the nodes, so its chain rule is the weight alone
+        g_stiff = apply_cell_weights(self, grads["normal"].copy())
+        for p, axes in enumerate(PAIRS[self.ndim][self.ndim :]):
+            density = grads["shear"][p] * pair_weights(self, axes)
+            g_stiff += pair_average_adjoint(self, density, gamma, axes)
+        return {"mass": g_mass, "stiff": g_stiff}
+
+    def _density_args(self, grads: dict) -> list:
+        """The accumulator and material head shared by the gradient and Frechet closures."""
+        args = [grads["mass"], grads["normal"]]
+        if self.ndim > 1:
+            args.append(grads["shear"])
+        return args
+
+    def define_gradient(
+        self, kernels: cp.RawModule, mat: dict, grads: dict
+    ) -> Callable:
+        """Closure accumulating the point mass and stress-point stiffness densities."""
+        gradient_kernel = kernels.get_function("gradient_kernel")
+        grid, block = grid_block(self)
+        inv_dx = [self.dtype(1.0 / d) for d in self.dx]
+        args = (
+            self._density_args(grads)
+            + [None, None, None, None]
+            + [
+                self.dtype(self.lame),
+                self.dtype(self.shear),
+                self.dtype(1.0 / self.dt**2),
+                face_mask(self, Clamped),
+                np.int32(self.comp_stride),
+                *axis_geometry(self, inv_dx),
+            ]
+        )
+        head = len(self._density_args(grads))
+
+        def gradient_step(u0, u1, u2, l1):
+            args[head], args[head + 1] = u0, u1
+            args[head + 2], args[head + 3] = u2, l1
+            gradient_kernel(grid, block, args)
+
+        return gradient_step
+
+    def define_frechet(
+        self, kernels: cp.RawModule, accs: dict, sign: float
+    ) -> Callable:
+        """Closure accumulating both quadratic densities of one field triplet, times `sign`."""
+        frechet_kernel = kernels.get_function("frechet_kernel")
+        grid, block = grid_block(self)
+        inv_dx = [self.dtype(1.0 / d) for d in self.dx]
+        args = (
+            self._density_args(accs)
+            + [None, None, None]
+            + [
+                self.dtype(self.lame),
+                self.dtype(self.shear),
+                self.dtype(sign / (2.0 * self.dt) ** 2),
+                self.dtype(-sign),
+                face_mask(self, Clamped),
+                np.int32(self.comp_stride),
+                *axis_geometry(self, inv_dx),
+            ]
+        )
+        head = len(self._density_args(accs))
+
+        def frechet_step(u0, u1, u2):
+            args[head], args[head + 1], args[head + 2] = u0, u1, u2
+            frechet_kernel(grid, block, args)
+
+        return frechet_step

cuwave/evals.py

@@ -0,0 +1,130 @@
+import cupy as cp
+import cupy.typing as cpt
+
+NAN = float("nan")
+
+
+# -------------------------------------- helpers --------------------------------------
+def _flatten_pair(
+    field: cpt.NDArray, truth: cpt.NDArray
+) -> tuple[cpt.NDArray, cpt.NDArray]:
+    """Ravel field and truth to 1D, checking shapes match."""
+    field, truth = cp.asarray(field).ravel(), cp.asarray(truth).ravel()
+    if field.shape != truth.shape:
+        raise ValueError(f"shape mismatch: {field.shape} against {truth.shape}")
+    return field, truth
+
+
+def _resolve_threshold(truth: cpt.NDArray, threshold: float | None = None) -> float:
+    """Return threshold, defaulting to the midpoint of truth's range.
+
+    The truth is always split at that midpoint, which is the natural cut for a
+    two-material indicator, so no separate truth threshold is ever passed in.
+    """
+    return 0.5 * float(truth.min() + truth.max()) if threshold is None else threshold
+
+
+def _ranked(
+    field: cpt.NDArray, truth: cpt.NDArray
+) -> tuple[cpt.NDArray, cpt.NDArray, int]:
+    """Field and labels ordered by descending damage score. Also returns the positive count."""
+    field, truth = _flatten_pair(field, truth)
+    label = truth < _resolve_threshold(truth)
+    order = cp.argsort(field)  # descending damage score (ascending indicator)
+    return field[order], label[order], int(label.sum())
+
+
+# ------------------------------ binary indicator fields ------------------------------
+def confusion(
+    field: cpt.NDArray, truth: cpt.NDArray, threshold: float | None = None
+) -> tuple[int, int, int, int]:
+    """(tp, fp, fn, tn) counts, `field` split at `threshold` and `truth` at its midpoint."""
+    field, truth = _flatten_pair(field, truth)
+    label = truth < _resolve_threshold(truth)
+    predicted = field < _resolve_threshold(truth, threshold)
+    tp = int(cp.count_nonzero(predicted & label))
+    fp = int(cp.count_nonzero(predicted)) - tp
+    fn = int(cp.count_nonzero(label)) - tp
+    return tp, fp, fn, predicted.size - tp - fp - fn
+
+
+def precision(
+    field: cpt.NDArray, truth: cpt.NDArray, threshold: float | None = None
+) -> float:
+    """Share of the detected damage that is true, `tp / (tp + fp)`"""
+    tp, fp, _, _ = confusion(field, truth, threshold)
+    return tp / (tp + fp) if tp + fp else NAN
+
+
+def recall(
+    field: cpt.NDArray, truth: cpt.NDArray, threshold: float | None = None
+) -> float:
+    """Share of the true damage that is detected, `tp / (tp + fn)` (true positive rate)"""
+    tp, _, fn, _ = confusion(field, truth, threshold)
+    return tp / (tp + fn) if tp + fn else NAN
+
+
+def false_positive_rate(
+    field: cpt.NDArray, truth: cpt.NDArray, threshold: float | None = None
+) -> float:
+    """Share of the intact material flagged as damage, `fp / (fp + tn)`"""
+    _, fp, _, tn = confusion(field, truth, threshold)
+    return fp / (fp + tn) if fp + tn else NAN
+
+
+def f1_score(
+    field: cpt.NDArray, truth: cpt.NDArray, threshold: float | None = None
+) -> float:
+    """Harmonic mean of `precision` and `recall`, `2 tp / (2 tp + fp + fn)`"""
+    tp, fp, fn, _ = confusion(field, truth, threshold)
+    return 2 * tp / (2 * tp + fp + fn) if tp else 0.0 if fp or fn else NAN
+
+
+def pr_auc(field: cpt.NDArray, truth: cpt.NDArray) -> float:
+    """Area under the precision-recall curve, as the average precision."""
+    score, label, positives = _ranked(field, truth)
+    if positives == 0:
+        return NAN
+    tp = cp.cumsum(label, dtype=cp.float64)
+    counted = cp.arange(1, label.size + 1, dtype=cp.float64)
+    # only the last entry of a run of equal scores is a threshold of its own
+    ends = cp.append(cp.diff(score) != 0, True)
+    tp, counted = tp[ends], counted[ends]
+    recalled = tp / positives
+    previous = cp.concatenate((cp.zeros(1, dtype=cp.float64), recalled[:-1]))
+    return float(cp.sum((recalled - previous) * (tp / counted)))
+
+
+def roc_auc(field: cpt.NDArray, truth: cpt.NDArray) -> float:
+    """Area under the receiver operating characteristic, `recall` against `false_positive_rate`."""
+    field, truth = _flatten_pair(field, truth)
+    label = truth < _resolve_threshold(truth)
+    positives = int(cp.count_nonzero(label))
+    negatives = label.size - positives
+    if positives == 0 or negatives == 0:
+        return NAN
+    ordered = cp.sort(-field)
+    damaged = -field[label]
+    left = cp.searchsorted(ordered, damaged, side="left")
+    right = cp.searchsorted(ordered, damaged, side="right")
+    ranks = 0.5 * float(cp.sum(left + right + 1))  # 1-based mid-ranks
+    return (ranks - 0.5 * positives * (positives + 1)) / (positives * negatives)
+
+
+def non_discreteness(field: cpt.NDArray, region: cpt.NDArray | None = None) -> float:
+    """Greyness measure `mean(4 x (1 - x))` (Sigmund 2007), 0 for a design already 0/1.
+
+    Takes no truth, so it also scores a topology optimization result, where the number
+    that matters is how far the grey design the optimizer saw is from the thresholded
+    one that gets built. See https://doi.org/10.1007/s00158-006-0087-x
+    """
+    x = cp.asarray(field)
+    x = x if region is None else x[region]
+    return float(cp.mean(4.0 * x * (1.0 - x))) if x.size else NAN
+
+
+def l2_error(field: cpt.NDArray, truth: cpt.NDArray, relative: bool = True) -> float:
+    """L2 norm of the reconstruction error, normalized by the norm of `truth`."""
+    field, truth = _flatten_pair(field, truth)
+    error = float(cp.linalg.norm(field - truth))
+    return error / float(cp.linalg.norm(truth)) if relative else error

cuwave/geometry.py

@@ -0,0 +1,226 @@
+"""Boolean region masks on the padded simulation grid
+
+Every helper takes the `coords` returned by `grid_coords` and an optional `out` mask to
+accumulate into: it is created when omitted
+"""
+
+import math
+from collections.abc import Sequence
+
+import cupy as cp
+import cupy.typing as cpt
+import numpy as np
+import numpy.typing as npt
+
+
+# -------------------------------------- helpers --------------------------------------
+def _accumulate(
+    mask: cpt.NDArray[cp.bool_], out: cpt.NDArray[cp.bool_] | None
+) -> cpt.NDArray[cp.bool_]:
+    if out is None:
+        return mask
+    out |= mask
+    return out
+
+
+def _empty(
+    coords: Sequence[cpt.NDArray], out: cpt.NDArray[cp.bool_] | None
+) -> cpt.NDArray[cp.bool_]:
+    return cp.zeros(coords[0].shape, dtype=bool) if out is None else out
+
+
+def ellipse(
+    coords: Sequence[cpt.NDArray],
+    center: Sequence[float],
+    radii: Sequence[float],
+    angle: float = 0.0,
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """Interior of the ellipse with semi-axes `radii`, rotated by `angle` radians"""
+    dx = coords[0] - center[0]
+    dy = coords[1] - center[1]
+    if angle:
+        cos, sin = math.cos(angle), math.sin(angle)
+        dx, dy = cos * dx + sin * dy, cos * dy - sin * dx
+    return _accumulate((dx / radii[0]) ** 2 + (dy / radii[1]) ** 2 < 1.0, out)
+
+
+def circle(
+    coords: Sequence[cpt.NDArray],
+    center: Sequence[float],
+    radius: float,
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """Interior of the circle of radius `radius`"""
+    return ellipse(coords, center, (radius, radius), out=out)
+
+
+def circles(
+    coords: Sequence[cpt.NDArray],
+    centers: npt.ArrayLike,
+    radius: float,
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """Union of equal-radius circles, one per row of `centers`, in any dimension.
+
+    Args:
+        coords: the grid the mask is built on.
+        centers: (num, ndim) physical centers, as `line` returns them.
+        radius: the radius shared by all of them.
+        out: mask to accumulate into, created when omitted.
+
+    Returns:
+        the accumulated mask, true within `radius` of any center.
+    """
+    centers = np.atleast_2d(centers)
+    if centers.shape[1] != len(coords):
+        raise ValueError(f"centers need {len(coords)} coordinates, not {centers.shape}")
+    out = _empty(coords, out)
+    for center in centers:
+        distance = sum((x - c) ** 2 for x, c in zip(coords, center))
+        out |= distance < radius**2
+    return out
+
+
+def box(
+    coords: Sequence[cpt.NDArray],
+    center: Sequence[float],
+    sizes: Sequence[float],
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """Interior of the axis-aligned box with side lengths `sizes`, boundary included"""
+    inside = None
+    for x, c, size in zip(coords, center, sizes):
+        slab = cp.abs(x - c) <= 0.5 * size
+        inside = slab if inside is None else inside & slab
+    return _accumulate(inside, out)
+
+
+def rectangle(
+    coords: Sequence[cpt.NDArray],
+    center: Sequence[float],
+    sizes: Sequence[float],
+    angle: float = 0.0,
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """Interior of the rectangle with side lengths `sizes`, rotated by `angle` radians"""
+    dx = coords[0] - center[0]
+    dy = coords[1] - center[1]
+    if angle:
+        cos, sin = math.cos(angle), math.sin(angle)
+        dx, dy = cos * dx + sin * dy, cos * dy - sin * dx
+    inside = (cp.abs(dx) <= 0.5 * sizes[0]) & (cp.abs(dy) <= 0.5 * sizes[1])
+    return _accumulate(inside, out)
+
+
+def random_ellipses(
+    coords: Sequence[cpt.NDArray],
+    count: int,
+    radii: tuple[float, float],
+    bounds: Sequence[tuple[float, float]],
+    angle: tuple[float, float] = (0.0, math.pi),
+    overlap: bool = True,
+    rng: int | np.random.Generator | None = None,
+    attempts: int = 100,
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """`count` ellipses at uniformly random centers, semi-axes, and orientations.
+
+    Args:
+        coords: the grid the mask is built on.
+        count: how many ellipses to place.
+        radii: (min, max) a semi-axis is drawn from, independently per axis.
+        bounds: one (low, high) per axis, the box centers are drawn from.
+        angle: (min, max) rotation in radians.
+        overlap: when false, reject a center whose circumscribed circle meets an
+            earlier one, and raise once `attempts` draws in a row are rejected.
+        rng: seed or generator, so a driver reproduces its geometry.
+        out: mask to accumulate into, created when omitted.
+
+    Returns:
+        the accumulated mask, true inside the ellipses.
+    """
+    rng = np.random.default_rng(rng)
+    out = _empty(coords, out)
+    placed = []  # (center, circumscribed radius) of the ellipses accepted so far
+    for i in range(count):
+        for _ in range(attempts):
+            center = tuple(rng.uniform(low, high) for low, high in bounds)
+            semi = tuple(rng.uniform(*radii) for _ in bounds)
+            bound = max(semi)
+            if overlap or all(
+                math.dist(center, other) >= bound + radius for other, radius in placed
+            ):
+                break
+        else:
+            raise RuntimeError(
+                f"placed only {i} of {count} ellipses without overlap "
+                f"({attempts} attempts for the next one)"
+            )
+        placed.append((center, bound))
+        ellipse(coords, center, semi, rng.uniform(*angle), out)
+    return out
+
+
+def stacked_circles(
+    coords: Sequence[cpt.NDArray],
+    count: int,
+    radius: float,
+    span: tuple[float, float],
+    center: float | Sequence[float],
+    axis: int = 0,
+    ratio: float = 0.5,
+    order: str | None = "descending",
+    out: cpt.NDArray[cp.bool_] | None = None,
+) -> cpt.NDArray[cp.bool_]:
+    """A row of geometrically shrinking circles, evenly gapped along one axis.
+
+    Args:
+        coords: the grid the mask is built on.
+        count: how many circles to place.
+        radius: the largest radius, which `ratio` shrinks from.
+        span: (start, end) along `axis` the row is fitted into, tangent to both ends.
+        center: the coordinate on each of the other axes.
+        axis: the axis the circles are stacked along.
+        ratio: factor between consecutive radii.
+        order: `descending` or `ascending` along the axis, or None for equal radii.
+        out: mask to accumulate into, created when omitted.
+
+    Returns:
+        the accumulated mask, true inside the circles.
+    """
+    if order not in (None, "ascending", "descending"):
+        raise ValueError("order must be 'descending', 'ascending' or None")
+    if order is None:
+        radii = [radius] * count
+    else:
+        radii = [radius * ratio**i for i in range(count)]
+    if order == "ascending":
+        radii.reverse()
+
+    length = span[1] - span[0]
+    gap = (length - 2.0 * sum(radii)) / (count - 1) if count > 1 else 0.0
+    if gap < 0.0:
+        raise ValueError(
+            f"{count} circles of radius {radius} and ratio {ratio} do not fit "
+            f"into a span of {length}"
+        )
+
+    others = np.atleast_1d(center).tolist()  # the nonstacking axes, in order
+    if len(others) != len(coords) - 1:
+        raise ValueError(f"center needs {len(coords) - 1} coordinate(s), not {others}")
+
+    out = _empty(coords, out)
+    position = span[0] + radii[0]
+    for i, r in enumerate(radii):
+        if i:
+            position += radii[i - 1] + gap + r
+        origin = others.copy()
+        origin.insert(axis % len(coords), position)
+        circle(coords, origin, r, out)
+    return out
+
+
+def nodes(mask: cpt.NDArray[cp.bool_]) -> cpt.NDArray[cp.int32]:
+    """The (ndim, count) grid indices `mask` selects, as the kernels take them"""
+    return cp.stack(cp.nonzero(mask)).astype(cp.int32)