"""Wave-based simulation of the lowest octave bands (or their third-octave bands).
Rays and image sources treat sound as rays, which holds while the room is large next
to the wavelength. At low frequencies it is not: small rooms ring at their modes, and
sound bends round everything. The wave solver computes the sound field itself, with
the finite-difference time-domain method (FDTD) on a cubic grid over the room, and its
octave bands replace the ray-traced ones.
- One grid covers every octave band up to ``max_band_hz``, with
``points_per_wavelength`` cells per wavelength at the top of that band's crossover.
In a simulation in third-octave bands, those are the third octaves of these octave
bands, and the grid is set by the top of the highest of them.
Each octave higher costs about 16 times as much (cells 8 times smaller, steps twice
as many). All bands share the grid, so a mode near a crossover is the same mode on
both sides of it.
- Waves on the grid travel slower the shorter they are. ``scheme`` picks the stencil:
the interpolated isotropic one (19 points, :data:`ISOTROPIC_COURANT`) is 0.67 % slow
at 8 cells per wavelength, within 0.03 % the same in every direction; the standard
one (7 points, :data:`COURANT`) up to 1.7 %, along the grid's axes. ``auto`` takes the
isotropic one but round an open model, where only the standard one has the matched
layer. Along the axes both are slowest (:func:`slow_by`); the run's details give how
slow the top of the highest band is there (``wave_slow_percent``).
- The surfaces absorb as their materials do in each band: each material becomes a
locally reacting surface whose admittance changes with frequency, fitted so that its
random-incidence absorption matches the material's in every wave band
(:mod:`acoustic_spaces.engine.impedance`). One run covers all the wave bands.
- Cells are air when the source reaches them without crossing a surface, so closed
rooms, open models and thin screens all work. Round an open model, whose air reaches
the edge of the grid, the grid grows by a perfectly matched layer of
:data:`LAYER_CELLS` cells that takes in the sound leaving it, and leaves room
(:data:`LAYER_ROOM`) for sound that runs along it, on the sides where no surface of
the model lies between that sound and the layer (:func:`_open_sides`). Openings are not
surfaces here: the air flows through them. Surfaces that let only part of the sound
through are not modelled, so a model with any stops the wave solver with an error.
- ``walls`` says where the grid's walls lie: ``"cell_faces"``, each surface on the cell
faces nearest it, or ``"fitted"``, where the model has it, cut exactly through the
cells. Fitted walls take the standard stencil (``auto`` takes it for them) and still
air with one speed of sound: they are refused with the isotropic stencil, outdoors and
in moving air.
- At these frequencies the source radiates the same way in all directions. The
listener records the pressure and, from its gradient, the direction the sound comes
from (first-order Ambisonics), so spatial outputs keep the low end's direction.
- The bands join the ray-traced ones through the zero-phase crossovers the impulse
response synthesis uses, which sum to one; the lowest starts at :data:`LOW_EDGE_HZ`
(22 Hz) instead of 0 Hz. Their energies, for the room parameters, are counted
through the octave filters of the analysis of measured responses.
- Outdoors, in wind and temperature that change with height
(:class:`~acoustic_spaces.scene.Atmosphere`), the speed of sound changes from cell to
cell: the still air's at the cell's height above the ground, plus the wind's
component along the horizontal from the source, the effective speed of sound the rays
and the parabolic equation take (:mod:`acoustic_spaces.engine.refraction`). The grid
is then fine enough for the slowest sound and steps in time for the fastest, so it
costs a little more than in still air. Sound that turns back towards the source, off
a building, keeps the speed of sound of sound going away from it.
- With ``wind="moving"`` the air moves instead: each cell keeps the still air's speed
of sound, and before each step both of the leapfrog's pressure levels are carried
along with the wind, dq/dt = -v . grad q (the strong-stability-preserving
Runge-Kutta method of third order); the still air's step follows, its boundaries, the
matched layer and the source fixed to the ground. In the air's own frame that is the
still air's step exactly, so a uniform wind gives the convected wave equation:
downwind sound at c + v, upwind at c - v whichever way it turned. Where the wind
changes, the term of the linearised Euler equations that the wind's shear puts on the
air's velocity is left out, about ``|dv/dz| / omega`` of the rest. That scheme keeps
the sound's energy only where no wind crosses a surface of the model and no cell
gains or loses air, so the atmosphere's wind is first made to flow round the model's
solids: on the faces between the cells, the wind of least change from the given one
(each face's change weighed by one over the given speed there) that crosses no
surface and leaves every cell as much as it enters it. A dead end, such as a room
with one opening, then holds nearly still air whatever the wind's profile. It is a
flow without wakes or eddies behind the solids, and at a sharp edge it speeds up, the
more the finer the grid; the run says how fast it gets through a face between two
cells (``wave_wind_fastest_m_s``), which must stay under half a cell a step. The
carrying is of fourth order where the wind is the same along a row of cells and of
second order where it changes; over open, flat ground, where the given wind already
crosses nothing, it is carried as given, by fourth-order central differences. Over
open ground it takes four to five times as long as the effective speed of sound's
run; round solids its steps take about eight times as long, after the solve of the
wind (see ``validation/wave_wind.py``). It runs on the CPU (asked for the GPU, it
says so and stays there). The matched layer's air is still: where the wind crosses
its border, each cell's own sound is carried out and silence in, which takes energy
and adds none, and a wave that leaves the moving air for the layer comes back by
about half the wind's Mach number (see the notes of ``fdtd.hpp``). The run is watched
all the same: once the source's pulse has ended, the pressure squared over the
grid's air, averaged over pieces of ``WATCH_S``, may not rise to ``WATCH_RISE`` times
its lowest so far (a ``ValueError``).
- The grid is laid out on the CPU and stepped there, or with ``device`` on a GPU,
through WebGPU (:mod:`acoustic_spaces.engine.gpu`); the two agree to rounding, in
wind and temperature too (with the effective speed of sound).
The levels follow the ray tracer's convention: in free field, the direct sound at r
metres is an impulse of height 1 / r.
"""
from __future__ import annotations
import dataclasses
import math
from collections.abc import Callable, Sequence
from dataclasses import dataclass, field
from typing import Literal
import numpy as np
from acoustic_spaces import products, synthesis
from acoustic_spaces.engine.gpu import Device, GpuWaveSolver, gpu_name, use_gpu
from acoustic_spaces.engine.impedance import (
MAX_ABSORPTION,
Admittance,
absorption_of_impedance,
admittance,
fit_admittance,
fit_impedance,
)
from acoustic_spaces.materials.bands import BANDS_PER_OCTAVE, OCTAVE_BANDS_HZ, band_centres
#: Courant number of the 7-point (standard rectilinear) stencil: its stable limit.
COURANT = 1.0 / math.sqrt(3.0)
#: Courant number of the 19-point (interpolated isotropic) stencil: its stable limit.
ISOTROPIC_COURANT = math.sqrt(0.75)
#: Which stencil steps the grid (see :func:`wave_responses`).
Scheme = Literal["auto", "standard", "isotropic"]
#: How the wave solver takes the wind (see :func:`wave_responses`).
WindModel = Literal["effective", "moving"]
#: Where the grid's walls lie (see :func:`wave_responses`).
Walls = Literal["cell_faces", "fitted"]
#: The stencils' points, and their Courant numbers, by scheme.
STENCILS = {"standard": (7, COURANT), "isotropic": (19, ISOTROPIC_COURANT)}
#: Each stencil's link weights, by its points: of an axial link and of an edge link (the
#: Courant number squared shared out over the links, as the update takes them).
LINK_WEIGHTS = {7: (1.0 / 3.0, 0.0), 19: (0.25, 0.125)}
#: Grids with more cells than this are refused (about 20 bytes each).
MAX_CELLS = 40_000_000
#: The highest bands the solver may compute (``simulation.wave.max_band_hz``).
WAVE_BANDS_HZ = OCTAVE_BANDS_HZ[:4]
#: The source's high-pass, applied twice: once so that the air the source pushes into
#: the room stops flowing, twice so that as much flows out again and a closed room's
#: pressure comes back to rest. Its length in seconds; twice, it is flat within 0.2 dB
#: above 20 Hz.
HIGH_PASS_S = 0.12
#: How much further than a response's end a simulation steps the solver (s), by the
#: resolution of its bands. The bands' filters spread each arrival both ways in time, so
#: they read the last of a response from the run after it too: a run that stops at the
#: response's end is silent there, and the room is not.
PAST_END_S = {"octave": 0.2, "third_octave": 0.4}
#: Cells of the matched layer round an open model, and its damping at the grid's edge
#: (the damping rate times half a time step). Sound leaving the model comes back from
#: it 72 to 74 dB down; from the grid's edge alone, 7 to 14 dB down (docs/validation.md,
#: Open models).
LAYER_CELLS = 8
LAYER_DAMPING = 0.5
#: Round an open model, the grid reaches past the source and the listeners, on each
#: side, by at least this share of the farthest a listener lies from the source along
#: that side (across its axis), before its margin and its matched layer; under an
#: outdoor ground, not at all. Sound that runs along the layer meets it near grazing,
#: where the layer sends much of it back: in one-off checks over a rigid plate, the
#: source and the listener 1.5 m above it and the layer a few cells above them (20 cm
#: cells), the level read 0.26 dB below the exact one at 125 Hz 20 m away, and 0.50 and
#: 1.71 dB below it at 63 and 125 Hz 40 m away. With this room it is within 0.03 dB of
#: the exact one, 20 to 160 m away (docs/validation.md, Open models). A side that the
#: model's own surfaces close off from the source and the listeners gets none
#: (:func:`_open_sides`).
LAYER_ROOM = 0.15
#: The wave solver's part of a response starts here (Hz), with the synthesis's
#: crossover shape round it: an octave below the 63 Hz band's lower edge, so that band,
#: skirts and all, comes from the wave solver. Further down a closed room's air is
#: squeezed as a whole (the wave solver's source leaves no air in it, so this falls
#: away), and the rays' response stays.
LOW_EDGE_HZ = OCTAVE_BANDS_HZ[0] / (2.0 * math.sqrt(2.0))
#: Length of the source's low-pass (taps; odd), which keeps the grid free of the
#: frequencies it cannot carry, and its cutoff (of the grid's sample rate) with the
#: 7-point stencil; it scales with the stencil's Courant number (0.3 with the 19-point
#: one), so that the top of the highest band lies as far below it with either.
_LOW_PASS_TAPS = 33
_LOW_PASS_CUTOFF = 0.2
#: Runs of more cell updates than this (a few seconds' work) report their progress.
_LONG_RUN = 2e9
#: Moving air is watched for sound that grows (its scheme keeps the sound's energy with
#: the wind that flows round the model's solids; the watch is for what that does not
#: cover). The pressure squared over the grid's air is averaged over pieces of the run
#: at least this long (s); from the end of the source's pulse on, a piece more than
#: WATCH_RISE times the lowest before it, and more than WATCH_FLOOR of the largest
#: (rounding's own level lies far below that), stops the run.
WATCH_S = 0.25
WATCH_RISE = 2.0
WATCH_FLOOR = 1e-6
[docs]
def band_top(band: int, total: int = len(OCTAVE_BANDS_HZ)) -> float:
"""Highest frequency band ``band`` of the ``total`` (8 octave or 24 third-octave)
bands has (Hz): the top of its upper crossover."""
edge = synthesis.crossover_frequencies(total)[band]
return edge * 2.0 ** (synthesis.crossover_width(total) / 2)
[docs]
def wave_gains(
n_fft: int, sample_rate: float, bands: int, total: int = len(OCTAVE_BANDS_HZ)
) -> np.ndarray:
"""Zero-phase gains (bands, n_fft // 2 + 1) of the lowest ``bands`` of the ``total``
(8 octave or 24 third-octave) bands as the wave solver covers them: the synthesis's
band gains, the lowest one starting at :data:`LOW_EDGE_HZ`."""
gains = synthesis.band_gains(n_fft, sample_rate, total)[:bands]
f = np.fft.rfftfreq(n_fft, 1.0 / sample_rate)
width = synthesis.CROSSOVER_WIDTH
x = (np.log2(np.maximum(f, 1e-6)) - math.log2(LOW_EDGE_HZ) + width / 2) / width
gains[0] *= np.sin(0.5 * np.pi * np.clip(x, 0.0, 1.0)) ** 2
return gains
def _filter(x: np.ndarray, gain: np.ndarray, n_fft: int) -> np.ndarray:
"""x (n, ...) through a zero-phase gain on the rFFT grid of n_fft."""
shape = (-1,) + (1,) * (x.ndim - 1)
spectrum = np.fft.rfft(x, n_fft, axis=0) * gain.reshape(shape)
return np.fft.irfft(spectrum, n_fft, axis=0)[: len(x)]
[docs]
def grid_phase(theta, stencil: int, ratio: float = 1.0) -> np.ndarray:
"""The phase w T a wave turns through in a time step on the ``stencil``-point grid,
from the phase it turns through across a cell along each axis, ``theta`` (..., 3),
k h: the stencil's dispersion relation, 2 - 2 cos(w T) = ratio^2 sum over the links
of g_k (1 - cos(k . d_k)). ``ratio`` is the speed of sound over the one the grid's
time step is set by (in wind and temperature, below 1 in all but the fastest air)."""
axial, edge = LINK_WEIGHTS[stencil]
cos = np.cos(np.asarray(theta, dtype=float))
total = 2 * axial * (1 - cos).sum(axis=-1)
for a, b in ((0, 1), (0, 2), (1, 2)):
total += 4 * edge * (1 - cos[..., a] * cos[..., b])
return np.arccos(1 - ratio**2 * total / 2)
[docs]
def slow_by(stencil: int, per_wavelength: float, ratio: float = 1.0) -> float:
"""How much slower than it should (a fraction) a wave of ``per_wavelength`` cells per
wavelength travels on the ``stencil``-point grid along its axes, the way it is
slowest with either stencil; ``ratio`` as in :func:`grid_phase` (below 1, slower
still). The 19-point stencil at 8 cells per wavelength: 0.67 %, at 5: 1.85 %; the
7-point one 1.74 % and 4.56 %."""
courant = dict(STENCILS.values())[stencil]
theta = 2.0 * math.pi / per_wavelength
turned = float(grid_phase([theta, 0.0, 0.0], stencil, ratio))
return 1.0 - turned / (ratio * courant * theta)
[docs]
@dataclass(frozen=True)
class BandGrid:
"""The grid of one band's run."""
band: int
#: Cell size (m).
cell: float
#: Sample rate of the run (Hz): the output rate over or times a whole number.
rate: float
[docs]
def band_grid(
band: int,
sample_rate: float,
speed_of_sound: float,
points_per_wavelength: float = 8.0,
total: int = len(OCTAVE_BANDS_HZ),
courant: float = COURANT,
) -> BandGrid:
"""The coarsest grid with ``points_per_wavelength`` cells per wavelength at the top of
band ``band`` (of ``total``, 8 octave or 24 third-octave bands) whose time step is a
whole number of the output's sample periods, or one of them over a whole number
where the grid needs more steps per second than the output has samples. ``courant``
is the stencil's Courant number."""
cell = speed_of_sound / (points_per_wavelength * band_top(band, total))
rate = speed_of_sound / (courant * cell) # one step crosses `courant` cells
if rate <= sample_rate:
rate = sample_rate / math.floor(sample_rate / rate)
else:
rate = sample_rate * math.ceil(rate / sample_rate)
return BandGrid(band, speed_of_sound / (courant * rate), rate)
def _cutoff(courant: float) -> float:
"""The source's low-pass cutoff (of the grid's sample rate) on the grid of the
stencil whose Courant number is ``courant``."""
return _LOW_PASS_CUTOFF * courant / COURANT
[docs]
def source_signal(
rate: float, cell: float, courant: float = COURANT, speed: float = 1.0, *, level: bool = True
) -> tuple[np.ndarray, int]:
"""What the source adds to the grid on each step, and its delay in steps.
An impulse, low-passed (so the grid carries no frequencies it cannot) and
high-passed twice (so it leaves no air in the room), scaled so that in free field the
pressure at r metres is that impulse over r. ``courant`` is the stencil's Courant
number, which says which stencil it is for and sets the low-pass's cutoff
(:func:`_cutoff`); ``speed`` the speed of sound at the source over the grid's (1
where it is the same everywhere).
On the 19-point grid a point source's sound comes out louder than what the source
adds, the more the higher the frequency: by 9 / (5 + 4 cos wT) in pressure, w T the
frequency's turn over a time step (the far field of the scheme's own response to one
cell, by stationary phase: 3 / (2 + cos kh) along an axis, kh the turn over a cell
there, which the scheme ties to the frequency by cos kh = 1 - 4 (1 - cos wT) / 3).
That is the gain along the axes and the cube's diagonals; along a face's diagonals
it is up to 0.03 dB more at eight cells per wavelength, and the same within 0.01 dB
over a band: 0.06 and 0.35 dB over the 63 and 125 Hz bands of a grid up to the
125 Hz band. Three taps, 2/9, 5/9 and 2/9, have the inverse gain exactly and are
part of the signal, with a step of delay (where the source's speed of sound is
``speed`` times the grid's, the side taps are over the square of ``speed``, the
middle one what is left of one); ``level=False`` gives the signal without them, the
impulse that the signal with them stands for. The 7-point grid's gain changes with
the direction (twelve cells away, over that 125 Hz band: none along an axis, 0.25 dB
along a face's diagonals and 0.32 to 0.34 dB along the cube's, by the places of the
source and the listener within their cells; validation/wave_solver.py), so no signal
can undo it.
"""
half = _LOW_PASS_TAPS // 2
k = np.arange(-half, half + 1)
cutoff = _cutoff(courant)
low = 2 * cutoff * np.sinc(2 * cutoff * k) * np.blackman(_LOW_PASS_TAPS)
low /= low.sum()
length = max(3, int(round(HIGH_PASS_S * rate)))
window = np.hanning(length + 2)[1:-1]
high = -window / window.sum()
high[0] += 1.0
signal = np.convolve(np.convolve(low, high), high)
delay = half
# (The 19-point stencil, known by its Courant number.)
if level and math.isclose(courant, ISOTROPIC_COURANT, rel_tol=1e-9):
side = 2.0 / (9.0 * speed**2)
signal = np.convolve(signal, [side, 1.0 - 2.0 * side, side])
delay += 1
return 4.0 * math.pi * courant**2 / cell * signal, delay
[docs]
@dataclass
class WaveResponse:
"""The lowest octave bands (or third-octave bands) of one response, from the wave
solver.
``signals`` holds the run at ``rate``: the pressure and the first-order directional
parts (samples, 4), AmbiX W, X, Y and Z in room coordinates, from ``lead_s`` before
emission on. Only the frequencies of the wave bands count.
"""
rate: float
signals: np.ndarray
#: The bands 0 to bands - 1 come from the wave solver.
bands: int
#: Cell size of the grid (m).
cell: float
#: How many bands the whole response has: 8 octave or 24 third-octave bands.
total_bands: int = len(OCTAVE_BANDS_HZ)
#: How long before emission ``signals`` start (s): the source's pulse is centred on
#: emission, so a listener near the source hears it start before then.
lead_s: float = 0.0
#: The energy gain of each wave band from the source's feed, or None for none.
band_gain: np.ndarray | None = None
#: How long after emission the source starts playing (s).
delay_s: float = 0.0
_cache: dict = field(default_factory=dict, init=False, repr=False, compare=False)
[docs]
def fed(self, gain: np.ndarray, delay_s: float) -> WaveResponse:
"""These bands with the energy ``gain`` of each and ``delay_s`` later."""
gain = np.asarray(gain, dtype=float)
total = gain if self.band_gain is None else self.band_gain * gain
return dataclasses.replace(self, band_gain=total, delay_s=self.delay_s + delay_s)
def _amplitudes(self) -> np.ndarray:
return np.ones(self.bands) if self.band_gain is None else np.sqrt(self.band_gain)
def _resampled(self, sample_rate: float, n: int) -> tuple[np.ndarray, int]:
"""The run at ``sample_rate`` (at least before + n, 4), still broadband, and
``before``: how many of its samples come before emission (those of the run that
do). What the run has after the n samples from emission stays, for the bands'
filters."""
from acoustic_spaces.render import resample
key = (float(sample_rate), int(n))
if key not in self._cache:
# Where the run starts, in samples from emission, rounded once, so within half
# a sample of its time at any sample_rate (lead_s need not be a whole number
# of samples at a rate other than the run's: 16 steps at 2000 Hz are 352.8
# samples at 44.1 kHz).
start = int(round((self.delay_s - self.lead_s) * sample_rate))
before = max(0, -start)
x = resample(self.signals, self.rate, sample_rate)
out = np.zeros((before + max(n, start + len(x)), 4))
# Impulse responses scale with the sample period: an impulse of height a at
# one rate is a * rate / sample_rate at another.
out[before + start : before + start + len(x)] = x * (self.rate / sample_rate)
self._cache = {key: (out, before)}
return self._cache[key]
[docs]
def field(self, sample_rate: float, n: int) -> np.ndarray:
"""The first-order sound field (n, 4) of the wave bands together, from emission:
W, X, Y, Z. The bands' filters take the run before emission too, and what they
spread to before emission is left out, as it is of the rays' sound. They take
the run after the n samples as well, where it goes on (:data:`PAST_END_S`)."""
run, before = self._resampled(sample_rate, n)
n_fft = synthesis.fft_size(len(run), sample_rate)
gains = wave_gains(n_fft, sample_rate, self.bands, self.total_bands)
gain = (gains * self._amplitudes()[:, None]).sum(axis=0)
spectrum = np.fft.rfft(run, n_fft, axis=0) * gain[:, None]
return np.fft.irfft(spectrum, n_fft, axis=0)[before : before + n]
[docs]
def high_pass(self, signals: np.ndarray, sample_rate: float, late: bool = False) -> np.ndarray:
"""``signals`` (n, channels) without the frequencies the wave bands cover, which
take them at a gain g: the rays' early paths at 1 - g, as they add to the wave
bands' sound in pressure, or with ``late`` their noise at sqrt(1 - g^2), as it
adds to the wave bands' tail in energy."""
n_fft = synthesis.fft_size(len(signals), sample_rate)
g = wave_gains(n_fft, sample_rate, self.bands, self.total_bands).sum(axis=0)
return _filter(signals, np.sqrt(1.0 - g**2) if late else 1.0 - g, n_fft)
[docs]
def energy(
self,
time_step: float,
slots: int,
axis: np.ndarray | None = None,
exponent: int = 2,
) -> np.ndarray:
"""Energy per band and time slot (bands, slots), as the ray tracer counts it: the
energy of the pressure through each band's filter (those of the analysis of
measured responses, :func:`acoustic_spaces.parameters.band_filter_gains`) over
that filter's share of the spectrum. The filters spread each arrival a
little both ways in time; what they spread to before emission counts in the
first slot.
With ``axis`` (a unit vector in room coordinates), that of a figure of eight
facing it instead, from X, Y and Z: with ``exponent`` 1, the magnitude of its
product with the pressure."""
from acoustic_spaces.parameters import band_filter_gains
out = np.zeros((self.bands, slots))
pad = int(round(synthesis._PAD_S * self.rate))
n_fft = synthesis.fft_size(len(self.signals) + pad, self.rate)
gains = band_filter_gains(n_fft, self.rate, self.total_bands)[: self.bands]
weights = np.full(gains.shape[1], 2.0)
weights[0] = weights[-1] = 1.0
# Each sample's time from emission (whole steps counted first, so that a sample
# on a slot's edge falls in the same slot whatever the lead).
lead = int(round(self.lead_s * self.rate))
time = (np.arange(len(self.signals) + pad) - pad - lead) / self.rate + self.delay_s
slot = np.maximum(time / time_step, 0).astype(np.int64)
amplitude = self._amplitudes()
keep = slot < slots
padded = np.concatenate([np.zeros(pad), self.signals[:, 0]])
if axis is not None:
figure8 = np.concatenate([np.zeros(pad), products.product(self.signals[:, 1:], axis)])
for b, gain in enumerate(gains):
pressure = _filter(padded, gain, n_fft)
share = float((gain**2 * weights).sum() / n_fft)
power = pressure[keep] ** 2
if axis is not None:
side = _filter(figure8, gain, n_fft)[keep]
power = side**2 if exponent == 2 else np.abs(side * pressure[keep])
energy = power * amplitude[b] ** 2 / (synthesis.ENERGY_TO_IR * share)
out[b] = np.bincount(slot[keep], energy, minlength=slots)[:slots]
return out
class _Weather:
"""The effective speed of sound over an outdoor scene's grid, from the source at
``source``: the still air's at each height above the ground (``ground``, its
temperature ``ground_c`` °C), plus the wind's component along the horizontal from
the source (none straight above it). Where the weather changes from place to place
(``zones``, a :class:`~acoustic_spaces.engine.weather.Weather`), each cell takes
the weather it stands over."""
def __init__(self, atmosphere, ground_c: float, ground: float, source: np.ndarray, zones=None):
self.atmosphere = atmosphere
self.ground_c = ground_c
self.ground = ground
self.source = np.asarray(source, dtype=float)
self.wind = atmosphere.to_wind()
self.zones = zones
if zones is not None:
self.weathers = zones.atmosphere.weathers()
self.grounds = zones.atmosphere.ground_temperatures(ground_c)
self.winds = zones.towards # (K, 2)
@classmethod
def of(cls, model, source: np.ndarray) -> _Weather | None:
"""The weather of ``model``'s scene, or None where the speed of sound is the
same everywhere: indoors, or outdoors in still air."""
from acoustic_spaces.engine.weather import Weather
atmosphere = getattr(model.room.scene, "atmosphere", None)
if model.room.outdoor is None or atmosphere is None or atmosphere.still:
return None
zones = Weather.of(model) if atmosphere.zones else None
return cls(
atmosphere, float(model.room.scene.air.temperature_c), model.ground, source, zones
)
def _profiles(self, z: np.ndarray, k: int | None = None) -> tuple[np.ndarray, np.ndarray]:
"""The still air's speed of sound and the wind's speed at heights z (m, in the
room's coordinates), of the atmosphere's own weather or of weather ``k``."""
height = np.asarray(z, dtype=float) - self.ground
if k is None:
still = np.asarray(self.atmosphere.sound_speed(height, self.ground_c), dtype=float)
return still, np.asarray(self.atmosphere.wind_speed(height), dtype=float)
weather = self.weathers[k]
still = np.asarray(weather.sound_speed(height, self.grounds[k]), dtype=float)
return still, np.asarray(weather.wind_speed(height), dtype=float)
def _along(self, x: np.ndarray, y: np.ndarray, wind=None) -> np.ndarray:
"""The cosine between the wind (``wind`` (2,), or the atmosphere's own) and the
horizontal from the source to (x, y)."""
wind = self.wind if wind is None else wind
dx, dy = x - self.source[0], y - self.source[1]
distance = np.hypot(dx, dy)
along = wind[0] * dx + wind[1] * dy
return np.divide(along, distance, out=np.zeros_like(along), where=distance > 0)
def at(self, points: np.ndarray) -> np.ndarray:
"""The speed of sound (m/s) at ``points`` (n, 3)."""
points = np.asarray(points, dtype=float).reshape(-1, 3)
if self.zones is None:
still, wind = self._profiles(points[:, 2])
return still + wind * self._along(points[:, 0], points[:, 1])
out = np.zeros(len(points))
zone = self.zones.zone_at(points[:, :2])
for k in np.unique(zone).tolist():
rows = zone == k
still, wind = self._profiles(points[rows, 2], k)
along = self._along(points[rows, 0], points[rows, 1], self.winds[k])
out[rows] = still + wind * along
return out
def _grid(self, origin: np.ndarray, h: float, shape) -> tuple:
centres = [origin[a] + (np.arange(shape[a]) + 0.5) * h for a in range(3)]
if self.zones is None:
still, wind = self._profiles(centres[2])
along = self._along(centres[0][None, :], centres[1][:, None]) # (ny, nx)
return still, wind, along, None
# Each weather's profiles and cosines, and which holds over each column.
profiles = [self._profiles(centres[2], k) for k in range(len(self.weathers))]
still = np.array([p[0] for p in profiles]) # (K, nz)
wind = np.array([p[1] for p in profiles]) # (K, nz)
along = np.array(
[
self._along(centres[0][None, :], centres[1][:, None], self.winds[k])
for k in range(len(self.weathers))
]
) # (K, ny, nx)
x, y = np.meshgrid(centres[0], centres[1]) # (ny, nx)
zone = self.zones.zone_at(np.column_stack([x.ravel(), y.ravel()])).reshape(x.shape)
return still, wind, along, zone
def extremes(self, origin: np.ndarray, h: float, shape) -> tuple[float, float]:
"""The slowest and the fastest speed of sound over the grid's cells."""
still, wind, along, zone = self._grid(origin, h, shape)
if zone is None:
ends = wind[:, None] * np.array([along.min(), along.max()])[None, :]
return float((still + ends.min(axis=1)).min()), float((still + ends.max(axis=1)).max())
low, high = np.inf, -np.inf
for k in np.unique(zone).tolist():
cosines = along[k][zone == k]
ends = wind[k][:, None] * np.array([cosines.min(), cosines.max()])[None, :]
low = min(low, float((still[k] + ends.min(axis=1)).min()))
high = max(high, float((still[k] + ends.max(axis=1)).max()))
return low, high
def ratios(self, origin: np.ndarray, h: float, shape, speed: float) -> np.ndarray:
"""(nx ny nz,) float32, x fastest: each cell's speed of sound over ``speed``,
the grid's (at most 1)."""
still, wind, along, zone = self._grid(origin, h, shape)
out = np.empty((int(shape[2]), int(shape[1]), int(shape[0])), np.float32)
if zone is None:
for z in range(len(still)): # a layer at a time, to keep the memory down
out[z] = np.minimum((still[z] + wind[z] * along) / speed, 1.0)
return out.reshape(-1)
iy, ix = np.indices(zone.shape)
cosines = along[zone, iy, ix] # (ny, nx) each column's cosine to its own wind
for z in range(still.shape[1]):
out[z] = np.minimum((still[zone, z] + wind[zone, z] * cosines) / speed, 1.0)
return out.reshape(-1)
# Moving air (``simulation.wave.wind: moving``): the still air's speed of sound in
# each cell, and the wind as the air's own motion.
def _still_grid(self, origin: np.ndarray, h: float, shape) -> tuple:
"""The still air's speed of sound (nz,) or (K, nz), the wind's speed the same
way, each weather's wind direction (K, 2) and the weather over each column
(ny, nx), or None and the atmosphere's own direction."""
z = origin[2] + (np.arange(shape[2]) + 0.5) * h
if self.zones is None:
still, wind = self._profiles(z)
return still, wind, self.wind[None, :], None
profiles = [self._profiles(z, k) for k in range(len(self.weathers))]
centres = [origin[a] + (np.arange(shape[a]) + 0.5) * h for a in range(2)]
x, y = np.meshgrid(centres[0], centres[1])
zone = self.zones.zone_at(np.column_stack([x.ravel(), y.ravel()])).reshape(x.shape)
still = np.array([q[0] for q in profiles])
wind = np.array([q[1] for q in profiles])
return still, wind, np.asarray(self.winds, dtype=float), zone
def still_at(self, point: np.ndarray) -> float:
"""The still air's speed of sound (m/s) at ``point`` (3,)."""
point = np.asarray(point, dtype=float).reshape(3)
k = None if self.zones is None else int(self.zones.zone_at(point[None, :2])[0])
return float(self._profiles(point[2:3], k)[0][0])
def moving_extremes(self, origin: np.ndarray, h: float, shape) -> tuple[float, float, float]:
"""The slowest and the fastest still air's speed of sound over the grid's
cells, and the wind's fastest speed (m/s)."""
still, wind, _, zone = self._still_grid(origin, h, shape)
if zone is not None:
used = np.unique(zone)
still, wind = still[used], wind[used]
return float(still.min()), float(still.max()), float(np.abs(wind).max())
def moving_fields(self, origin: np.ndarray, h: float, shape, speed: float, shift: float):
"""(nx ny nz,) float32 each, x fastest: each cell's still air's speed of sound
over ``speed`` (the grid's, at most 1), and the air's velocity along x and y in
cells per step (the wind's speed times ``shift``, a step over a cell)."""
still, wind, towards, zone = self._still_grid(origin, h, shape)
nz, ny, nx = int(shape[2]), int(shape[1]), int(shape[0])
speeds = np.empty((nz, ny, nx), np.float32)
fx = np.empty((nz, ny, nx), np.float32)
fy = np.empty((nz, ny, nx), np.float32)
for z in range(nz): # a layer at a time, to keep the memory down
if zone is None:
speeds[z] = min(still[z] / speed, 1.0)
fx[z] = wind[z] * towards[0, 0] * shift
fy[z] = wind[z] * towards[0, 1] * shift
else:
speeds[z] = np.minimum(still[zone, z] / speed, 1.0)
fx[z] = wind[zone, z] * towards[zone, 0] * shift
fy[z] = wind[zone, z] * towards[zone, 1] * shift
return speeds.reshape(-1), fx.reshape(-1), fy.reshape(-1)
#: Points each listener takes the pressure at (see :func:`_probe_points`).
_PROBES = 13
#: A point round a listener that lies nearer the source than this many cells, and nearer
#: it than the listener itself, is left out of the listener's gradient (see
#: :func:`_off_the_source`), by the stencil's points: it reads the cells the source
#: itself feeds, whose sound is not a point's. Measured against a point source's exact
#: field over 18 places of the source within a cell and 50 directions, the grid's 26 and
#: others (``places`` of validation/wave_solver.py, with this at 0 and at 1.5; the worse
#: of the 63 and 125 Hz bands). On the 19-point grid, 1.5, 2, 2.5 and 3 cells from the
#: source, the gradient's main axis is up to 26, 21, 10 and 7 degrees off the line to
#: the source with those points and 16, 13, 10 and 7 without them, and its energy over
#: the pressure's up to 9.2, 7.6, 13.2 and 6.6 dB off with them and 6.3, 4.5, 3.7 and
#: 1.2 dB without. A listener nearer the source than 1.5 cells keeps the points that lie
#: no nearer it than itself: 1 and 1.4 cells away its axis is then up to 11.4 and 16.0
#: degrees off and its energy 7.30 and 6.54 dB (with every point 17.6 and 26.0 degrees,
#: 7.56 and 9.25 dB; without any point nearer than 1.5 cells 27.7 and 20.4 degrees), and
#: from one listener to the next 0.1 cells further out the energy changes by 2.4 dB at
#: most from 0.9 cells on (by 15.2 dB at 1.5 cells if a listener nearer than that kept
#: every point; one-off scans every 0.1 cells from 0.5 to 2, as ``places`` measures).
#: On the 7-point grid 1.5, 2, 2.5 and 3 cells give 21, 15, 5 and 4 degrees and 6.2,
#: 5.4, 3.4 and 1.7 dB with the points, 17, 17, 5 and 4 degrees and 5.4, 4.3, 3.5 and
#: 1.9 dB without: no clear gain, so it keeps them.
_SOURCE_CELLS = {7: 0.0, 19: 1.5}
def _off_the_source(
found: np.ndarray, probes: np.ndarray, source: np.ndarray, cell: float, stencil: int
) -> np.ndarray:
"""``found`` (whether each of ``probes``, the :func:`_probe_points` of each listener
in turn, counts) without the points among the source's own cells: those nearer the
source than :data:`_SOURCE_CELLS` cells and nearer it than their listener (that many
cells, or as far as the listener, to within rounding counts as not nearer). Of the
two points a cell from a listener along an axis at most one lies nearer the source
than the listener, so the listener loses at most that one. Where the other one is
not found either (a wall behind the listener), the axis keeps its points."""
limit = (_SOURCE_CELLS[stencil] - 1e-9) * cell
away = np.linalg.norm(probes - source, axis=1).reshape(-1, _PROBES)
near = (away < limit) & (away < away[:, :1] - 1e-9 * cell)
before = np.asarray(found, dtype=bool).reshape(-1, _PROBES)
after = before & ~near
for axis in range(3):
points = [1 + 2 * axis, 2 + 2 * axis, 7 + 2 * axis, 8 + 2 * axis]
empty = ~(after[:, points[0]] | after[:, points[1]])
after[np.ix_(empty, points)] = before[np.ix_(empty, points)]
return after.reshape(-1)
def _probe_points(listener: np.ndarray, cell: float) -> np.ndarray:
"""The listener, the points one cell to either side of it along each axis (+x, -x,
+y, -y, +z, -z), then those two cells to either side, in the same order:
:data:`_PROBES` points."""
steps = np.repeat(np.eye(3), 2, axis=0) * np.tile([1, -1], 3)[:, None]
return listener[None, :] + cell * np.vstack([np.zeros(3), steps, 2 * steps])
def _spans_across(source: np.ndarray, listeners: np.ndarray) -> np.ndarray:
"""(3,) the farthest any of ``listeners`` lies from ``source`` across each axis: in
the plane of the other two."""
offsets = listeners - source
across = np.sum(offsets**2, axis=1)[:, None] - offsets**2
return np.sqrt(np.max(across, axis=0, initial=0.0))
def _open_sides(
bvh,
points: np.ndarray,
room: np.ndarray,
origin: np.ndarray,
cell: float,
shape,
layer: int,
threads: int = 0,
) -> np.ndarray:
"""(3, 2) for each axis's low and high side, whether sound that runs between
``points`` (the source, then the listeners) can meet the matched layer on that side
of the grid (of ``shape`` cells of ``cell`` metres from ``origin``, ``layer`` of them
matched layer inside each edge) near grazing: whether the layer there needs its
``room`` (3,) (see :data:`LAYER_ROOM`).
It can where the air round the points reaches the layer inside the box that lies the
room past them along every axis (and five cells, for the cells the points take: a
listener's gradient points lie two cells from it, and each reads up to two further). The
air is flooded from the source over the grid's cells in that box, as the solver
floods its own, and from every listener it does not reach. Where it reaches no
layer, a surface of the model lies between: sound from a point to that side's layer
and back to a point leaves the box across one of its faces, so it runs at least as
far as a reflection off a layer that lies that face's axis's room past the points,
which a grid with room on every side has too. A side of the box that ends short of
the layer counts as open (its room lies inside the grid).
"""
from acoustic_spaces import _native
shape = np.asarray(shape, dtype=np.int64)
first, last = np.full(3, layer + 1), shape - 2 - layer # the cells inside the layer
low = np.floor((points.min(axis=0) - room - origin) / cell).astype(np.int64) - 5
high = np.floor((points.max(axis=0) + room - origin) / cell).astype(np.int64) + 5
start, stop = np.maximum(first, low), np.minimum(last, high)
reached = np.zeros((3, 2), dtype=bool)
left = list(range(len(points))) # the points whose air is not flooded yet
while left:
seed, left = left[0], left[1:]
try:
# A grid of the box's cells and one more round them, where its air ends.
part = _native.WaveSolver(
bvh,
np.zeros(bvh.face_count, np.int64),
np.zeros(1),
np.zeros((0, 3)),
np.zeros(0, np.int64),
origin + (start - 1) * cell,
cell,
*(int(n) for n in stop - start + 3),
np.ascontiguousarray(points[seed]),
np.ascontiguousarray(points[left].reshape(-1, 3)),
1.0,
0,
0.0,
threads,
)
except ValueError:
continue # a point in no air: the run's own grid says which, and stops
reached |= np.array(part.open_sides, dtype=bool).reshape(3, 2)
left = [p for k, p in enumerate(left) if not part.probe_found(k)]
at_layer = np.column_stack([start == first, stop == last])
return reached | ~at_layer
def _first_order(
probes: np.ndarray,
found: Sequence[bool],
name: str,
courant: float = COURANT,
cutoff: float = _LOW_PASS_CUTOFF,
) -> np.ndarray:
"""W, X, Y, Z (samples, 4) from the pressure at the listener and round it, at the
:func:`_probe_points` (``probes``, one row each).
X, Y and Z are c times the time integral of the pressure gradient: X = -rho c u_x,
against the particle velocity, so that it points towards the sound (as in AmbiX).
The gradient is a central difference of fourth order over two cells either side,
(8 (p(h) - p(-h)) - (p(2h) - p(-2h))) / 12h, of second order where a point two cells
away is not ``found`` (out of the air, or across a surface from the listener), and
one-sided where a point one cell away is not. The integral is the trapezoidal rule,
so that it falls on the pressure's samples, with the rule's gain, (wT/2) / tan(wT/2),
divided out up to ``cutoff`` (of the sample rate), the source's low-pass's cutoff:
above it the source gives next to nothing. ``courant`` is the Courant number of the
speed of sound at the listener.
"""
if not found[0]:
raise ValueError(f"listener {name!r} is not in the air of the wave grid")
out = np.zeros((probes.shape[1], 4))
out[:, 0] = probes[0]
for axis in range(3):
plus, minus = 1 + 2 * axis, 2 + 2 * axis
if found[plus] and found[minus]:
difference = 0.5 * (probes[plus] - probes[minus])
if found[plus + 6] and found[minus + 6]:
difference = difference * (4 / 3) - (probes[plus + 6] - probes[minus + 6]) / 12
elif found[plus]:
difference = probes[plus] - probes[0]
elif found[minus]:
difference = probes[0] - probes[minus]
else:
continue
out[:, 1 + axis] = courant * (np.cumsum(difference) - 0.5 * difference)
n_fft = 1 << int(math.ceil(math.log2(2 * len(out) + 1)))
turn = np.pi * np.fft.rfftfreq(n_fft) # wT / 2
gain = np.ones(len(turn))
below = (turn > 0) & (turn <= np.pi * cutoff)
gain[below] = np.tan(turn[below]) / turn[below]
spectrum = np.fft.rfft(out[:, 1:], n_fft, axis=0) * gain[:, None]
out[:, 1:] = np.fft.irfft(spectrum, n_fft, axis=0)[: len(out)]
return out
[docs]
def wave_responses(
model,
source: np.ndarray,
listeners: np.ndarray,
names: Sequence[str],
*,
max_band_hz: int,
length_s: float,
sample_rate: float,
speed_of_sound: float,
points_per_wavelength: float = 8.0,
threads: int = 0,
device: Device = "cpu",
scheme: Scheme = "auto",
say: Callable[[str], None] | None = None,
label: str = "",
wind: WindModel = "effective",
walls: Walls = "cell_faces",
) -> tuple[list[WaveResponse], dict[str, float]]:
"""The wave bands of the responses from ``source`` to each of ``listeners`` in the
room of ``model`` (a :class:`~acoustic_spaces.engine.model.TraceModel`), and run
details. ``device`` says where the grid is stepped (see :mod:`.gpu`); ``scheme``
which stencil steps it: ``"isotropic"`` (19 points), ``"standard"`` (7 points) or
``"auto"``, the isotropic one but round an open model, where only the standard one
has the matched layer. ``wind`` says how it takes the wind outdoors: ``"effective"``,
as a speed of sound changed by the wind's component along the horizontal from the
source, or ``"moving"``, as air that moves (see the module's notes). ``walls`` says
where the grid's walls lie: ``"cell_faces"``, on the cell faces nearest the surfaces,
or ``"fitted"``, where the model has them, cut through the cells; fitted walls take
the standard stencil whatever the ``scheme`` but ``"isotropic"``, which they refuse,
as they refuse an outdoor model and moving air. The fit's own refusals of a model (a
crack, faces laid on one another, a model reaching into the matched layer) are
``ValueError`` starting "fitted walls:", raised before any step."""
from acoustic_spaces import _native
from acoustic_spaces.scene.model import FITTED_WALLS_OUTDOORS, FITTED_WALLS_STENCIL
say = say or (lambda _: None)
use_gpu(device) # an unknown device, or the GPU missing, before any work
if max_band_hz not in WAVE_BANDS_HZ:
raise ValueError(f"max_band_hz must be one of {WAVE_BANDS_HZ}, got {max_band_hz}")
# The scene's schema checks these; a caller of this function may pass anything.
if scheme not in ("auto", "standard", "isotropic"):
raise ValueError(f"unknown scheme {scheme!r}; use auto, standard or isotropic")
if wind not in ("effective", "moving"):
raise ValueError(f"unknown wind {wind!r}; use effective or moving")
if walls not in ("cell_faces", "fitted"):
raise ValueError(f"unknown walls {walls!r}; use cell_faces or fitted")
fitted = walls == "fitted"
if fitted and scheme == "isotropic":
raise ValueError(FITTED_WALLS_STENCIL)
for what, value in (
("points_per_wavelength", points_per_wavelength),
("length_s", length_s),
("sample_rate", sample_rate),
("speed_of_sound", speed_of_sound),
):
if not (math.isfinite(value) and value > 0.0):
raise ValueError(f"{what} must be a positive number, not {value!r}")
listeners = np.asarray(listeners, dtype=float).reshape(-1, 3)
if len(names) != len(listeners):
raise ValueError(f"{len(names)} names for {len(listeners)} listeners")
mesh = model.room.mesh
solid = ~model.transparent
if not solid.any():
raise ValueError(
"the wave solver needs a surface that reflects: every face of the model lets "
"all sound through (an opening)"
)
if model.transmission is not None:
partial = np.unique(model.room.face_materials[solid & np.any(model.transmission > 0, 1)])
if len(partial):
materials = ", ".join(repr(model.room.material_names[m]) for m in partial)
raise ValueError(
f"the wave solver cannot pass sound through a surface; {materials} let "
"some through (openings, with transmission 1, are fine): set "
"simulation.wave.enabled to false or give them no transmission"
)
# The faces of the grid's walls, and their tree; fitted walls are cut from these.
bvh, faces = model.bvh, mesh.faces
if not solid.all(): # openings: holes in the grid's walls
faces = np.ascontiguousarray(mesh.faces[solid])
bvh = _native.Bvh(mesh.vertices, faces, split=model.ray_tree)
points = np.vstack([np.asarray(source, dtype=float).reshape(1, 3), listeners])
centres = band_centres(model.bands)
bands = (OCTAVE_BANDS_HZ.index(max_band_hz) + 1) * BANDS_PER_OCTAVE[model.bands]
total = len(centres)
# Each material's admittance, fitted to its absorption in the wave bands, or for a
# material with an impedance (a ground's) to that impedance's admittance.
coefficients = np.round(model.absorption[solid, :bands], 6)
impedance = None
if model.face_impedance is not None:
keys = np.column_stack([coefficients, model.face_impedance[solid]])
keys, face_material = np.unique(keys, axis=0, return_inverse=True)
rows, impedance = keys[:, :bands], keys[:, bands].astype(np.int64)
else:
rows, face_material = np.unique(coefficients, axis=0, return_inverse=True)
outdoor = model.room.outdoor is not None
if fitted and outdoor:
raise ValueError(FITTED_WALLS_OUTDOORS)
weather = _Weather.of(model, source)
windy = False # the wind blows somewhere over the scene
if weather is not None:
heights = model.room.mesh.vertices[:, 2]
top = max(float(heights.max()), float(points[:, 2].max())) + 100.0
z = np.linspace(model.ground, top, 512)
weathers = weather.weathers if weather.zones is not None else [weather.atmosphere]
windy = any(np.any(np.asarray(w.wind_speed(z - model.ground)) != 0.0) for w in weathers)
moving = windy and wind == "moving" # (temperature alone needs no moving air)
if fitted and weather is not None:
# Only an outdoor scene has a weather, and outdoors is refused above; the fitted
# solver takes still air with one speed of sound over the grid, so a weather that
# reaches here all the same is refused, its moving air or its speed per cell.
if moving:
raise ValueError(
"fitted walls are not available in moving air: set simulation.wave.walls "
"to cell_faces, or simulation.wave.wind to effective"
)
raise ValueError(
"fitted walls take one speed of sound over the grid, and the weather gives each "
"cell its own: set simulation.wave.walls to cell_faces"
)
open_sides: list[np.ndarray] = [] # the sides whose layer needs room, once found
fit_seconds: list[float] = [] # with fitted walls, the fit's on each grid made
def layout(courant: float, layer: int, speed: float, per_wavelength: float):
"""The grid for the stencil's ``courant``, with ``layer`` cells of matched
layer, its time step set by ``speed``, ``per_wavelength`` cells per wavelength
at that speed; where it starts, and its shape."""
grid = band_grid(bands - 1, sample_rate, speed, per_wavelength, total, courant)
h = grid.cell
# The model, and two cells round the source and listeners (in an open model they
# may lie outside it); then two cells of margin (one for an open model's air, one
# that is never air) and in an open model the matched layer, shifted off the
# model's planes.
low = np.minimum(mesh.vertices.min(axis=0), points.min(axis=0) - 2.0 * h)
high = np.maximum(mesh.vertices.max(axis=0), points.max(axis=0) + 2.0 * h)
offset = h * (2.0 + layer + np.array([0.0137, 0.0219, 0.0291]))
if layer:
# Room for sound that runs along the layer (see LAYER_ROOM), below in whole
# cells so that the grid keeps its place on the model; none under an outdoor
# scene, whose ground closes the grid there, nor on a side the model's own
# surfaces close (found once, on the first grid that would grow).
room = LAYER_ROOM * _spans_across(points[0], points[1:])
below = np.ceil(np.maximum(low - (points.min(axis=0) - room), 0.0) / h)
if outdoor:
below[2] = 0.0
above = np.maximum(high, points.max(axis=0) + room)
if not open_sides and (below.any() or np.any(above > high)):
bare = np.ceil((high - low + offset) / h).astype(np.int64) + 2 + layer
if int(np.prod(bare)) > MAX_CELLS: # refused below, with or without room
open_sides.append(np.ones((3, 2), dtype=bool))
else:
open_sides.append(
_open_sides(bvh, points, room, low - offset, h, bare, layer, threads)
)
if open_sides:
low = low - h * np.where(open_sides[0][:, 0], below, 0.0)
high = np.where(open_sides[0][:, 1], above, high)
origin = low - offset
shape = np.ceil((high - origin) / h).astype(np.int64) + 2 + layer
return grid, origin, shape
def check_size(shape, layer: int) -> None:
"""Refuses a grid of more than MAX_CELLS cells, before the weather's fields or
the solver, each the size of the grid, are made for it."""
if int(np.prod(shape)) > MAX_CELLS:
what = " with the matched layer round this open model" if layer else ""
raise ValueError(
f"the wave grid up to the {max_band_hz} Hz band would have "
f"{int(np.prod(shape)):,} cells{what} (at most {MAX_CELLS:,}); lower "
"max_band_hz or points_per_wavelength"
)
def prepare(stencil: str, layer: int, still_air: bool = False):
"""The solver, grid, fits and probes for the stencil, with ``layer`` cells of
matched layer; with ``still_air``, in the weather's still air, without its wind
(for a closed model's air, which no wind blows through)."""
size, courant = STENCILS[stencil]
speeds, extremes, flow = None, None, (None, None)
still = speed_of_sound # the slowest still air's speed of sound on the grid
if weather is None:
grid, origin, shape = layout(courant, layer, speed_of_sound, points_per_wavelength)
check_size(shape, layer)
elif moving or still_air:
# Fine enough for sound going against the fastest wind in the slowest air, in
# time steps for the fastest still air (the air's motion is carried apart;
# still air has none).
slowest = fastest = float(weather.at(source)[0])
for _ in range(8):
grid, origin, shape = layout(
courant, layer, fastest, points_per_wavelength * fastest / slowest
)
low, high, top = weather.moving_extremes(origin, grid.cell, shape)
if still_air:
top = 0.0
if low - top >= slowest and high <= fastest:
break
slowest, fastest = min(slowest, low - top), max(fastest, high)
check_size(shape, layer)
step = courant * grid.cell * grid.rate
speeds, *flow = weather.moving_fields(
origin, grid.cell, shape, step, 1.0 / (grid.cell * grid.rate)
)
if still_air:
flow = [None, None]
extremes, still = (low - top, high + top), low
else:
# Fine enough for the slowest sound and in time steps for the fastest, over
# the grid those give (which grows a little as its cells shrink).
slowest = fastest = float(weather.at(source)[0])
for _ in range(8):
grid, origin, shape = layout(
courant, layer, fastest, points_per_wavelength * fastest / slowest
)
low_speed, high_speed = weather.extremes(origin, grid.cell, shape)
if low_speed >= slowest and high_speed <= fastest:
break
slowest, fastest = min(slowest, low_speed), max(fastest, high_speed)
check_size(shape, layer)
speeds = weather.ratios(origin, grid.cell, shape, courant * grid.cell * grid.rate)
extremes, still = (low_speed, high_speed), low_speed
h = grid.cell
fits = [fit_admittance(row, total, grid.rate) for row in rows]
if impedance is not None:
for m in np.flatnonzero(impedance >= 0).tolist():
fits[m] = fit_impedance(
_impedance_of(model, int(impedance[m])), bands, total, grid.rate
)
branches = [fit.branches(grid.rate) for fit in fits]
branch_material = np.concatenate(
[np.full(len(b), m, dtype=np.int64) for m, b in enumerate(branches)]
)
probes = np.vstack([_probe_points(p, h) for p in listeners])
# Fitted walls: the arrays the walls' tree is built from, the faces in its order.
fitting = (
{"fitted_walls": True, "vertices": mesh.vertices, "faces": faces} if fitted else {}
)
try:
solver = _native.WaveSolver(
bvh,
np.ascontiguousarray(face_material.reshape(-1), dtype=np.int64),
np.array([fit.beta for fit in fits]),
np.ascontiguousarray(np.vstack(branches)),
branch_material,
origin,
h,
int(shape[0]),
int(shape[1]),
int(shape[2]),
np.asarray(source, dtype=float),
np.ascontiguousarray(probes),
1.0,
layer,
LAYER_DAMPING,
threads,
size,
speeds,
*flow,
_PROBES,
**fitting,
)
except ValueError as error:
if "the wind round the model's solids" not in str(error):
raise
raise ValueError(
f"the wave solver's moving air: {error} (on cells of {100 * h:.0f} cm; a "
"sharp edge speeds the wind up, the more the finer the grid): set "
"simulation.wave.wind to effective, or lower max_band_hz or "
"points_per_wavelength"
) from error
if fitted:
fit_seconds.append(float(solver.cut_stats["seconds"]))
return solver, grid, fits, probes, courant, extremes, still
def kept(stencil: str, layer: int, still_air: bool = False):
"""What ``prepare`` gives, where its grid is closed without a matched layer or
open with one; otherwise None, and its grid goes before the next is made."""
built = prepare(stencil, layer, still_air)
return built if built[0].open == bool(layer) else None
# The isotropic stencil, but round an open model the standard one with its matched
# layer, which the isotropic one has none of, and with fitted walls the standard one
# (they take no other). An outdoor model's sky is an opening, so its grid is open
# unless the source is shut in: the one with the layer first, and the isotropic
# stencil refused before any grid is made. With fitted walls the model is fitted on
# each grid made: an open model's twice, its closed grid's fit thrown away.
if scheme == "isotropic" and outdoor:
raise ValueError(
"outdoors the isotropic stencil is not available (it has no matched layer for "
"the sky): set simulation.wave.scheme to auto or standard"
)
built = kept("standard", LAYER_CELLS) if outdoor else None
if built is None:
# A closed model's air is still, whichever way the wind is taken: no wind blows
# through its walls (outdoors, a source shut in a closed building).
built = kept("standard" if scheme == "standard" or fitted else "isotropic", 0, windy)
if built is None:
if scheme == "isotropic":
raise ValueError(
"the isotropic stencil has no matched layer for an open model: set "
"simulation.wave.scheme to auto or standard"
)
built = prepare("standard", LAYER_CELLS)
solver, grid, fits, probes, courant, extremes, still = built
still_inside = windy and not solver.open # the wind left out of a closed model
stilled = moving or still_inside # the grid's speeds are the still air's
h = grid.cell
at_source = 1.0 # the speed of sound at the source over the grid's
if weather is not None:
here = weather.still_at(source) if stilled else weather.at(source)[0]
at_source = min(float(here) / (courant * h * grid.rate), 1.0)
signal, delay = source_signal(grid.rate, h, courant, at_source)
samples = int(math.ceil(length_s * grid.rate))
# The run starts `lead` steps before emission, where the source's pulse starts (or a
# little before, so that the lead is a whole number of the output's samples), and
# keeps all of it: a listener within `delay` steps' travel of the source hears it
# start before emission.
whole = max(1, round(grid.rate / sample_rate)) # steps per output sample, at least 1
lead = -(-delay // whole) * whole
steps = lead + samples # the source's term on step n stands for its value at step n
drive = np.zeros(steps, np.float32)
drive[lead - delay : lead - delay + len(signal)] = signal[: steps - lead + delay]
# Before any step: a listener outside the source's air, or a source closed in. A
# point round a listener counts only where the listener sees it, from the side of a
# surface each is read on: a point across a thin surface (a screen, a balcony's front)
# can have air of its own, and a difference across the surface is no gradient of the
# listener's air.
found = np.array(
[solver.probe_found(p) and solver.probe_in_sight(p) for p in range(len(probes))]
)
found = _off_the_source(found, probes, np.asarray(source, dtype=float), h, solver.stencil)
found = found.tolist()
missing = [listener for i, listener in enumerate(names) if not found[_PROBES * i]]
if missing:
# A source on a surface sends sound into the space on one side of it, which the
# listeners it reaches choose where they can (see the solver's place_on_face).
note = (
" (the source lies on a surface of the model and sends sound into the space on"
" one side of it only: a listener in the space on its other side is not reached)"
if solver.source_on_face
else ""
)
air, volume = solver.air_cells * h**3, model.room.volume_m3
if volume and air < 0.1 * volume:
who = f"source {label!r}" if label else "the source"
raise ValueError(
f"{who} is closed in: the wave grid has {air:.2g} m³ of air round it, "
f"in a room of {volume:.3g} m³{note}"
)
raise ValueError(f"listener {missing[0]!r} is not in the air of the wave grid{note}")
name = f"{centres[0]} Hz" if bands == 1 else f"{centres[0]}-{centres[bands - 1]} Hz"
# The GPU steps still air only: moving air stays on the CPU.
gpu_wanted = use_gpu(device, steps)
on_gpu = gpu_wanted and not solver.flowing
where = f" on {gpu_name()}" if on_gpu else ""
if extremes is not None:
where += f", sound at {extremes[0]:.0f} to {extremes[1]:.0f} m/s"
if still_inside:
where += ", the wind left out: the air inside the closed model is still"
# The fastest wind round the model's solids (m/s), where it was made to flow round them.
fastest = solver.wind_fastest * h * grid.rate if solver.wind_round else None
if solver.flowing:
where += ", the air moving" + (
" (on the CPU: the GPU steps still air)" if gpu_wanted else ""
)
if fastest is not None:
where += f", round the model's solids at up to {fastest:.0f} m/s"
say(
f"{label}: wave solver, {name} ({solver.air_cells:,} cells of {100 * h:.0f} cm, "
f"{'fitted walls, ' if fitted else ''}{steps:,} steps{where})"
)
stepper = GpuWaveSolver(solver) if on_gpu else solver
who = f"source {label!r}" if label else "the source"
unstable = "set simulation.wave.wind to effective"
# Long runs report every tenth (which is also where a cancelled run stops), and
# moving air runs in the pieces it is watched over (see WATCH_S).
tenths = 10 if solver.air_cells * steps > _LONG_RUN else 1
watch = max(1, round(WATCH_S * grid.rate)) # the steps of a watched piece, at least
chunks = max(tenths, steps // watch) if solver.flowing else tenths
if chunks == 1:
recorded = stepper.run(drive)
else:
# Into one array as each piece comes, not all joined at the end (twice the
# memory).
recorded = np.empty((len(probes), steps))
bounds = np.linspace(0, steps, chunks + 1).astype(np.int64)
ended = lead - delay + len(signal) # the first step after the source's pulse
lowest, largest = math.inf, 0.0
squares, since = 0.0, 0 # the watched piece so far: its squares' sum, its first step
for c in range(chunks):
if c and c * tenths // chunks > (c - 1) * tenths // chunks:
say(f"{label}: wave solver, {name}, {100 * (c * tenths // chunks) // tenths} %")
recorded[:, bounds[c] : bounds[c + 1]] = stepper.run(drive[bounds[c] : bounds[c + 1]])
if not solver.flowing:
continue
squares += solver.mean_square * float(bounds[c + 1] - bounds[c])
if not math.isfinite(squares):
recorded[:, bounds[c + 1] :] = math.nan # refused below
break
if bounds[c + 1] - since < watch:
continue # (a long run's tenths can be shorter than a watched piece)
level = squares / float(bounds[c + 1] - since)
start, squares, since = since, 0.0, int(bounds[c + 1])
largest = max(largest, level)
if start >= ended:
if level > WATCH_RISE * lowest and level > WATCH_FLOOR * largest:
raise ValueError(
f"{who}: the wave solver's sound grew in the moving air instead "
f"of dying away ({10 * math.log10(level / lowest):.1f} dB over its "
f"lowest level, {(since - lead) / grid.rate:.1f} s after "
f"emission): {unstable}"
)
lowest = min(lowest, level)
if not np.all(np.isfinite(recorded)):
raise ValueError(
f"{who}: the wave solver's run did not stay finite"
+ (f": {unstable}" if solver.flowing else "")
)
info: dict[str, float] = {
"wave_cells": float(solver.air_cells),
"wave_cell_m": h,
"wave_steps": float(steps),
"wave_stencil": float(solver.stencil),
}
if solver.open:
info["wave_open"] = 1.0
if on_gpu:
info["wave_gpu"] = 1.0
if extremes is not None:
info["wave_speed_min_m_s"], info["wave_speed_max_m_s"] = extremes
if solver.flowing:
info["wave_moving_air"] = 1.0
if fastest is not None:
info["wave_wind_fastest_m_s"] = fastest
if still_inside:
info["wave_still_inside"] = 1.0
if fitted:
info["wave_fitted_walls"] = 1.0
info["wave_fit_s"] = sum(fit_seconds) # on every grid made
# How much slower than it should sound travels at the top of the highest band along
# the grid's axes: the slowest sound's cells per wavelength there, stepped as the
# slowest air is (in moving air, the still air's step in the air's own frame;
# carrying it with the wind adds an error of its own).
slowest = speed_of_sound if extremes is None else extremes[0]
per_wavelength = slowest / (band_top(bands - 1, total) * h)
ratio = still / (courant * h * grid.rate)
info["wave_slow_percent"] = 100.0 * slow_by(solver.stencil, per_wavelength, ratio)
# How far the fitted surfaces' absorption is from the materials', at worst.
used = np.unique(face_material)
wanted = np.minimum(rows[used], MAX_ABSORPTION)
info["wave_absorption_miss"] = float(
np.max(np.abs(np.array([fits[m].achieved for m in used]) - wanted))
)
responses = []
for i, listener in enumerate(names):
part = slice(_PROBES * i, _PROBES * (i + 1))
local = courant # the Courant number at the listener
if weather is not None:
# In moving air the still air's (the wind's share of the gradient is left out).
here = weather.still_at(listeners[i]) if stilled else weather.at(listeners[i])[0]
local *= float(here) / (courant * h * grid.rate)
# X, Y and Z from the first step on, where the grid is still at rest.
signals = _first_order(recorded[part], found[part], listener, local, _cutoff(courant))
responses.append(WaveResponse(grid.rate, signals, bands, h, total, lead / grid.rate))
return responses, info
def _impedance_of(model, row: int):
"""The admittance at frequencies f (Hz) of the material with the impedance in row
``row`` of the model's (see
:attr:`~acoustic_spaces.engine.model.TraceModel.face_impedance`)."""
room = model.room
face = int(np.flatnonzero(model.face_impedance == row)[0])
material = room.scene.materials[room.material_names[room.face_materials[face]]]
return lambda f: material.impedance.admittance(f, room.speed_of_sound())
__all__ = [
"COURANT",
"ISOTROPIC_COURANT",
"HIGH_PASS_S",
"LAYER_CELLS",
"LAYER_DAMPING",
"LOW_EDGE_HZ",
"MAX_ABSORPTION",
"MAX_CELLS",
"LINK_WEIGHTS",
"STENCILS",
"WAVE_BANDS_HZ",
"Scheme",
"Walls",
"WindModel",
"Admittance",
"BandGrid",
"WaveResponse",
"absorption_of_impedance",
"admittance",
"fit_admittance",
"band_grid",
"band_top",
"grid_phase",
"slow_by",
"source_signal",
"wave_gains",
"wave_responses",
]