"""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",
]