"""The simulated response from one source to one listener."""
from __future__ import annotations
import dataclasses
import math
import weakref
from collections.abc import Callable, Sequence
from dataclasses import dataclass, field
from typing import TYPE_CHECKING, Any, cast
import numpy as np
from acoustic_spaces import parameters as iso3382
from acoustic_spaces import products, synthesis
from acoustic_spaces.engine import coherent
from acoustic_spaces.engine.early import EarlyReflections
from acoustic_spaces.engine.wave import WaveResponse
from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ, band_centres, resolution_of, to_octaves
if TYPE_CHECKING:
from acoustic_spaces.engine.reweight import Redraws
#: The synthesized late part is smoothed over 10 ms from this long after the direct sound.
SMOOTH_AFTER_S = 0.05
#: Stage support is measured this far from the source (m): ISO 3382-1:2009, annex C (after
#: Gade's ST1). It is given only for listeners within ``STAGE_TOLERANCE_M`` of it: its
#: first 10 ms hold the direct sound, whose energy goes as 1 / r^2, so a listener r m away
#: reads it up to 20 lg r dB off, 0.9 dB at 0.9 m and 0.8 dB at 1.1 m.
STAGE_DISTANCE_M = 1.0
STAGE_TOLERANCE_M = 0.1
#: The fields of a :class:`Response` that hold its late part, each of which may be given
#: as a :class:`Deferred`.
LATE_ARRAYS = ("late", "late_directional", "late_moments", "late_batches")
@dataclass(frozen=True)
class Deferred:
"""A late array that a :class:`Response` makes when it is read instead of holding
it: what ``make()`` gives. A walk's places between those traced for their
late part have theirs so, each mixed from the traced ones on either side
(``simulate(late_from=...)``), which are held once however many places read them."""
make: Callable[[], np.ndarray]
def then(self, change: Callable[[np.ndarray], np.ndarray]) -> Deferred:
"""``change`` of this array, made when it is read."""
make = self.make
return Deferred(lambda: change(make()))
def field(self) -> np.ndarray:
"""This, as a :class:`Response` takes it for one of its ``LATE_ARRAYS``: typed
as the array the field reads as."""
return cast(np.ndarray, self)
[docs]
@dataclass
class Response:
"""Early specular paths plus late energy per band and time slot, and the lowest
bands from the wave solver when it ran (``wave``), which then replace the rays'.
The bands are the 8 octave bands or the 24 third-octave bands the simulation ran in;
room parameters are given in octave bands either way.
Energies are time-integrated intensity for a source of unit energy (the direct sound
at r metres carries 1 / (4 pi r^2)); times are measured from emission.
The late part's arrays (``late``, ``late_directional``, ``late_moments`` and
``late_batches``) may each be given as a :class:`Deferred`: the response then keeps
that, and reading the field makes the array, which a read of the field again gets
until that of another response is made.
"""
source: str
listener: str
early: EarlyReflections
late: np.ndarray # (bands, slots)
time_step: float # s, slot width of ``late``
length_s: float
#: Arrival time of the direct sound (s), whether or not the direct path is blocked.
direct_delay_s: float
#: Early paths end here (s, from emission); the late part covers everything else.
transition_s: float
#: Volume of the listener's room (m3; None in a model that is not closed): how
#: densely the synthesized late part's reflections come.
volume_m3: float | None
speed_of_sound: float
#: Seed for the noise of the synthesized late part.
seed: int = 0
#: The listener's head axes (forward, left, up) as columns, in room coordinates.
orientation: np.ndarray = field(default_factory=lambda: np.eye(3))
#: Arrival directions of the late energy (room coordinates) and the late energy
#: split between them (directions, bands, slots of ``direction_step``). Without
#: them the late part arrives evenly from all directions.
late_directions: np.ndarray = field(default_factory=lambda: np.zeros((0, 3)))
late_directional: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0)))
direction_step: float = 0.01
#: The lowest octave bands from the wave solver, or None.
wave: WaveResponse | None = None
#: Unit vector from the listener towards the source (room coordinates); None takes
#: the direct path's, or the listener's forward axis without one.
source_direction: np.ndarray | None = None
#: The energy gain per band of the source's feed (its gain and equalizer), which the
#: energies include, or None for none. G is taken against the same source in free
#: field, so the feed does not change it.
feed: np.ndarray | None = None
#: How much later the feed makes every arrival (s), which the times include.
feed_delay_s: float = 0.0
#: With face groups (``simulate(groups=...)``): the moments of the late energy's
#: reflection counts off each group (terms, bands, slots of ``moment_step``), for
#: :meth:`reweighted`; else empty.
late_moments: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0)))
moment_step: float = 0.0
#: With the late rays traced in batches (``simulation.late.batches`` of 2 or more):
#: ``late`` as each batch gives it (batches, bands, slots of ``batch_step``, a whole
#: number of ``time_step``), each an estimate of its own and their mean ``late``, for
#: :meth:`standard_errors`; else empty.
late_batches: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0)))
batch_step: float = 0.01
#: Outdoors: the energy per band of the same source at the listener in free field
#: (its direct sound over the straight line, with the air's attenuation and the
#: source's directivity, without the feed), for :meth:`relative_to_free_field`; else
#: None.
free_field: np.ndarray | None = None
#: The early part as the echogram reads its coherent bands, with what it came from.
_pressure: tuple | None = field(default=None, init=False, repr=False, compare=False)
#: What the coherent bands' echograms share with those of the other draws of the
#: absorption the response was re-weighted for (:meth:`reweighted` with ``redraws``).
_same_delays: coherent.SameDelays | None = field(
default=None, init=False, repr=False, compare=False
)
def __getstate__(self) -> dict:
"""What a pickle or a copy of the response holds: its attributes, with the late
arrays as they read (one given as a :class:`Deferred` made)."""
return {**vars(self), **{name: getattr(self, name) for name in LATE_ARRAYS}}
@property
def bands(self) -> int:
return self.late.shape[0]
@property
def coherent_bands(self) -> int:
"""How many of the lowest bands the early paths add in pressure in
(:mod:`~acoustic_spaces.engine.coherent`); the wave solver's take the place of
those it covers."""
return self.early.coherent_bands
def _early_pressure(self) -> dict:
"""The :class:`~acoustic_spaces.engine.coherent.EarlyPressure` of each point
source's paths, as far as they were made, for
:func:`~acoustic_spaces.engine.coherent.coherent_energy`."""
early = self.early
key = (early, early.energy, early.delay_s, early.direction, early.spectrum, early.point)
if self._pressure is None or any(
a is not b for a, b in zip(self._pressure[0], key, strict=True)
):
self._pressure = (key, {})
return self._pressure[1]
@property
def band_hz(self) -> tuple[int, ...]:
"""Centre frequencies (Hz) of the bands: octave or third-octave bands."""
return band_centres(resolution_of(self.bands))
[docs]
def energy(self, time_step: float | None = None) -> np.ndarray:
"""Echogram: energy per band and time slot (bands, slots), early paths included."""
return self._echogram(time_step)
[docs]
def octave_energy(self, time_step: float | None = None) -> np.ndarray:
"""Echogram in octave bands (8, slots): each octave the mean of its three
third-octave bands, when the simulation ran in those."""
return to_octaves(self._echogram(time_step))
[docs]
def weighted_energy(
self, axis: np.ndarray, exponent: int = 2, time_step: float | None = None
) -> np.ndarray:
"""Echogram of a figure of eight facing ``axis`` (a unit vector, room
coordinates): each arrival's energy times the cosine of its angle to the axis,
taken without its sign, to the power ``exponent``. With 2 that is the energy the
figure of eight picks up; with 1 the magnitude of its product with the pressure,
as LFC takes it. Late energy without directions counts as arriving evenly from
all of them."""
return self._echogram(time_step, np.asarray(axis, dtype=float), exponent)
def _echogram(
self, time_step: float | None, axis: np.ndarray | None = None, exponent: int = 2
) -> np.ndarray:
step = self.time_step if time_step is None else time_step
slots = int(math.ceil(self.length_s / step - 1e-9))
late = self.late if axis is None else self.late * self._late_weights(axis, exponent)
if math.isclose(step, self.time_step):
out = late[:, :slots].copy()
if out.shape[1] < slots:
out = np.pad(out, ((0, 0), (0, slots - out.shape[1])))
else:
# Spread each late slot evenly over the slots it overlaps.
edges = np.arange(late.shape[1] + 1) * self.time_step
cumulative = np.concatenate(
[np.zeros((self.bands, 1)), np.cumsum(late, axis=1)], axis=1
)
new_edges = np.arange(slots + 1) * step
out = np.diff(
np.array([np.interp(new_edges, edges, row) for row in cumulative]), axis=1
)
early = self.early.energy
if axis is not None:
early = early * (np.abs(self.early.direction @ axis) ** exponent)[:, None]
# A path before its emission (none: see EarlyReflections.at_moment) would count
# in the first slot, as what a measured response's filters spread before it.
idx = np.maximum(self.early.delay_s / step, 0.0).astype(np.int64)
keep = idx < slots
count = self.coherent_bands
for b in range(count, self.bands):
np.add.at(out[b], idx[keep], early[keep, b])
if count and len(self.early):
# The lowest bands read from the early part's pressure, as from a measured
# response (or the wave solver's).
out[:count] += coherent.coherent_energy(
self.early,
step,
slots,
axis,
exponent,
start=self.direct_delay_s,
cache=self._early_pressure(),
kept=self._same_delays,
)
if self.wave is not None:
out[: self.wave.bands] = self.wave.energy(step, slots, axis, exponent)
return out
def _late_weights(self, axis: np.ndarray, exponent: int) -> np.ndarray:
"""Per band and slot of ``late``, the mean |cos|^exponent of the late energy's
directions to ``axis``: 1/3 or 1/2 for energy from all directions alike."""
even = 1.0 / (exponent + 1.0)
shape = self.late.shape
energy = self.late_directional
if len(self.late_directions) == 0 or energy.size == 0:
return np.full(shape, even)
gain = np.abs(self.late_directions @ axis) ** exponent
total = energy.sum(axis=0)
mean = np.full(total.shape, even)
# tensordot(gain, energy, axes=1): the directions' energies weighted by their gains
weighted = products.product(gain, energy.reshape(len(gain), -1)).reshape(energy.shape[1:])
np.divide(weighted, total, out=mean, where=total > 0)
coarse = (np.arange(shape[1]) * self.time_step / self.direction_step + 1e-9).astype(int)
inside = coarse < mean.shape[1]
return np.where(inside, mean[:, np.minimum(coarse, mean.shape[1] - 1)], even)
[docs]
def lateral_axis(self) -> np.ndarray:
"""The axis of a figure of eight with its null on the source (ISO 3382-1): level,
across the direction of the source, towards the listener's left side of it."""
towards = self.source_direction
if towards is None:
direct = np.flatnonzero((self.early.order == 0) & ~self.early.diffracted)
towards = self.early.direction[direct[0]] if len(direct) else self.orientation[:, 0]
side = np.cross([0.0, 0.0, 1.0], towards)
if np.linalg.norm(side) < 1e-9: # the source straight above or below
side = self.orientation[:, 1]
return side / np.linalg.norm(side)
[docs]
def fed(self, gain_db: Sequence[float] | np.ndarray, delay_s: float = 0.0) -> Response:
"""This response with the source's feed: ``gain_db`` per band (dB, the bands of
the response) on every energy, and every arrival ``delay_s`` later."""
gain = 10.0 ** (np.asarray(gain_db, dtype=float) / 10.0)
if gain.shape != (self.bands,):
raise ValueError(f"expected {self.bands} gains, one per band")
if not math.isfinite(delay_s) or delay_s < 0:
raise ValueError("the delay must be a finite time, 0 or more")
early = dataclasses.replace(
self.early, delay_s=self.early.delay_s + delay_s, energy=self.early.energy * gain
)
def late(name: str, step: float, gains: np.ndarray, empty: bool = False) -> np.ndarray:
"""The late array ``name`` (slots of ``step`` s) times ``gains`` and
``delay_s`` later, one without values left as it is unless ``empty``; one
made when it is read (:class:`Deferred`) is fed when it is read."""
def feed(x: np.ndarray) -> np.ndarray:
return _delayed(x * gains, delay_s / step) if empty or x.size else x
held = vars(self)[name]
return held.then(feed).field() if isinstance(held, Deferred) else feed(held)
directional = late("late_directional", self.direction_step, gain[None, :, None])
wave = None if self.wave is None else self.wave.fed(gain[: self.wave.bands], delay_s)
moments = late("late_moments", self.moment_step, gain[None, :, None])
batches = late("late_batches", self.batch_step, gain[None, :, None])
return dataclasses.replace(
self,
early=early,
late_moments=moments,
late_batches=batches,
late=late("late", self.time_step, gain[:, None], empty=True),
length_s=self.length_s + delay_s,
direct_delay_s=self.direct_delay_s + delay_s,
transition_s=self.transition_s + delay_s,
late_directional=directional,
wave=wave,
feed=gain if self.feed is None else self.feed * gain,
feed_delay_s=self.feed_delay_s + delay_s,
)
def _reference(self) -> np.ndarray:
"""Energy per octave band of the same source, fed alike, at 10 m in free field."""
feed = np.ones(self.bands) if self.feed is None else self.feed
return to_octaves(feed) / (4.0 * math.pi * 100.0)
[docs]
def reweighted(
self,
face_group: np.ndarray,
ratio: np.ndarray,
absorption: tuple[np.ndarray, np.ndarray] | None = None,
admittance_of=None,
redraws: Redraws | None = None,
) -> Response:
"""This response for other absorption, without tracing again
(:mod:`acoustic_spaces.engine.reweight`): ``face_group`` the group of each face
(-1 for none) as traced, ``ratio`` the change per reflection off each group,
ln((1 - new) / (1 - old)) per group and band (:func:`~acoustic_spaces.engine.
reweight.log_ratio`), and ``absorption`` each group's absorption (groups, bands)
as traced and as ``ratio`` changes it, (old, new). The early paths re-weight
exactly (but for reflections off a ground with an impedance or with zones, whose
factor is not 1 - absorption: see the module), the late part from its moments,
which the response needs (``simulate(groups=...)``). Where the early paths add in pressure
(:mod:`~acoustic_spaces.engine.coherent`), the phase of their reflections
depends on the absorption too, and turns with it
(:func:`~acoustic_spaces.engine.reweight.turned_paths`, with
``admittance_of`` if given): that needs ``absorption``, unless no path reflects
off a group whose absorption changes. ``redraws`` (a
:class:`~acoustic_spaces.engine.reweight.Redraws` of this response's early paths),
for one of many draws of the absorption, holds what does not depend on the draw;
the response is the same with it as without it."""
from acoustic_spaces.engine import reweight
ratio = np.asarray(ratio, dtype=float)
if ratio.ndim != 2 or ratio.shape[1] != self.bands:
raise ValueError(f"expected a ratio per group and each of {self.bands} bands")
groups = ratio.shape[0]
if self.late_moments.shape[0] != 1 + groups + groups * (groups + 1) // 2:
raise ValueError(
f"the response has no late moments of {groups} groups; "
"simulate it with the same groups"
)
if self.wave is not None:
raise ValueError("the wave solver's bands do not re-weight; trace without it")
if redraws is None:
counts = reweight.path_counts(self.early, face_group, groups)
else:
counts = redraws.counts(self.early, face_group, groups)
early = reweight.reweighted_paths(self.early, counts, ratio)
if self.early.spectrum is not None:
if absorption is not None:
old, new = (np.asarray(a, dtype=float) for a in absorption)
if old.shape != ratio.shape or new.shape != ratio.shape:
raise ValueError(
f"expected the absorption of {groups} groups in {self.bands} bands"
)
turn = reweight.turned_paths if redraws is None else redraws.turned
early = turn(early, face_group, old, new, admittance_of)
elif len(counts) and np.any(counts[:, np.any(ratio != 0.0, axis=1)] > 0):
raise ValueError(
"the early paths add in pressure in the lowest bands, where the phase "
"of a reflection depends on the absorption: give the absorption as "
"traced and as re-weighted for"
)
exponent = reweight.moment_exponent(self.late_moments, ratio)
factor = reweight.slot_factor(
exponent, self.late.shape[1], self.time_step, self.moment_step
)
late = self.late * factor
batches = self.late_batches
if batches.size:
batches = batches * reweight.slot_factor(
exponent, batches.shape[2], self.batch_step, self.moment_step
)
directional = self.late_directional
if directional.size:
factor = reweight.slot_factor(
exponent, directional.shape[2], self.direction_step, self.moment_step
)
directional = directional * factor[None]
out = dataclasses.replace(
self, early=early, late=late, late_directional=directional, late_batches=batches
)
if redraws is not None:
out._same_delays = redraws.delays
return out
[docs]
def parameters(self, energy: np.ndarray | None = None) -> iso3382.RoomParameters:
"""ISO 3382-1 parameters per octave band, straight from the energies.
Those of a figure of eight with its null on the source (LF, LFC, LJ) and the
decay times of figures of eight along the listener's axes come from the
directions the energy arrives from; stage support only for a listener 0.9 to
1.1 m from the source (``STAGE_DISTANCE_M`` and ``STAGE_TOLERANCE_M``), as the
standard measures it 1 m away. IACC needs a binaural response:
:func:`~acoustic_spaces.parameters.interaural_cross_correlation`. Outdoors (with
:attr:`free_field`), G of a band that does not decay as a room's does is that of
the energy the response holds. ``energy``: its :meth:`octave_energy`, when already
at hand.
"""
energy = self.octave_energy() if energy is None else energy
side = self.lateral_axis()
def weighted(axis, exponent=2):
return to_octaves(self.weighted_energy(axis, exponent))
return self._parameters(
energy,
lateral=(weighted(side), weighted(side, 1)),
directional=[weighted(self.orientation[:, k]) for k in range(3)],
)
def _parameters(self, energy: np.ndarray, **directions) -> iso3382.RoomParameters:
""":meth:`parameters` from the echogram ``energy`` in octave bands, with those
from the directions of the energy given in ``directions`` (else NaN)."""
return iso3382.from_energy(
energy,
self.time_step,
self.direct_delay_s,
reference_energy=self._reference(), # free field at 10 m
stage=self._at_stage_distance(),
open_air=self.free_field is not None,
**directions,
)
def _at_stage_distance(self) -> bool:
"""Whether the listener is close enough to 1 m from the source for stage support:
the direct sound's path (its time, the feed's delay taken off) within
``STAGE_TOLERANCE_M`` of ``STAGE_DISTANCE_M``, to a nanometre, which a distance
taken through a delay and back can miss by."""
distance = (self.direct_delay_s - self.feed_delay_s) * self.speed_of_sound
return abs(distance - STAGE_DISTANCE_M) <= STAGE_TOLERANCE_M + 1e-9
[docs]
def standard_errors(self) -> iso3382.RoomParameters | None:
"""The standard error of each of :meth:`parameters` from the late rays' batches
(``simulation.late.batches``): one standard deviation of how much it would
change between runs with other random seeds and as many rays. A jackknife: the
parameters again without each of the n batches in turn, whose spread, times
(n - 1) / n under the root, is the standard error. The early paths and the wave
solver's bands do not depend on the seed, and add none. Those from the
directions the late energy arrives from (LF, LFC, LJ and the decay times along
the listener's axes) are NaN, as IACC is; so is a parameter some batches leave
undefined or infinite (a clarity without late energy). None without 2 batches or more.
The batches hold the energy in slots of :attr:`batch_step`; without a batch,
each slot of :attr:`time_step` keeps its share of its slot of
:attr:`batch_step`, so a strong arrival in one of them (a ray through the
listener long after the rest, in a room whose walls keep a few going) leaves
with the batch it came in."""
values = [self._parameters(energy) for energy in self._without_each_batch()]
if not values:
return None
return iso3382.RoomParameters(
**{
f.name: _jackknife([getattr(v, f.name) for v in values])
for f in dataclasses.fields(iso3382.RoomParameters)
}
)
def _without_each_batch(self):
"""The echogram in octave bands without each batch of late rays in turn (the
mean of the others in its place), for a jackknife; none without 2 batches."""
batches = self.late_batches
n = len(batches)
if n < 2:
return
echogram = self.energy()
late = self.late[:, : echogram.shape[1]]
step = max(1, round(self.batch_step / self.time_step))
mean = batches.mean(axis=0)
for k in range(n):
# The late energy without batch k (the mean of the others), as a factor on it.
factor = np.ones_like(mean)
np.divide(n * mean - batches[k], (n - 1) * mean, out=factor, where=mean > 0)
factor = np.repeat(factor, step, axis=1)[:, : late.shape[1]]
energy = echogram.copy()
energy[:, : factor.shape[1]] += late[:, : factor.shape[1]] * (factor - 1.0)
if self.wave is not None:
energy[: self.wave.bands] = echogram[: self.wave.bands]
yield to_octaves(np.maximum(energy, 0.0))
[docs]
def relative_to_free_field(self) -> np.ndarray:
"""The level relative to free field per octave band (dB): how much louder (or,
negative, quieter) the source is here than the same source the same distance
away in free field, which the air between them attenuates as here. The ground,
the weather, buildings, barriers and vegetation make the difference; with the
sign turned, it is the excess attenuation of outdoor acoustics. It compares the
energy the response holds (nothing is extrapolated past its end, as G does for
a room's decay) with the free field's; -inf where no sound arrives, NaN in every
band of a response without :attr:`free_field`."""
if self.free_field is None:
return np.full(len(OCTAVE_BANDS_HZ), math.nan)
return self._relative_to_free_field(self.octave_energy())
def _relative_to_free_field(self, energy: np.ndarray) -> np.ndarray:
""":meth:`relative_to_free_field` of the echogram ``energy`` in octave bands."""
if self.free_field is None:
return np.full(len(OCTAVE_BANDS_HZ), math.nan)
held = energy.sum(axis=1) / self._reference() # re 10 m free field
with np.errstate(divide="ignore", invalid="ignore"):
return 10.0 * np.log10(held / (to_octaves(self.free_field) * (4.0 * math.pi * 100.0)))
[docs]
def levels(
self,
level_db: float | Sequence[float] = 94.0,
parameters: iso3382.RoomParameters | None = None,
) -> np.ndarray:
"""Sound pressure level per octave band (dB SPL) of a source of sound power
``level_db`` (dB re 1 pW, the feed's gain included): one value spread evenly over
the octave bands, or one per octave band
(:meth:`~acoustic_spaces.scene.Source.power_db`). It is the band's sound power
plus its G, less 31 dB, the level of a source of 0 dB at 10 m in free field."""
params = self.parameters() if parameters is None else parameters
power = np.asarray(level_db, dtype=float)
if power.ndim == 0:
power = np.full(
len(OCTAVE_BANDS_HZ), float(power) - 10.0 * math.log10(len(OCTAVE_BANDS_HZ))
)
elif power.shape != (len(OCTAVE_BANDS_HZ),):
raise ValueError("give the sound power in all or per octave band")
return power + params.g + 10.0 * math.log10(1.0 / (4.0 * math.pi * 100.0))
[docs]
def levels_or_held(
self,
level_db: float | Sequence[float] = 94.0,
parameters: iso3382.RoomParameters | None = None,
) -> np.ndarray:
""":meth:`levels`, but in a band whose G is undefined (the few rays that reach a
far place may carry no energy in it, or too little of its decay to read), the
level of the energy the response holds from the direct sound's arrival, as
outdoors: -inf where none arrives. The level a listener is given in
``simulate``'s report, the editor's results, the demos' captions and each place
of :func:`~acoustic_spaces.walkthrough.pass_by`; the coverage maps and
:meth:`speech` leave such a band undefined."""
params = self.parameters() if parameters is None else parameters
return self._levels_or_held(level_db, params)
def _levels_or_held(
self, level_db, params: iso3382.RoomParameters, energy: np.ndarray | None = None
) -> np.ndarray:
""":meth:`levels_or_held` from the parameters ``params`` of the echogram
``energy`` in octave bands (default the response's own)."""
if not np.isfinite(params.g).all():
energy = self.octave_energy() if energy is None else energy
first = min(int(self.direct_delay_s / self.time_step), energy.shape[1] - 1)
with np.errstate(divide="ignore"):
held = 10.0 * np.log10(energy[:, first:].sum(axis=1) / self._reference())
params = dataclasses.replace(params, g=np.where(np.isfinite(params.g), params.g, held))
return self.levels(level_db, params)
[docs]
def speech(
self,
level_db: float | Sequence[float] = 94.0,
noise_db: float | Sequence[float] | None = None,
parameters: iso3382.RoomParameters | None = None,
talker: iso3382.Talker = "male",
) -> iso3382.SpeechParameters:
"""STI, STIPA and U50 for speech from a source of sound power ``level_db`` (dB
re 1 pW: in all, spread evenly over the octave bands, or per octave band), with
background noise ``noise_db`` (dB SPL, one value or one per band), as the
coverage maps take them, weighted for a male or female ``talker``; the STI and
STIPA are NaN when a band from 125 Hz up has no level (its G is undefined).
``parameters`` are this response's, when already at hand."""
params = self.parameters() if parameters is None else parameters
return self._speech(self.octave_energy(), level_db, noise_db, params, talker)
def _speech(
self, energy: np.ndarray, level_db, noise_db, params: iso3382.RoomParameters, talker
) -> iso3382.SpeechParameters:
""":meth:`speech` from the echogram ``energy`` in octave bands and its
parameters ``params``."""
level = self.levels(level_db, params)
signal = np.where(np.isfinite(level), level, -100.0)
# No STI without the level of each of its bands, 125 Hz to 8 kHz.
sti, stipa = (
iso3382.speech_transmission_index(
energy,
self.time_step,
signal_db=signal,
noise_db=noise_db,
stipa=short,
talker=talker,
)
if np.isfinite(level[1:]).all()
else math.nan
for short in (False, True)
)
u50 = iso3382.useful_to_detrimental(params.d50, signal, noise_db)
return iso3382.SpeechParameters(sti=sti, stipa=stipa, u50=u50, signal_db=level)
[docs]
def levels_and_speech(
self,
level_db: float | Sequence[float] = 94.0,
noise_db: float | Sequence[float] | None = None,
talker: iso3382.Talker = "male",
parameters: iso3382.RoomParameters | None = None,
energy: np.ndarray | None = None,
) -> iso3382.Levels:
"""The levels and speech results at the listener for a source of sound power
``level_db`` (dB re 1 pW, in all or per octave band), as a run's report gives
them: :meth:`levels_or_held` and its A-weighted sum; the STI, STIPA and U50 of
:meth:`speech` with background noise ``noise_db`` for ``talker``; and
:meth:`relative_to_free_field`, with its A-weighted value (the A-weighted level
less that of the same source in free field). ``parameters`` are this
response's, and ``energy`` its :meth:`octave_energy`, when already at hand."""
params = self.parameters(energy) if parameters is None else parameters
energy = self.octave_energy() if energy is None else energy
return self._levels_and_speech(energy, level_db, noise_db, talker, params)
def _levels_and_speech(
self, energy: np.ndarray, level_db, noise_db, talker, params: iso3382.RoomParameters
) -> iso3382.Levels:
""":meth:`levels_and_speech` from the echogram ``energy`` in octave bands and
its parameters ``params``."""
spl = self._levels_or_held(level_db, params, energy)
speech = self._speech(energy, level_db, noise_db, params, talker)
relative = self._relative_to_free_field(energy)
total = iso3382.a_weighted(spl)
# In a band no sound arrives in (a level of -inf) the level in free field
# cannot be read back from the level: the A-weighted value is then NaN.
with np.errstate(invalid="ignore"):
relative_a = total - iso3382.a_weighted(spl - relative)
return iso3382.Levels(
spl=spl,
spl_a=total,
sti=speech.sti,
stipa=speech.stipa,
u50=speech.u50,
re_free_field=relative,
re_free_field_a=relative_a,
)
[docs]
def level_errors(
self,
level_db: float | Sequence[float] = 94.0,
noise_db: float | Sequence[float] | None = None,
talker: iso3382.Talker = "male",
) -> iso3382.Levels | None:
"""The standard error of each of :meth:`levels_and_speech` from the late rays'
batches, by the jackknife of :meth:`standard_errors`: NaN where some batch
leaves the value undefined or infinite, None without 2 batches or more. Where
G is defined, a band's level is its G and the source's power, so its error is
G's; where it is not, the level is that of the energy held
(:meth:`levels_or_held`) and has an error of its own."""
values = [
self._levels_and_speech(energy, level_db, noise_db, talker, self._parameters(energy))
for energy in self._without_each_batch()
]
if not values:
return None
errors: dict[str, Any] = {}
for f in dataclasses.fields(iso3382.Levels):
error = _jackknife([getattr(v, f.name) for v in values])
errors[f.name] = error if error.ndim else float(error)
return iso3382.Levels(**errors)
[docs]
def impulse_response(self, sample_rate: int = 48_000, seed: int | None = None) -> np.ndarray:
"""Mono impulse response; the direct sound at r metres is an impulse of height 1 / r.
Early paths become fractional-delay impulses filtered per band, in the lowest
bands with the phase of their reflections
(:mod:`~acoustic_spaces.engine.coherent`), in turbulence as at one moment
(:meth:`moment`); the late energy drives a random-sign
Dirac sequence with the density of reflections in the room.
From 50 ms after the direct sound the late energy is smoothed over 10 ms first,
so a single strong ray late in the tail does not become a click. The wave
solver's bands, when it ran, take the place of the lowest ones: through the
crossover the early paths make way for them in pressure and the noise, which
does not interfere with them, in energy (``WaveResponse.high_pass``).
"""
n = int(math.ceil(self.length_s * sample_rate))
scale = synthesis.ENERGY_TO_IR
paths = coherent.with_own_phases(self.moment(seed), self.seed if seed is None else seed)
band_signals, quadrature = coherent.band_impulses(paths, n, sample_rate)
low = coherent.signal(paths, n, sample_rate)[:, 0]
noise_signals = np.zeros_like(band_signals)
if np.any(self.late > 0):
rng = np.random.default_rng(self.seed if seed is None else seed)
noise = synthesis.dirac_sequence(
n, sample_rate, self.volume_m3, self.speed_of_sound, rng, self.time_step
)
late = synthesis.smooth_energy(
self.late, self.time_step, self.direct_delay_s + SMOOTH_AFTER_S
)
noise_signals = synthesis.shape_noise(scale * late, self.time_step, noise, sample_rate)
if self.wave is None:
return (
synthesis.combine_bands(band_signals + noise_signals, sample_rate, quadrature) + low
)
# The wave bands take the early paths' place in pressure, the noise's in energy.
early = synthesis.combine_bands(band_signals, sample_rate, quadrature) + low
early = self.wave.high_pass(early, sample_rate)
noise = synthesis.combine_bands(noise_signals, sample_rate)
late = self.wave.high_pass(noise, sample_rate, late=True)
return early + late + self.wave.field(sample_rate, n)[:, 0]
[docs]
def moment(self, seed: int | None = None) -> EarlyReflections:
"""The early paths at a moment of the turbulent air, drawn with ``seed``
(default the response's): outdoors in turbulence the eddies delay each path at
random, and an impulse response is one moment of them, whose levels scatter
about the echogram's average. Without turbulence, the early paths."""
return self.early.frozen(self.seed if seed is None else seed)
[docs]
def spatial_impulse_response(
self, fmt, sample_rate: int = 48_000, seed: int | None = None, *, threads: int = 1
) -> np.ndarray:
"""Impulse responses (samples, channels) in a format of
:mod:`acoustic_spaces.spatial`: ``Ambisonics(order)``, ``Loudspeakers.layout(name)``,
``Binaural(hrtf)`` or ``Mono()``, its channels rendered on ``threads`` threads
(the same result with any number; at most the computer's cores)."""
from acoustic_spaces.spatial.render import spatial_impulse_response
return spatial_impulse_response(self, fmt, sample_rate, seed, threads=threads)
class _LateArray:
"""One of a :class:`Response`'s ``LATE_ARRAYS``, kept under the field's name among
the response's own attributes: read, it is the array given, or what the
:class:`Deferred` given makes. The array made last is kept with a weak reference to
its :class:`Deferred`, which keeps none of what it is made from and lets the array
go with it, so that reading the field of one response again and again makes it
once."""
def __init__(self, name: str) -> None:
self.name = name
self._last: tuple[weakref.ref[Deferred], np.ndarray] | None = None
def __get__(self, response: Response | None, owner: type | None = None) -> np.ndarray:
# Without a response (the class asked), there is no such attribute, as for a
# dataclass's field without a default value or with a factory for one.
held = None if response is None else vars(response).get(self.name)
if held is None:
raise AttributeError(self.name)
if not isinstance(held, Deferred):
return held
last = self._last
if last is not None and last[0]() is held:
return last[1]
made = held.make()
self._last = (weakref.ref(held, self._forget), made)
return made
def _forget(self, gone: weakref.ref[Deferred]) -> None:
last = self._last
if last is not None and last[0] is gone:
self._last = None
def __set__(self, response: Response, value: np.ndarray | Deferred) -> None:
vars(response)[self.name] = value
for _name in LATE_ARRAYS:
setattr(Response, _name, _LateArray(_name))
def _jackknife(replicas) -> np.ndarray:
"""The standard error of a value from its ``replicas`` (n, ...), each found without
one of n batches: their spread, times (n - 1) / n under the root. NaN where a
replica is undefined or infinite (no spread to a clarity of inf)."""
replicas = np.array(replicas, dtype=float)
replicas[~np.isfinite(replicas)] = math.nan
n = len(replicas)
spread = ((replicas - replicas.mean(axis=0)) ** 2).sum(axis=0)
return np.sqrt((n - 1) / n * spread)
def _delayed(x: np.ndarray, slots: float) -> np.ndarray:
"""``x`` with its last axis (time slots) ``slots`` later, a fraction of a slot
shared between the two slots it falls between; as long as it needs to be."""
if slots <= 0:
return x
whole = int(math.floor(slots))
part = slots - whole
pad = [(0, 0)] * (x.ndim - 1)
out = np.pad(x, [*pad, (whole, 1)]) * (1.0 - part)
out[..., 1:] += np.pad(x, [*pad, (whole, 0)]) * part
return out
__all__ = ["LATE_ARRAYS", "Deferred", "Response"]