Source code for acoustic_spaces.engine.gpu

"""The wave solver's time steps on a GPU, through WebGPU.

:class:`GpuWaveSolver` takes a grid that the C++ solver
(:class:`acoustic_spaces._native.WaveSolver`) has set up, with its air, boundaries,
branches, matched layer, source and probes, and a speed of sound per cell where the
grid has one (outdoors in wind and temperature), and steps it with one WGSL compute shader on
any GPU that wgpu reaches: Vulkan (AMD, Intel, NVIDIA, and Mesa's software lavapipe),
Metal or Direct3D 12. It needs the optional ``gpu`` extra (``pip install
"acoustic-spaces[gpu]"``). Its arithmetic is the CPU's, in single precision, so the two
agree to rounding.

Each time step is one dispatch: one thread for each cell of the grid (the interior air
cells take the plain update and the rest return), then one for each boundary cell, each
matched-layer cell and each probe. The two pressure fields swap from one step to the
next, and so do the two sets of branch velocities, by the step's parity.
"""

from __future__ import annotations

import functools
import logging
import sys
from typing import Literal

import numpy as np

#: Where the wave solver runs: ``"auto"`` takes a GPU when wgpu finds a hardware one
#: (and ``acoustic-spaces tune`` did not find the CPU faster for the run's length).
Device = Literal["cpu", "gpu", "auto"]

#: Threads per workgroup, and time steps per command buffer.
_GROUP = 256
_BATCH = 512
#: Cell updates per submission: about a second's work on an integrated GPU, well inside
#: the watchdog that resets a GPU whose job runs too long (10 s on Linux's amdgpu).
_SUBMIT_CELL_STEPS = 2**26
#: Workgroups per dispatch dimension WebGPU always allows.
_MAX_GROUPS = 65535

_SHADER = """
struct Grid {
    cells: u32,
    sy: u32,
    sz: u32,
    specials: u32,
    layers: u32,
    probes: u32,
    nx: u32,
    ny: u32,
    special_at: u32,
    state_at: u32,
    layer_at: u32,
    coefficient_at: u32,
    probe_at: u32,
    probe_cells_at: u32,
    branches: u32,
    layer_state_at: u32,
    link_at: u32,
    offset_at: u32,
    wide: u32,
    scaled: u32,
    scale_at: u32,
    layer_scale_at: u32,
    axial: f32,
    diagonal: f32,
    centre: f32,
    total: f32,
}

struct Step {
    index: u32,
    odd: u32,
    source: f32,
}

@group(0) @binding(0) var<uniform> grid: Grid;
@group(0) @binding(1) var<uniform> now: Step;
// The pressure a step before, overwritten with the next; and the current pressure.
@group(0) @binding(2) var<storage, read_write> next: array<f32>;
@group(0) @binding(3) var<storage, read> current: array<f32>;
// The layout: cell types (four to a word), then the tables the offsets in `grid` give.
@group(0) @binding(4) var<storage, read> table: array<u32>;
// Two sets of branch velocities, then the matched layer's state.
@group(0) @binding(5) var<storage, read_write> state: array<f32>;
@group(0) @binding(6) var<storage, read_write> out: array<f32>;

fn number(at: u32) -> f32 {
    return bitcast<f32>(table[at]);
}

fn interior(i: u32) {
    if (i < grid.sz || i + grid.sz >= grid.cells) {
        return;
    }
    if (((table[i >> 2u] >> ((i & 3u) * 8u)) & 0xffu) != 1u) {
        return;
    }
    let sy = grid.sy;
    let sz = grid.sz;
    let sum = current[i - 1u] + current[i + 1u] + current[i - sy] + current[i + sy] +
              current[i - sz] + current[i + sz];
    // With a speed of sound per cell, the cell's links weigh s times as much (the
    // square of its speed over the grid's) and its centre 2 - total * s, as on the CPU.
    var scaled = grid.scaled != 0u;
    var s = 1.0;
    if (scaled) {
        s = number(grid.scale_at + i);
    }
    if (grid.wide == 0u) {
        if (scaled) {
            next[i] = (2.0 - grid.total * s) * current[i] + (s * grid.axial) * sum - next[i];
        } else {
            next[i] = grid.centre * current[i] + grid.axial * sum - next[i];
        }
        return;
    }
    let edges = current[i - 1u - sy] + current[i + 1u - sy] + current[i - 1u + sy] +
                current[i + 1u + sy] + current[i - 1u - sz] + current[i + 1u - sz] +
                current[i - 1u + sz] + current[i + 1u + sz] + current[i - sy - sz] +
                current[i + sy - sz] + current[i - sy + sz] + current[i + sy + sz];
    if (scaled) {
        next[i] = (2.0 - grid.total * s) * current[i] + (s * grid.axial) * sum +
                  (s * grid.diagonal) * edges - next[i];
        return;
    }
    next[i] = grid.centre * current[i] + grid.axial * sum + grid.diagonal * edges - next[i];
}

fn special(k: u32) {
    let at = grid.special_at + 9u * k;
    let i = table[at];
    let first = table[at + 3u];
    let last = table[at + 4u];
    // Its links: a direction (whose offset wraps round as a u32) and a weight each.
    var sum = 0.0;
    for (var l = table[at + 1u]; l < table[at + 2u]; l++) {
        let e = grid.link_at + 2u * l;
        sum += number(e + 1u) * current[i + table[grid.offset_at + table[e]]];
    }
    // The branch velocities a step before (then the next) and now.
    let before_at = select(0u, grid.branches, now.odd != 0u);
    let now_at = grid.branches - before_at;
    var flow = 0.0;
    for (var j = first; j < last; j++) {
        let c = grid.state_at + 4u * j;
        flow += number(c) * (number(c + 1u) * state[now_at + j] -
                             number(c + 2u) * state[before_at + j]);
    }
    let previous = next[i];
    let value = (number(at + 5u) * current[i] + sum - number(at + 6u) * previous - flow +
                 number(at + 8u) * now.source) * number(at + 7u);
    next[i] = value;
    for (var j = first; j < last; j++) {
        let c = grid.state_at + 4u * j;
        state[before_at + j] += (value - previous) * number(c + 3u) +
                                (number(c + 1u) * state[now_at + j] -
                                 number(c + 2u) * state[before_at + j]);
    }
}

fn layer(k: u32) {
    let i = table[grid.layer_at + k];
    var at = array<u32, 3>(i % grid.nx, (i / grid.nx) % grid.ny, i / grid.sz);
    var strides = array<u32, 3>(1u, grid.sy, grid.sz);
    var starts = array<u32, 3>(0u, grid.nx + 1u, grid.nx + grid.ny + 2u);
    let s = grid.layer_state_at + 9u * k;
    // With a speed of sound per cell, the cell's push weighs its scale, as on the CPU.
    var scale = 1.0;
    if (grid.scaled != 0u) {
        scale = number(grid.layer_scale_at + k);
    }
    var total = 0.0;
    for (var axis = 0u; axis < 3u; axis++) {
        let stride = strides[axis];
        // The centre's then the face's keep and push, at the cell and the one above.
        let c = grid.coefficient_at + 4u * (starts[axis] + at[axis]);
        let below = number(c + 2u) * state[s + 3u + 2u * axis] -
                    number(c + 3u) * (current[i] - current[i - stride]);
        let above = number(c + 6u) * state[s + 4u + 2u * axis] -
                    number(c + 7u) * (current[i + stride] - current[i]);
        state[s + 3u + 2u * axis] = below;
        state[s + 4u + 2u * axis] = above;
        var part = number(c) * state[s + axis] - number(c + 1u) * (above - below);
        if (grid.scaled != 0u) {
            part = number(c) * state[s + axis] - (number(c + 1u) * scale) * (above - below);
        }
        state[s + axis] = part;
        total += part;
    }
    next[i] = total;
}

fn record(k: u32) {
    let first = table[grid.probe_at + k];
    let last = table[grid.probe_at + k + 1u];
    var value = 0.0;
    for (var c = first; c < last; c++) {
        let e = grid.probe_cells_at + 2u * c;
        value += number(e + 1u) * current[table[e]];
    }
    out[now.index * grid.probes + k] = value;
}

@compute @workgroup_size(256)
fn main(@builtin(global_invocation_id) id: vec3<u32>,
        @builtin(num_workgroups) groups: vec3<u32>) {
    var t = id.x + id.y * groups.x * 256u;
    if (t < grid.cells) {
        interior(t);
        return;
    }
    t -= grid.cells;
    if (t < grid.specials) {
        special(t);
        return;
    }
    t -= grid.specials;
    if (t < grid.layers) {
        layer(t);
        return;
    }
    t -= grid.layers;
    if (t < grid.probes) {
        record(t);
    }
}
"""


def _wgpu(what: str = "the wave solver"):
    try:
        import wgpu
    except ImportError as error:  # pragma: no cover - depends on the install
        raise RuntimeError(
            f'{what} needs wgpu to run on a GPU: pip install "acoustic-spaces[gpu]"'
        ) from error
    return wgpu


def _not_a_vulkan_setup_note(record: logging.LogRecord) -> bool:
    """Whether wgpu's log ``record`` is anything but a note on setting up Vulkan: one of
    the Vulkan loader's, or the line after it naming the Vulkan instance it is about, or
    wgpu's own on an extension the computer's Vulkan lacks (all of them, with no Vulkan
    driver; wgpu 0.31, the last for Python 3.10, warns of each)."""
    message = record.getMessage()
    return not (
        "[Loader Message" in message
        or message.startswith("\tobjects: (type: INSTANCE,")
        or message.startswith("Unable to find extension: ")
    )


def _primary_backends() -> None:
    """Have wgpu use Vulkan, Metal or Direct3D 12 only, never its OpenGL backend: setting
    that up through EGL aborts the whole process (a Rust panic Python cannot catch) when
    the editor's 3D view already holds an OpenGL context. On Windows, Direct3D 12's
    shader compiler (FXC) also goes without its optimizer (wgpu's debug flag), which
    miscompiled the ray tracer's vegetation: rays scattered in it came out where they
    had started. The driver optimizes the shader anyway, and the compile takes no
    longer. (Only flags every wgpu from 0.31 on knows: an unknown one sets nothing.)
    The debug flag also has wgpu pass on the Vulkan loader's notes, such as finding no
    driver on a computer with Direct3D 12 only, and wgpu 0.31 warns of every extension
    such a computer's Vulkan lacks: they say nothing to a user, and are left out of
    wgpu's log."""
    flags = ["Debug"] if sys.platform == "win32" else ["Default"]
    if sys.platform == "win32":
        logging.getLogger("wgpu").addFilter(_not_a_vulkan_setup_note)
    try:
        from wgpu.backends.wgpu_native.extras import set_instance_extras

        set_instance_extras(backends=["Primary"], flags=flags)
    except (ImportError, KeyError, RuntimeError):  # another backend, or set up already
        pass


@functools.lru_cache(maxsize=1)
def _adapter():
    """The GPU wgpu picks (a hardware one first), or None."""
    try:
        import wgpu
    except ImportError:
        return None
    _primary_backends()
    try:
        return wgpu.gpu.request_adapter_sync(power_preference="high-performance")
    except Exception:  # no driver, or none wgpu can use
        return None


@functools.lru_cache(maxsize=1)
def _device():
    adapter = _adapter()
    if adapter is None:
        raise RuntimeError("wgpu finds no GPU")
    names = ("max-storage-buffer-binding-size", "max-buffer-size")
    return adapter.request_device_sync(
        label="acoustic-spaces",
        required_limits={name: adapter.limits[name] for name in names},
    )


[docs] def gpu_name() -> str | None: """The GPU the wave solver would run on, as ``"<device> (<backend>, <type>)"``, or None when wgpu is missing or finds none.""" adapter = _adapter() if adapter is None: return None info = adapter.info return f"{info['device']} ({info['backend_type']}, {info['adapter_type']})"
[docs] def hardware_gpu() -> bool: """Whether wgpu finds a hardware GPU (not a software renderer such as lavapipe).""" adapter = _adapter() return adapter is not None and adapter.info["adapter_type"] != "CPU"
[docs] def use_gpu(device: Device, steps: int | None = None) -> bool: """Whether the wave solver runs on the GPU for the setting ``device``, for a run of ``steps`` steps. ``auto`` takes a hardware GPU: when ``acoustic-spaces tune`` timed both on this computer, only if it steps that many times clearly faster (see :mod:`acoustic_spaces.engine.tuning`).""" if device == "cpu": return False if device == "gpu": if _adapter() is None: try: import wgpu # noqa: F401 except ImportError: raise ValueError( "simulation.wave.device is gpu, which needs wgpu: pip install " '"acoustic-spaces[gpu]"' ) from None raise ValueError( "simulation.wave.device is gpu, but wgpu finds no GPU: install a Vulkan, " "Metal or Direct3D 12 driver, or set it to cpu or auto" ) return True if device == "auto": if not hardware_gpu(): return False from acoustic_spaces.engine import tuning faster = None if steps is None else tuning.wave_prefers_gpu(steps) return True if faster is None else faster raise ValueError(f"the wave solver's device must be cpu, gpu or auto, not {device!r}")
#: The directions of the C++ solver's neighbours (fdtd.hpp): six axial, twelve edge. _STEPS = ( (-1, 0, 0), (1, 0, 0), (0, -1, 0), (0, 1, 0), (0, 0, -1), (0, 0, 1), (-1, -1, 0), (1, -1, 0), (-1, 1, 0), (1, 1, 0), (-1, 0, -1), (1, 0, -1), (-1, 0, 1), (1, 0, 1), (0, -1, -1), (0, 1, -1), (0, -1, 1), (0, 1, 1), ) # fmt: skip def _words(values: np.ndarray) -> np.ndarray: return np.ascontiguousarray(values, dtype=np.float32).view(np.uint32) def _tables(layout: dict[str, np.ndarray]) -> tuple[np.ndarray, dict[str, int]]: """The layout packed as 32-bit words, and where each table starts.""" n = int(np.prod(layout["shape"])) types = np.zeros(4 * ((n + 3) // 4), np.uint8) types[:n] = layout["types"] special = layout["special"] start = layout["state_start"] links = layout["link_start"] specials = np.column_stack( [ special.astype(np.uint32), links[:-1].astype(np.uint32), links[1:].astype(np.uint32), start[:-1].astype(np.uint32), start[1:].astype(np.uint32), _words(layout["coef_a"]), _words(layout["coef_b"]), _words(layout["coef_inv"]), _words(layout["source"]), ] ) branch = layout["state_branch"] states = np.column_stack( [ layout["state_weight"], layout["branch_now"][branch], layout["branch_before"][branch], layout["branch_gain"][branch], ] ) coefficients = [ np.column_stack( [ layout[f"keep_{axis}"], layout[f"push_{axis}"], layout[f"keep_face_{axis}"], layout[f"push_face_{axis}"], ] ).reshape(-1) for axis in "xyz" if len(layout[f"keep_{axis}"]) ] nx, ny, _ = (int(v) for v in layout["shape"]) # The offset table: for each direction of _STEPS from the first on, the step from a cell's # index to its neighbour's, as a 32-bit word that wraps round below zero; a special cell's # link finds its neighbour through the entry of its direction. It holds the stencil's own # directions (6 on the 7-point grid, 18 on the 19-point one) and runs on to the largest # direction a link takes: with fitted walls the special cells of the 7-point grid link # along the edge diagonals (directions 6 to 17) too. directions = len(layout["weights"]) if len(layout["link_direction"]): directions = max(directions, int(layout["link_direction"].max()) + 1) steps = np.array(_STEPS[:directions], np.int64) offsets = (steps @ np.array([1, nx, nx * ny])).astype(np.int32).view(np.uint32) link_table = np.column_stack( [layout["link_direction"].astype(np.uint32), _words(layout["link_weight"])] ) probes = np.column_stack( [layout["probe_cells"].astype(np.uint32), _words(layout["probe_weights"])] ) parts = { "types": types.view(np.uint32), "special_at": specials.reshape(-1), "state_at": _words(states.reshape(-1)), "layer_at": layout["layer_cells"].astype(np.uint32), "coefficient_at": _words(np.concatenate(coefficients)) if coefficients else np.zeros(0, np.uint32), "probe_at": layout["probe_start"].astype(np.uint32), "probe_cells_at": probes.reshape(-1), "link_at": link_table.reshape(-1), "offset_at": offsets, "scale_at": _words(layout["scale"]), "layer_scale_at": _words(layout["layer_scale"]), } offsets, at = {}, 0 for name, words in parts.items(): offsets[name] = at at += len(words) if at >= 2**32: raise ValueError("the wave grid is too large for the GPU's 32-bit indices") return np.concatenate(list(parts.values())), offsets
[docs] class GpuWaveSolver: """Steps the grid of ``solver`` (a fresh or reset :class:`acoustic_spaces._native.WaveSolver`) on the GPU: :meth:`run` does what the solver's ``run`` does, from the GPU's own state.""" def __init__(self, solver) -> None: wgpu = _wgpu() self._device = device = _device() layout = solver.layout() nx, ny, nz = (int(v) for v in layout["shape"]) n = nx * ny * nz table, offsets = _tables(layout) self._probes = len(layout["probe_start"]) - 1 branches = len(layout["state_branch"]) layers = len(layout["layer_cells"]) weights = layout["weights"] grid = np.zeros(28, np.uint32) grid[:22] = [ n, nx, nx * ny, len(layout["special"]), layers, self._probes, nx, ny, offsets["special_at"], offsets["state_at"], offsets["layer_at"], offsets["coefficient_at"], offsets["probe_at"], offsets["probe_cells_at"], branches, 2 * branches, offsets["link_at"], offsets["offset_at"], int(layout["stencil"][0]) == 19, int(layout["scaled"][0]), offsets["scale_at"], offsets["layer_scale_at"], ] diagonal = weights[6] if len(weights) > 6 else 0.0 grid[22:26] = _words( np.array([weights[0], diagonal, layout["centre"][0], layout["total"][0]]) ) self._cells = n threads = n + len(layout["special"]) + layers + self._probes groups = -(-threads // _GROUP) self._groups = (min(groups, _MAX_GROUPS), -(-groups // _MAX_GROUPS)) limit = device.limits["max-storage-buffer-binding-size"] # The branches' and the matched layer's state: round an open grid, the largest. state = 4 * max(1, 2 * branches + 9 * layers) largest = max(4 * n, table.nbytes, state) if largest > limit: raise ValueError( f"the wave grid needs GPU buffers of {largest / 2**20:,.0f} MiB, and this GPU " f"binds at most {limit / 2**20:,.0f} MiB: lower max_band_hz or " "points_per_wavelength, or run the wave solver on the CPU" ) usage = wgpu.BufferUsage storage = usage.STORAGE | usage.COPY_DST self._grid = device.create_buffer_with_data(data=grid, usage=usage.UNIFORM) self._table = device.create_buffer_with_data(data=table, usage=usage.STORAGE) self._fields = [device.create_buffer(size=4 * n, usage=storage) for _ in range(2)] self._state = device.create_buffer(size=state, usage=storage) self._limit = limit self._stride = max(16, device.limits["min-uniform-buffer-offset-alignment"]) self._steps = device.create_buffer( size=self._stride * _BATCH, usage=usage.UNIFORM | usage.COPY_DST ) def entry(binding, kind, dynamic=False): return { "binding": binding, "visibility": wgpu.ShaderStage.COMPUTE, "buffer": {"type": kind, "has_dynamic_offset": dynamic}, } kinds = wgpu.BufferBindingType self._layout = device.create_bind_group_layout( entries=[ entry(0, kinds.uniform), entry(1, kinds.uniform, dynamic=True), entry(2, kinds.storage), entry(3, kinds.read_only_storage), entry(4, kinds.read_only_storage), entry(5, kinds.storage), entry(6, kinds.storage), ] ) self._pipeline = device.create_compute_pipeline( layout=device.create_pipeline_layout(bind_group_layouts=[self._layout]), compute={"module": device.create_shader_module(code=_SHADER), "entry_point": "main"}, ) self._done = 0 # steps run so far: their parity says which field is which @property def probes(self) -> int: return self._probes
[docs] def run(self, signal: np.ndarray) -> np.ndarray: """Advances one step per sample of ``signal`` (added at the source) and returns the pressure at every probe before each step (probes, steps).""" signal = np.ascontiguousarray(signal, dtype=np.float32).reshape(-1) steps = len(signal) recorded = np.empty((self._probes, steps)) # The probes' pressures go to one buffer, so as many steps at a time as it binds. most = max(1, self._limit // (4 * max(1, self._probes))) for begin in range(0, steps, most): end = min(begin + most, steps) recorded[:, begin:end] = self._run(signal[begin:end]) return recorded
def _run(self, signal: np.ndarray) -> np.ndarray: """:meth:`run` for as many steps as one buffer of the probes' pressures binds.""" wgpu = _wgpu() device, queue = self._device, self._device.queue steps = len(signal) size = 4 * max(1, steps * self._probes) out = device.create_buffer( size=size, usage=wgpu.BufferUsage.STORAGE | wgpu.BufferUsage.COPY_SRC ) def bind(next_field, current_field): buffers = [ self._grid, self._steps, next_field, current_field, self._table, self._state, out, ] entries = [] for binding, buffer in enumerate(buffers): resource = {"buffer": buffer, "offset": 0, "size": buffer.size} if binding == 1: resource["size"] = 16 entries.append({"binding": binding, "resource": resource}) return device.create_bind_group(layout=self._layout, entries=entries) first, second = self._fields groups = (bind(first, second), bind(second, first)) words = self._stride // 4 # The steps go in submissions of bounded work: a GPU's watchdog resets it when # one runs too long, and every step after is lost. per_submit = max(1, min(_BATCH, _SUBMIT_CELL_STEPS // self._cells)) for begin in range(0, steps, _BATCH): count = min(_BATCH, steps - begin) index = np.arange(begin, begin + count, dtype=np.uint32) entries = np.zeros((count, words), np.uint32) entries[:, 0] = index entries[:, 1] = (self._done + index) & 1 entries[:, 2] = _words(signal[begin : begin + count]) queue.write_buffer(self._steps, 0, entries) for start in range(0, count, per_submit): encoder = device.create_command_encoder() compute = encoder.begin_compute_pass() compute.set_pipeline(self._pipeline) for k in range(start, min(start + per_submit, count)): compute.set_bind_group(0, groups[entries[k, 1]], [k * self._stride]) compute.dispatch_workgroups(*self._groups) compute.end() queue.submit([encoder.finish()]) self._done += steps recorded = np.frombuffer(queue.read_buffer(out), np.float32)[: steps * self._probes] return recorded.reshape(steps, self._probes).T
__all__ = ["Device", "GpuWaveSolver", "gpu_name", "hardware_gpu", "use_gpu"]