Source code for acoustic_spaces.engine.ray_device

"""Where the late stage traces its rays: on the CPU, on a GPU, or on both at once.

``simulation.late.device`` picks it:

- ``cpu`` (the default): the compiled core, on ``simulation.performance.threads``.
- ``gpu``: :mod:`acoustic_spaces.engine.gpu_tracer`, through WebGPU (the ``gpu`` extra).
- ``both``: the two share the rays. Each takes the next share of them as soon as it is
  done with the last, so the faster one traces more.
- ``auto``: whichever of the three is fastest on this computer for the run's response
  length. It takes the choice ``acoustic-spaces tune`` kept for that length (see
  :mod:`acoustic_spaces.engine.tuning`); without one, a short trial traces a few
  thousand rays on the scene's own model, for the run's own length, on the CPU and on
  the GPU and keeps the fastest for that range of lengths. It takes the CPU, the safe
  choice, when wgpu finds no GPU or only a software one, or when neither the GPU nor
  both together would be clearly faster. With the trial switched off
  (:func:`set_trial`, ``--no-device-trial``), ``auto`` takes the choice kept for the
  nearest length, or the CPU when there is none.

What only the CPU traces (sound through partitions and openings, a source or a listener
too near a surface or the line where two meet for the GPU's rays, vegetation of more
media than the GPU keeps) runs there, whatever the setting, and so does a run the GPU
declines once it has it (one whose results its buffers cannot hold, or a ray through
more volumes of vegetation at once than its tables hold): the plan :func:`trace` returns
says so. Outdoors the GPU bends the rays in the atmosphere and takes them through
vegetation as the CPU does.

The two agree statistically, not ray for ray (the GPU works in single precision and
draws its own random numbers). With ``cpu`` a run gives the same result every time,
and with ``gpu`` too until the weight window fills a family of copies
(``max_family``): which copies split then depends on the order the GPU's threads come
in. With ``both`` which rays each one traces depends on how fast each goes. Results
then vary from run to run within the noise of the ray count.
"""

from __future__ import annotations

import math
import sys
import threading
import time
from dataclasses import dataclass
from typing import Literal

import numpy as np

from acoustic_spaces.engine import gpu, run_size, tuning

#: The settings of ``simulation.late.device``.
Device = Literal["cpu", "gpu", "both", "auto"]
DEVICES = ("cpu", "gpu", "both", "auto")
#: The command-line switch (``acoustic-spaces simulate`` and the editor) for set_trial.
TRIAL_FLAG = "--no-device-trial"
#: The trial's rays (traced for the run's own response length).
TRIAL_RAYS = 8192
#: How much faster the GPU, or both together, must be in the trial for auto to leave
#: the CPU; and how much the CPU must add to the GPU for auto to share the rays.
MARGIN = 1.2
CPU_SHARE = 1.1
#: Parts of the rays each one takes at a time when they share them: about this many
#: per device (fewer and larger for the GPU, which works best on many rays at once).
CPU_PARTS = 12
GPU_PARTS = 4
# The results of trace_stochastic that carry energy, which a part traced on the CPU
# scales to the whole run: energy, directional, moments and ray_energy.
_SCALED = (0, 1, 2, 4)

_trial = True
_lock = threading.Lock()
#: Trial results of this session: per model, band count and range of response lengths,
#: the CPU's and the GPU's rays per second.
_rates: dict[tuple, tuple[float, float]] = {}


[docs] def set_trial(enabled: bool) -> None: """Switch ``auto``'s trial on or off for this session (off: the saved choice).""" global _trial _trial = bool(enabled)
def trial_enabled() -> bool: return _trial
[docs] @dataclass(frozen=True) class Plan: """Where rays go: ``device`` is cpu, gpu or both; ``cpu_rate`` and ``gpu_rate`` (rays per second, from the trial; 1 for unknown) share them; ``reason`` says why, when it differs from the setting.""" device: str cpu_rate: float = 1.0 gpu_rate: float = 1.0 reason: str = ""
def _unsupported(values: dict) -> str: """Why only the CPU can trace this run wherever its source and listeners are, or '' (:func:`_clear` looks at where they are).""" from acoustic_spaces.engine.gpu_tracer import MAX_MEDIA, outdoors_declined, passes_sound upright = values.get("plant_upright") if values.get("plants") is not None and upright is not None and len(upright) > MAX_MEDIA: return f"vegetation of more than {MAX_MEDIA} media is traced on the CPU" atmosphere = values.get("atmosphere") bending = atmosphere is not None and len(atmosphere) > 0 declined = outdoors_declined(bending, values.get("plants") is not None) if declined: return declined rooms, source_room = values.get("face_room", ()), values.get("source_room", -1) if passes_sound(values["transmission"], rooms, source_room): return "sound through partitions and openings is traced on the CPU" return "" def _clear(plan: Plan, values: dict) -> Plan: """``plan``, or the CPU with the reason where the plan names the GPU and the run's source or one of its listeners lies too near a surface, or the line where two meet, for the GPU's rays (``gpu_tracer.too_near``).""" if plan.device == "cpu": return plan from acoustic_spaces.engine.gpu_tracer import too_near near = too_near(values["bvh"], values["source"], values["receivers"], values["receiver_radius"]) return Plan("cpu", reason=near) if near else plan def _check_gpu(setting: str) -> None: """For a device setting that names the GPU: raises ValueError without one.""" if gpu._adapter() is not None: return try: import wgpu # noqa: F401 except ImportError: raise ValueError( f"simulation.late.device is {setting}, which needs wgpu: pip install " '"acoustic-spaces[gpu]"' ) from None raise ValueError( f"simulation.late.device is {setting}, but wgpu finds no GPU: install a Vulkan, " "Metal or Direct3D 12 driver, or set it to cpu or auto" ) def _cpu_threads(values: dict) -> int: return run_size.worker_threads(int(values["threads"]))
[docs] def trial(values: dict) -> tuple[float, float]: """Rays per second on the CPU and on the GPU for a run like ``values`` (the arguments of ``_native.trace_stochastic``): a few thousand rays traced on each, past the run's own random streams.""" from acoustic_spaces import _native from acoustic_spaces.engine import gpu_tracer short = values | { "rays": TRIAL_RAYS, "first_ray": 1 << 40, "split_target": np.zeros(0), } try: # Compile the shader and start the GPU outside the timing. gpu_tracer.trace_stochastic(**(short | {"rays": 64, "max_time": 0.01}), keep=True) started = time.perf_counter() gpu_tracer.trace_stochastic(**short, keep=True) on_gpu = time.perf_counter() - started finally: gpu_tracer.release() # the run itself may go to the CPU started = time.perf_counter() _native.trace_stochastic(**short) on_cpu = time.perf_counter() - started return TRIAL_RAYS / max(on_cpu, 1e-9), TRIAL_RAYS / max(on_gpu, 1e-9)
def _decide(cpu_rate: float, gpu_rate: float, threads: int) -> str: """The fastest of cpu, gpu and both by the trial's speeds, the CPU on a close call. Sharing leaves one CPU thread to keep the GPU busy.""" both = cpu_rate * (threads - 1) / threads + gpu_rate if threads > 1 else gpu_rate if both >= MARGIN * cpu_rate and both >= CPU_SHARE * gpu_rate: return "both" if gpu_rate >= MARGIN * cpu_rate: return "gpu" return "cpu"
[docs] def choose(setting: str | Plan, values: dict) -> Plan: """Where to trace a run with the arguments ``values`` of ``_native.trace_stochastic`` for the device ``setting``, or as the ``Plan`` given (as ``acoustic-spaces tune`` times each).""" if isinstance(setting, Plan): if setting.device != "cpu": _check_gpu(setting.device) reason = _unsupported(values) return Plan("cpu", reason=reason) if reason else _clear(setting, values) if setting not in DEVICES: choices = ", ".join(DEVICES) raise ValueError(f"the late stage's device must be one of {choices}, not {setting!r}") if setting == "cpu": return Plan("cpu") if setting in ("gpu", "both"): _check_gpu(setting) reason = _unsupported(values) if reason: return Plan("cpu", reason=reason) if setting == "gpu": return _clear(Plan("gpu"), values) length = float(values["max_time"]) if setting == "both": # Shares by the speeds of a trial or of tune, if there was one; else even ones. kept = tuning.late_choice(length) or {"cpu_rate": 1.0, "gpu_rate": 1.0} rates = _rates.get(_key(values), (kept["cpu_rate"], kept["gpu_rate"])) return _clear(Plan("both", *rates), values) # auto if not gpu.hardware_gpu(): return Plan("cpu", reason="no hardware GPU") tuned = tuning.late_entry(length) if tuned is not None and tuned.get("from") == "tune": return _clear(_kept(tuned), values) if not _trial: kept = tuning.late_choice(length) if kept is None: return Plan("cpu", reason="no trial or tune on this computer yet") return _clear(_kept(kept), values) from acoustic_spaces.engine import gpu_tracer key = _key(values) with _lock: if key not in _rates: near = _clear(Plan("gpu"), values) if near.device == "cpu": return near # no trial of a run the GPU would not trace try: _rates[key] = trial(values) except gpu_tracer.Unsupported as declined: return Plan("cpu", reason=str(declined)) cpu_rate, gpu_rate = _rates[key] device = _decide(cpu_rate, gpu_rate, _cpu_threads(values)) tuning.keep_late( length, {"device": device, "cpu_rate": cpu_rate, "gpu_rate": gpu_rate, "from": "trial"}, ) return _clear(Plan(device, cpu_rate, gpu_rate, "the trial"), values)
def _kept(choice: dict) -> Plan: """The plan of a kept choice.""" reason = "acoustic-spaces tune" if choice.get("from") == "tune" else "the saved choice" return Plan(choice["device"], choice["cpu_rate"], choice["gpu_rate"], reason) def _key(values: dict) -> tuple: """The model, band count and range of response lengths of a run: one trial for each in a session (so not again for every run of the same room in the editor).""" bvh = values["bvh"] return ( int(bvh.face_count), float(bvh.scale), len(np.asarray(values["air"])), tuning.length_key(values["max_time"]), )
[docs] def trace(plan: Plan, values: dict, keep: bool = False) -> tuple[tuple, Plan]: """``_native.trace_stochastic(**values)`` where ``plan`` says, and the plan it followed: the CPU, with the GPU's reason, where the GPU declined the rays. With ``keep``, the GPU keeps its rays in flight for the next call, until :func:`release`.""" from acoustic_spaces import _native from acoustic_spaces.engine import gpu_tracer if plan.device == "gpu": try: return gpu_tracer.trace_stochastic(**values, keep=keep), plan except gpu_tracer.Unsupported as declined: gpu_tracer.release() return _native.trace_stochastic(**values), Plan("cpu", reason=str(declined)) if plan.device == "both": return _shared(plan, values, keep) return _native.trace_stochastic(**values), plan
def _part_sizes(plan: Plan, count: int, threads: int) -> dict[str, int]: """The rays the CPU and the GPU each take at a time of a call of ``count`` rays they share: about ``CPU_PARTS`` and ``GPU_PARTS`` parts of their share of it at ``plan``'s rates (the CPU's on all its threads but the one that keeps the GPU busy), at least 256 and 4,096 rays, but no more than that share. So the CPU takes its share of a call of few rays too, as the late part calls the tracer once for each batch of rays (``late.batches``).""" cpu_rate = plan.cpu_rate * (threads - 1) / threads if threads > 1 else plan.cpu_rate total = cpu_rate + plan.gpu_rate on_cpu = math.ceil(count * cpu_rate / total) on_gpu = math.ceil(count * plan.gpu_rate / total) return { "cpu": max(1, min(on_cpu, max(256, math.ceil(on_cpu / CPU_PARTS)))), "gpu": max(1, min(on_gpu, max(4096, math.ceil(on_gpu / GPU_PARTS)))), }
[docs] def release() -> None: """Lets go of what the GPU keeps from one of a run's calls to the next, as the run ends (nothing where the GPU's tracer was never loaded).""" tracer = sys.modules.get("acoustic_spaces.engine.gpu_tracer") if tracer is not None: tracer.release()
def _shared(plan: Plan, values: dict, keep: bool = False) -> tuple[tuple, Plan]: """The rays of ``values`` shared between the CPU and the GPU: each takes the next part as it finishes the one before. A part traced on the CPU carries its own share of the energy, so its results (and its expected ray energies) are scaled to the whole run's. Where the GPU declines a part, it hands that part to the CPU and stops, so the CPU traces it and the rest, one tracer at a time.""" from acoustic_spaces import _native from acoustic_spaces.engine import gpu_tracer count, first = int(values["rays"]), int(values["first_ray"]) target = np.asarray(values["split_target"], float) threads = _cpu_threads(values) sizes = _part_sizes(plan, count, threads) cursor = [0] lock = threading.Lock() # The parts' results summed as each comes in (each scaled to the whole run), so the # run holds the sums and the parts being traced, not every part. totals: list = [] summing = threading.Lock() errors: list[BaseException] = [] on_gpu = threading.Event() declined: list[str] = [] # Parts the GPU declined, for the CPU to trace. left: list[tuple[int, int]] = [] def take(device: str) -> tuple[int, int]: with lock: if device == "cpu" and left: return left.pop() lo = cursor[0] cursor[0] = hi = min(count, lo + sizes[device]) return lo, hi def add(scale: float, part: tuple) -> None: part = list(part) if scale != 1.0: for i in _SCALED: part[i] *= scale with summing: if not totals: totals.extend(part) return for i, value in enumerate(part): totals[i] += value def on_cpu(lo: int, hi: int, workers: int) -> None: m = hi - lo part = _native.trace_stochastic( **values | { "rays": m, "first_ray": first + lo, "split_target": target * (count / m), "threads": workers, } ) add(m / count, part) def work(device: str) -> None: try: while not errors: lo, hi = take(device) if lo >= hi: return if device == "cpu": # One thread keeps the GPU busy, until it declines. on_cpu(lo, hi, threads if declined else max(1, threads - 1)) continue try: part = gpu_tracer.trace_stochastic( **values | {"rays": hi - lo, "first_ray": first + lo}, total=count, keep=keep, ) except gpu_tracer.Unsupported as reason: declined.append(str(reason)) with lock: left.append((lo, hi)) gpu_tracer.release() return add(1.0, part) on_gpu.set() except BaseException as error: # noqa: BLE001 - handed to the caller below errors.append(error) helper = threading.Thread(target=work, args=("gpu",), name="acoustic-spaces-gpu") helper.start() work("cpu") helper.join() if errors: raise errors[0] # What the GPU declined after the CPU had run out of parts. for lo, hi in left: on_cpu(lo, hi, threads) followed = Plan("cpu", reason=declined[0]) if declined and not on_gpu.is_set() else plan energy, directional, moments, escaped, ray_energy, reflections, traced = totals return ( energy, directional, moments, int(escaped), ray_energy, reflections, int(traced), ), followed __all__ = [ "DEVICES", "TRIAL_FLAG", "Device", "Plan", "choose", "release", "set_trial", "trace", "trial", "trial_enabled", ]