cuwave 0.1.0__py3-none-any.whl

cuwave/__init__.py

@@ -0,0 +1,8 @@
+"""CuWave: a single-GPU, differentiable finite-difference wave solver"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("cuwave")
+except PackageNotFoundError:  # a checkout on sys.path without an install
+    __version__ = "0.0.0"

cuwave/anisotropic.py

@@ -0,0 +1,337 @@
+"""Cell-assembled elasticity, the collocated sibling of the staggered `ElasticWave`.
+
+The stencil is a 9-point one in 2D and 27-point in 3D, gathered cell by cell rather
+than axis by axis, since a variable-coefficient elastic operator couples the components
+through mixed derivatives that a per-axis flux cannot carry. Its coefficients are
+derived as `-B^T C B` with `C` on the cell, which is what makes the operator exactly
+symmetric for a varying material, never differentiates the material, leaves the
+leapfrog reversible, and makes a traction-free surface the natural condition of the
+interior-cell sum. `C` is any symmetric Voigt matrix, which is what earns this scheme
+its keep next to the staggered one: order 2 only, but collocated components and a
+general anisotropy.
+"""
+
+from __future__ import annotations
+
+import itertools
+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, faces_with
+from .elastic import voigt
+from .wave import PAIRS, Simulation, apply_cell_weights, grid_block
+
+KERNEL_PATH = Path(__file__).parent / "kernels" / "anisotropic.cu"
+SENSITIVITY_PATH = Path(__file__).parent / "kernels" / "anisotropic_sensitivity.cu"
+
+
+# -------------------------------------- helpers --------------------------------------
+def corner_bits(ndim: int) -> list[tuple[int, ...]]:
+    """The `2**ndim` nodes of a cell, node `c` having bit `d` set on the plus side of axis `d`."""
+    return [tuple((c >> d) & 1 for d in range(ndim)) for c in range(2**ndim)]
+
+
+def cell_stencil(
+    ndim: int, dx: tuple[float, ...], C: npt.NDArray
+) -> npt.NDArray[np.float64]:
+    """One cell's contribution to the nodal stencil, ordered (node, component).
+
+    Built as `sum_q w_q B_q^T C B_q` over the cell, `B` the discrete symmetric gradient
+    on the `2**ndim` corners, so the assembled operator is symmetric by construction
+    rather than by inspection. The entries collapse to the 9-point (27-point in 3D)
+    finite difference stencil
+
+        f_x = (lame + 2 mu) [M_y * D2_x] u_x + mu [M_x * D2_y] u_x
+              + (lame + mu) [D_x * D_y] u_y
+
+    with the second difference `D2` = (1, -2, 1), the centred first difference `D` and
+    the transverse average `M` = (1, 4, 1) / 6. That average is the only departure from
+    the textbook elastic stencil, and it is what removes the checkerboard from the null
+    space: one quadrature point per axis would give (1, 2, 1) / 4 and leave it there as
+    an undamped hourglass mode.
+
+    Args:
+        ndim: dimensionality of the cell.
+        dx: cell side per axis.
+        C: (voigt, voigt) symmetric stiffness matrix, from `elastic.voigt` or the
+            caller.
+
+    Returns:
+        the (n * ndim, n * ndim) matrix for `n = 2**ndim`, node `c` and component `i`
+        occupying row `c * ndim + i`, `c` running over the corners in `corner_bits`
+        order.
+    """
+    corners = corner_bits(ndim)
+    nloc = len(corners) * ndim
+    nodes, weights = np.polynomial.legendre.leggauss(2)
+    nodes = 0.5 * (nodes + 1.0)
+    weights = 0.5 * weights * float(np.prod(dx)) ** (1.0 / ndim)
+    K = np.zeros((nloc, nloc))
+    for point in itertools.product(range(2), repeat=ndim):
+        weight = float(np.prod([weights[q] for q in point]))
+        value = [(1.0 - nodes[q], nodes[q]) for q in point]
+        dN = np.zeros((len(corners), ndim))
+        for m, entry in enumerate(corners):
+            for k in range(ndim):
+                term = (-1.0, 1.0)[entry[k]] / dx[k]
+                for axis in range(ndim):
+                    if axis != k:
+                        term *= value[axis][entry[axis]]
+                dN[m, k] = term
+        B = np.zeros((len(PAIRS[ndim]), nloc))
+        for r, (axis_k, axis_l) in enumerate(PAIRS[ndim]):
+            for m in range(len(corners)):
+                if axis_k == axis_l:
+                    B[r, m * ndim + axis_k] += dN[m, axis_k]
+                else:
+                    B[r, m * ndim + axis_l] += dN[m, axis_k]  # engineering shear
+                    B[r, m * ndim + axis_k] += dN[m, axis_l]
+        K += weight * (B.T @ C @ B)
+    return K
+
+
+def cell_average(sim: Simulation, field: cpt.NDArray) -> cpt.NDArray:
+    """Harmonic mean of `field` over the `2**ndim` corners of a cell, at its low corner.
+
+    Harmonic and not arithmetic for the reason the scalar flux uses it: it keeps the
+    cell stiffness single valued across a material jump, and it is what holds the
+    stable timestep together at a high contrast, where a light node borders a stiff
+    cell.
+    """
+    out = cp.zeros(sim.Nx_padded, dtype=sim.dtype)
+    safe = cp.maximum(field, cp.finfo(sim.dtype).tiny)
+    inner = tuple(slice(0, n - 1) for n in sim.Nx)
+    for corner in corner_bits(sim.ndim):
+        shifted = tuple(slice(b, n - 1 + b) for b, n in zip(corner, sim.Nx))
+        out[inner] += 1.0 / safe[shifted]
+    out[inner] = 2.0**sim.ndim / out[inner]
+    return out
+
+
+# ------------------------------- discretization setup --------------------------------
+@dataclass
+class AnisotropicElasticWave(Simulation):
+    """Cell-assembled 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. `C` overrides the isotropic Voigt matrix with an
+    anisotropic one at gamma = 1, which the cell assembly carries where the staggered
+    scheme cannot. Order 2 only: the cell gather costs `(2r)**(2 ndim)` per node, so a
+    wide stencil belongs to `ElasticWave`.
+    """
+
+    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
+    C: npt.NDArray | None = None  # (voigt, voigt) stiffness at gamma = 1, or isotropic
+
+    kernel_path = KERNEL_PATH
+    sensitivity_path = SENSITIVITY_PATH
+    default_boundary = Traction
+    gradient_names = ("mass", "stiff", "cell")
+
+    @property
+    def ncomp(self) -> int:
+        """One displacement component per axis."""
+        return self.ndim
+
+    def __post_init__(self) -> None:
+        """Validate the material, the 2D plane assumption and the order, then derive the grid."""
+        super().__post_init__()
+        if None in (self.density, self.wavespeed_p, self.wavespeed_s):
+            raise ValueError(
+                "AnisotropicElasticWave 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.space_order != 2:
+            raise ValueError(
+                f"the cell gather costs (2r)**(2 ndim) per node, so order "
+                f"{self.space_order} belongs to the staggered ElasticWave"
+            )
+        self._stencil = None  # built once and reused across material rebuilds
+        if self.wavespeed_s >= self.wavespeed_p:
+            raise ValueError(
+                f"wavespeed_s must be below wavespeed_p: "
+                f"{self.wavespeed_s} >= {self.wavespeed_p}"
+            )
+        nvoigt = len(PAIRS[self.ndim])
+        if self.C is not None:
+            self.C = np.asarray(self.C, dtype=float)
+            if self.C.shape != (nvoigt, nvoigt):
+                raise ValueError(f"C must be ({nvoigt}, {nvoigt}): {self.C.shape}")
+            if not np.allclose(self.C, self.C.T):
+                raise ValueError("C must be symmetric")
+
+    @property
+    def lame(self) -> float:
+        """First Lame parameter `rho0 * (c_p**2 - 2 c_s**2)`."""
+        return self.density * (self.wavespeed_p**2 - 2.0 * self.wavespeed_s**2)
+
+    @property
+    def shear(self) -> float:
+        """Second Lame parameter `rho0 * c_s**2`."""
+        return self.density * self.wavespeed_s**2
+
+    def stencil(self) -> cpt.NDArray:
+        """Stencil table at `gamma = 1`: one cell's `-B^T C B`, flattened for the kernel."""
+        if self._stencil is not None:
+            return self._stencil
+        C = self.C
+        if C is None:
+            C = voigt(self.ndim, self.lame, self.shear, self.plane)
+        K = cell_stencil(self.ndim, self.dx, C)
+        self._stencil = cp.asarray(K.ravel(), dtype=self.dtype)
+        return self._stencil
+
+    def cell_weights(self) -> cpt.NDArray:
+        """Nodal cell weights W, halved once per wall the node sits on."""
+        return apply_cell_weights(self, cp.ones(self.Nx_padded, dtype=self.dtype))
+
+    def inverse_inertia(self, indicator: cpt.NDArray) -> cpt.NDArray:
+        """Lumped `1 / (gamma rho0 V W)`, the mass the interior-cell assembly implies."""
+        volume = float(np.prod(self.dx))
+        mass = indicator * (self.density * volume) * self.cell_weights()
+        return 1.0 / cp.maximum(mass, cp.finfo(self.dtype).tiny)
+
+    def build_materials(self, indicator: cpt.NDArray) -> dict:
+        """Lumped inverse inertia, the cell design field, and the stencil table."""
+        minv = self.inverse_inertia(indicator)
+        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
+            minv[tuple(wall)] = 0.0
+        mat = {
+            "minv": cp.ascontiguousarray(minv, dtype=self.dtype),
+            "gamma": cp.ascontiguousarray(indicator, dtype=self.dtype),
+            "cell": cell_average(self, indicator),
+            "stencil": self.stencil(),
+        }
+        if self.damping is not None:
+            mat["damping"] = self.damping
+        return mat
+
+    def step_kernel_args(self, mat: dict) -> tuple:
+        """Material, stencil table and component stride for the step kernel."""
+        args = (mat["minv"], mat["cell"], mat["stencil"])
+        if self.damping is not None:
+            args += (mat["damping"], self.dtype(self.dt))
+        return args + (np.int32(self.comp_stride),)
+
+    def excitation_weights(
+        self, mat: dict, lin_index: cpt.NDArray[cp.int32]
+    ) -> cpt.NDArray:
+        """Source weights `dt**2 / inertia`, the spatial node read off the folded index."""
+        node = lin_index % np.int32(self.comp_stride)
+        weight = mat["minv"].ravel()[node]
+        if self.damping is not None:
+            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:
+        """`dt**2`; the grid spacing already sits in the stencil table."""
+        return [self.dtype(self.dt**2)] * self.ndim
+
+    def source_factor(self) -> float:
+        """Source scaling, unscaled since rho0 is already folded into the lumped inertia."""
+        return 1.0
+
+    def axis_geometry(self) -> list:
+        """Extents and previous-axis strides, the step kernel's tail without the factors."""
+        geom = [self.Nx[0]]
+        for d in range(1, self.ndim):
+            geom += [self.Nx[d], self.strides[d - 1]]
+        return geom
+
+    def gradient_fields(self, mat: dict) -> dict[str, cpt.NDArray]:
+        """Nodal accumulators plus the cell one the stiffness density lands in first."""
+        grads = {
+            name: cp.zeros(self.Nx_padded, dtype=self.dtype)
+            for name in self.gradient_names
+        }
+        # the harmonic cell mean has a design dependent chain rule, so keep both fields
+        grads["material"] = mat["cell"]
+        grads["design"] = mat["gamma"]
+        return grads
+
+    def finalize_gradients(self, grads: dict, kernels: cp.RawModule) -> dict:
+        """Weight the mass density by W and spread the cell density onto its corners."""
+        apply_cell_weights(self, grads["mass"])
+        cell_to_node = kernels.get_function("cell_to_node_kernel")
+        grid, block = grid_block(self)
+        cell_to_node(
+            grid,
+            block,
+            [
+                grads["stiff"],
+                grads["cell"],
+                grads["material"],
+                grads["design"],
+                self.dtype(1.0 / 2.0**self.ndim),
+                *self.axis_geometry(),
+            ],
+        )
+        return {"mass": grads["mass"], "stiff": grads["stiff"]}
+
+    def define_gradient(
+        self, kernels: cp.RawModule, mat: dict, grads: dict
+    ) -> Callable:
+        """Closure accumulating the nodal mass and cell stiffness densities."""
+        gradient_kernel = kernels.get_function("gradient_kernel")
+        grid, block = grid_block(self)
+        # d(mass)/d(gamma) is rho0 V, the W of the lumping supplied by the epilogue
+        mass_factor = self.dtype(self.density * float(np.prod(self.dx)) / self.dt**2)
+        args = [grads["mass"], grads["cell"], None, None, None, None] + [
+            mat["stencil"],
+            mass_factor,
+            np.int32(self.comp_stride),
+            *self.axis_geometry(),
+        ]
+
+        def gradient_step(u0, u1, u2, l1):
+            args[2], args[3], args[4], args[5] = u0, u1, 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)
+        volume = float(np.prod(self.dx))
+        args = [accs["mass"], accs["cell"], None, None, None] + [
+            self.stencil(),
+            self.dtype(sign * self.density * volume / (2.0 * self.dt) ** 2),
+            self.dtype(-sign),
+            np.int32(self.comp_stride),
+            *self.axis_geometry(),
+        ]
+
+        def frechet_step(u0, u1, u2):
+            args[2], args[3], args[4] = u0, u1, u2
+            frechet_kernel(grid, block, args)
+
+        return frechet_step
+
+    def adjoint_weights(self, sensors: cpt.NDArray[cp.int32]) -> cpt.NDArray:
+        """Ones: the lumped inertia already carries W, and dJ/du is nodal, not a density."""
+        return cp.ones(sensors.shape[1], dtype=self.dtype)

cuwave/boundary.py

@@ -0,0 +1,255 @@
+"""Boundary conditions, one per (axis, side).
+
+A `BoundaryCondition` is a declarative marker: it names a kernel and nothing more, so a
+setup can place one per face in `Simulation.boundary` long before the module is
+compiled. `define_boundary` turns the markers into the launch closures once
+`compile_kernels` has run, which is why `simulate` needs no separate preparation phase.
+
+`sponge` opens the domain from the other side: it dissipates in the material behind a
+face rather than acting on the ghost ring, so it needs no kernel and no marker of its own.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import cupy as cp
+import numpy as np
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+    import cupy.typing as cpt
+
+    from .wave import Simulation
+
+
+@dataclass(frozen=True, repr=False)
+class BoundaryCondition:
+    """Names a kernel in the equation's .cu, or nothing. Frozen, so it can key the grouping."""
+
+    kernel: str | None
+    name: str = ""
+
+    def __repr__(self) -> str:
+        # so that printing a Simulation shows the condition, not the kernel name
+        return self.name or self.kernel.removesuffix("_kernel")
+
+    def define(
+        self, sim: Simulation, kernels: cp.RawModule, faces: Sequence[int]
+    ) -> Callable[[cpt.NDArray], None]:
+        """closure applying this condition on `faces`, the codes 2 * axis + side"""
+        kernel = kernels.get_function(self.kernel)
+        threads = 256
+
+        # one thread per boundary node, edges and corners excluded
+        inner = [n - 2 for n in sim.Nx]
+        num_boundary = sum(
+            int(np.prod(inner[:d] + inner[d + 1 :])) for d in (f // 2 for f in faces)
+        )
+        grid = ((num_boundary + threads - 1) // threads,)
+
+        # a bitmask, so the kernel keeps its axis loop at compile time
+        mask = np.int32(sum(1 << f for f in faces))
+
+        geom = [sim.Nx[0]]
+        for d in range(1, sim.ndim):
+            geom += [sim.Nx[d], sim.strides[d - 1]]
+
+        args = [None, mask, *geom]
+
+        def step(u):
+            args[0] = u
+            kernel(grid, (threads,), args)
+
+        return step
+
+
+Neumann = BoundaryCondition("homogeneous_neumann_kernel")
+Dirichlet = BoundaryCondition("homogeneous_dirichlet_kernel")
+# an elastic wall is the interior-cell assembly or a zeroed inertia: no kernel needed
+Traction = BoundaryCondition(None, "traction")
+Clamped = BoundaryCondition(None, "clamped")
+# the same walls read electromagnetically, the tangential field held or left natural
+Conductor = BoundaryCondition(None, "conductor")
+Magnetic = BoundaryCondition(None, "magnetic")
+
+
+def faces_with(sim: Simulation, condition: BoundaryCondition) -> list[int]:
+    """The `2 * axis + side` codes of the faces `sim.boundary` marks with `condition`."""
+    return [
+        2 * d + side
+        for d, pair in enumerate(sim.boundary)
+        for side, marker in enumerate(pair)
+        if marker is condition
+    ]
+
+
+def face_mask(sim: Simulation, condition: BoundaryCondition) -> np.int32:
+    """The faces carrying `condition`, as the bitmask the kernels take."""
+    return np.int32(sum(1 << f for f in faces_with(sim, condition)))
+
+
+def canonical_boundary(
+    boundary: BoundaryCondition | Sequence | None,
+    ndim: int,
+    default: BoundaryCondition = Neumann,
+) -> tuple[tuple[BoundaryCondition, BoundaryCondition], ...]:
+    """makes the boundary canonical ((low, high),) * ndim
+
+    Accepts `None` for the equation's `default` on every face.
+    """
+    if boundary is None:
+        boundary = default
+    if isinstance(boundary, BoundaryCondition):
+        boundary = (boundary,) * ndim
+    if len(boundary) != ndim:
+        raise ValueError(f"boundary needs one (low, high) pair per axis: {ndim}")
+    pairs = []
+    for pair in boundary:
+        if isinstance(pair, BoundaryCondition):
+            pair = (pair, pair)
+        if len(pair) != 2:
+            raise ValueError("a boundary axis is a (low, high) pair of conditions")
+        pairs.append(tuple(pair))
+    return tuple(pairs)
+
+
+def define_boundary(
+    sim: Simulation, kernels: cp.RawModule
+) -> Callable[[cpt.NDArray], cpt.NDArray]:
+    """one launch per distinct condition, so the default stays one launch."""
+    groups = {}
+    for d, pair in enumerate(sim.boundary):
+        for side, condition in enumerate(pair):
+            if condition.kernel is not None:
+                groups.setdefault(condition, []).append(2 * d + side)
+    steps = [
+        condition.define(sim, kernels, faces) for condition, faces in groups.items()
+    ]
+
+    def bc_step(u):
+        for step in steps:
+            step(u)
+        return u
+
+    return bc_step
+
+
+def _canonical_faces(ndim: int, faces: Sequence[int] | None) -> tuple[int, ...]:
+    """Expand `None` to every face and check the codes fit `ndim`."""
+    faces = tuple(range(2 * ndim) if faces is None else faces)
+    if any(f not in range(2 * ndim) for f in faces):
+        raise ValueError(f"face codes run to {2 * ndim - 1} in {ndim}D: {faces}")
+    return faces
+
+
+def _validate_layer(sim: Simulation, width: int, faces: Sequence[int] | None) -> tuple:
+    """Check a layer fits behind `faces` and expand `None` to every face."""
+    if width < 1:
+        raise ValueError(f"width must be at least one node: {width}")
+    faces = _canonical_faces(sim.ndim, faces)
+    for d in range(sim.ndim):
+        sides = sum(2 * d + side in faces for side in (0, 1))
+        if sides * width >= sim.Nx[d] - 2:
+            raise ValueError(
+                f"{sides} layer(s) of {width} nodes leave no interior on axis {d}: "
+                f"Nx={sim.Nx[d]}"
+            )
+    return faces
+
+
+def _layer_taper(sim: Simulation, width: int, faces: Sequence[int]) -> cpt.NDArray:
+    """Linear ramp over the `width` nodes behind `faces`, 1 on the wall and 0 inside."""
+    taper = cp.zeros(sim.Nx_padded, dtype=sim.dtype)
+    interior = cp.ones(sim.Nx_padded, dtype=bool)
+    for d in range(sim.ndim):
+        shape = [1] * sim.ndim
+        shape[d] = sim.Nx_padded[d]
+        index = cp.arange(sim.Nx_padded[d], dtype=sim.dtype).reshape(shape)
+        interior &= (index >= 1) & (index <= sim.Nx[d] - 2)
+        for side in (0, 1):
+            if 2 * d + side in faces:
+                wall = 1 if side == 0 else sim.Nx[d] - 2
+                ramp = cp.clip(1.0 - cp.abs(index - wall) / width, 0.0, 1.0)
+                # max, so a corner is graded once rather than by each of its faces
+                taper = cp.maximum(taper, ramp)
+    # the ghost ring is slaved to its mirror and the padding tail is never read
+    return taper * interior
+
+
+def pad_for_sponge(
+    Nx: tuple[int, ...],
+    dx: tuple[float, ...],
+    thickness: float,
+    faces: Sequence[int] | None = None,
+) -> tuple[tuple[int, ...], int, tuple[float, ...], tuple[slice, ...]]:
+    """Grow a region of interest `Nx` by a sponge layer of physical `thickness`.
+
+    The layer is grid the simulation carries but the application does not own, so what
+    a driver needs back is where its region of interest ends up: `origin` shifts the
+    coordinates it places transducers and defects at, and `region` selects it out of
+    the grown grid for a design mask or a figure.
+
+    Args:
+        Nx: logical grid points per axis of the region of interest, ghost nodes
+            included.
+        dx: grid spacing per axis.
+        thickness: layer depth in physical units, taken in nodes off the finest axis so
+            that no face comes out thinner than asked for.
+        faces: the `2 * axis + side` codes to line, or None for every face.
+
+    Returns:
+        (Nx, width, origin, region): the grown extent to build the simulation on, the
+        layer `width` in nodes to hand `sponge`, the physical origin of the region of
+        interest per axis, and the index tuple selecting its interior nodes.
+    """
+    if thickness <= 0.0:
+        raise ValueError(f"thickness must be positive: {thickness}")
+    faces = _canonical_faces(len(Nx), faces)
+    width = round(thickness / min(dx))
+    if width < 1:
+        raise ValueError(f"thickness {thickness} is under one node at dx {min(dx)}")
+    pads = [
+        tuple(width if 2 * d + side in faces else 0 for side in (0, 1))
+        for d in range(len(Nx))
+    ]
+    grown = tuple(n + lo + hi for n, (lo, hi) in zip(Nx, pads))
+    origin = tuple(lo * h for (lo, _), h in zip(pads, dx))
+    region = tuple(slice(lo + 1, n - 1 - hi) for (lo, hi), n in zip(pads, grown))
+    return grown, width, origin, region
+
+
+def sponge(
+    sim: Simulation,
+    indicator: cpt.NDArray,
+    width: int,
+    beta: float,
+    faces: Sequence[int] | None = None,
+) -> cpt.NDArray:
+    """Damping field ramping to `beta` over the `width` nodes behind a face, 0 elsewhere.
+
+    The price is losslessness: the field is rejected by `superposition_sensitivity`,
+    whose reverse-time reconstruction needs an operator it can run backwards, and it is
+    what `reconstruction_sensitivity` records a strip of in order to march past it.
+
+    Args:
+        sim: the simulation the field is built for, whose `dt` and inertia scale it.
+        indicator: the design field, read for the inertia the damping is scaled by.
+        width: layer thickness in nodes, measured inward from the wall node.
+        beta: peak `d * dt / 2m` at the wall, the dimensionless decay per step.
+        faces: the `2 * axis + side` codes to line, or None for every face.
+
+    Returns:
+        the field to set as `Simulation.damping`, over the padded grid, ramped
+        quadratically so the layer front is not a coherent reflector.
+    """
+    if beta < 0.0:
+        raise ValueError(f"beta must be non-negative: {beta}")
+    faces = _validate_layer(sim, width, faces)
+    minv = sim.inverse_inertia(indicator)
+    taper = _layer_taper(sim, width, faces)
+    return cp.ascontiguousarray(
+        (2.0 * beta * taper**2 / (sim.dt * minv)).astype(sim.dtype)
+    )