Source code for acoustic_spaces.calibration

"""Material calibration: absorption fitted to the parameters measured in a room.

A model of an existing room starts from absorption coefficients out of tables, which
seldom match the room as built. :func:`calibrate` adjusts the absorption of the
materials named, octave band by octave band, until the simulated parameters (T30, EDT
and C80 by default) at each measured source and listener pair come as close as they can
to those measured, in just noticeable differences (ISO 3382-1, annex A, and by analogy
for T30; see :data:`~acoustic_spaces.compare.JND`).

It does not trace the room again for every trial. Each round traces it once, keeping
the reflections each ray had off each material
(:mod:`~acoustic_spaces.engine.reweight`); the responses for other absorption then come
from re-weighting those rays, so a least-squares fit per band
(:func:`scipy.optimize.least_squares`) costs little more than computing the parameters.
The next round traces again at the absorption found, until it moves by less than
``tolerance``; a last trace gives the parameters reported after the fit.

Measurements seldom pin down every material: what they fix best is the total absorption,
and two surfaces that the sound meets in much the same way (a ceiling and a floor of a
flat room, say) trade absorption freely. So the materials keep their proportions unless
the measurements ask otherwise: the fit is free to scale every material's absorption by
a common factor, but a material that moves by a factor more than the others costs as
much as missing a parameter, one JND for each factor of ``PRIOR_FACTOR``. Without
measurements that tell the materials apart this is the fit of a single factor per band,
as fitting a diffuse-field formula to the reverberation time does.
:attr:`Calibration.uncertainty` says, per material and band, how far its absorption
could move, the other materials following it, before the sum of the squared misses
grows by one JND squared (its standard error): what the measurements leave open.
"""

from __future__ import annotations

import math
from collections.abc import Callable, Mapping, Sequence
from dataclasses import dataclass, field
from pathlib import Path

import numpy as np

from acoustic_spaces import parameters as iso3382
from acoustic_spaces import products
from acoustic_spaces.compare import JND
from acoustic_spaces.engine import reweight
from acoustic_spaces.engine.coherent import EarlyPressure, filtered_bands, with_mean_phases
from acoustic_spaces.engine.late import MAX_GROUPS
from acoustic_spaces.engine.response import Response
from acoustic_spaces.engine.simulate import _as_room, simulate
from acoustic_spaces.materials.bands import OCTAVE_BANDS_HZ
from acoustic_spaces.parameters import RoomParameters
from acoustic_spaces.room import Room
from acoustic_spaces.scene import Scene

#: The parameters fitted unless others are named.
DEFAULT_PARAMETERS: tuple[str, ...] = ("t30", "edt", "c80")
#: A material whose absorption moves by this factor more than the others' does costs as
#: much as missing one parameter by one JND.
PRIOR_FACTOR = 2.0
#: The step (in absorption) of the finite differences behind the fit and its
#: uncertainty.
_STEP = 0.01

Pair = tuple[str, str]


[docs] @dataclass class Calibration: """What :func:`calibrate` found: the absorption per material and octave band, and the parameters before and after, against those measured.""" scene: Scene # the scene as it was materials: list[str] parameters: tuple[str, ...] initial: np.ndarray # (materials, bands) absorption: np.ndarray # (materials, bands), fitted #: (materials, bands) the standard error of each material's absorption, for misses #: of one JND: how far it can move, the others following it, before the sum of the #: squared misses grows by one JND squared. It is what the measurements leave open. #: Above 0.1 or so they hardly constrain it. uncertainty: np.ndarray measured: dict[Pair, RoomParameters] before: dict[Pair, RoomParameters] after: dict[Pair, RoomParameters] rounds: int # traces at new absorption, the last one included bands_hz: tuple[int, ...] = OCTAVE_BANDS_HZ details: dict[str, float] = field(default_factory=dict)
[docs] def fitted_scene(self) -> Scene: """A copy of the scene with the fitted absorption.""" return with_absorption(self.scene, self.materials, self.absorption)
[docs] def errors(self, which: str = "after") -> dict[str, np.ndarray]: """Per fitted parameter, the mean absolute difference from the measurements in JNDs per band over the pairs (NaN where no pair has both values); ``which`` is "before" or "after".""" simulated = {"before": self.before, "after": self.after}[which] out = {} for name in self.parameters: rows = [ np.abs(_jnd_differences(name, getattr(simulated[p], name), getattr(m, name))) for p, m in self.measured.items() ] with np.errstate(invalid="ignore"): stacked = np.array(rows) count = np.isfinite(stacked).sum(axis=0) total = np.nansum(stacked, axis=0) out[name] = np.where(count > 0, total / np.maximum(count, 1), math.nan) return out
[docs] def table(self) -> str: """The fitted absorption, what it started from, its uncertainty and the errors before and after, as text.""" bands = "".join(f"{iso3382._band_label(f):>8}" for f in self.bands_hz) width = max(12, *(len(m) for m in self.materials)) lines = [f"{'absorption':<{width}}{bands}"] for k, name in enumerate(self.materials): lines.append(f"{name:<{width}}" + "".join(f"{v:8.2f}" for v in self.absorption[k])) was = "".join(f"{v:8.2f}" for v in self.initial[k]) lines.append(f"{' was':<{width}}{was}") marks = "".join( f"{v:8.2f}" if np.isfinite(v) and v < 10 else f"{'-':>8}" for v in self.uncertainty[k] ) lines.append(f"{' +-':<{width}}{marks}") lines.append("") lines.append(f"{'mean |error|':<{width}}{bands} (JND)") before, after = self.errors("before"), self.errors("after") for name in self.parameters: for label, errors in (("before", before), ("after", after)): row = "".join(f"{v:8.2f}" if np.isfinite(v) else f"{'-':>8}" for v in errors[name]) lines.append(f"{iso3382._symbol(name) + ' ' + label:<{width}}{row}") return "\n".join(lines)
def as_dict(self) -> dict: def plain(a: np.ndarray): return [None if not math.isfinite(v) else round(float(v), 6) for v in a] return { "materials": { name: { "absorption": plain(self.absorption[k]), "initial": plain(self.initial[k]), "uncertainty": plain(self.uncertainty[k]), } for k, name in enumerate(self.materials) }, "parameters": list(self.parameters), "bands_hz": list(self.bands_hz), "errors_jnd": { which: {name: plain(v) for name, v in self.errors(which).items()} for which in ("before", "after") }, "rounds": self.rounds, "pairs": { f"{source} {listener}": { side: { name: plain(getattr(values[source, listener], name)) for name in self.parameters } for side, values in ( ("measured", self.measured), ("before", self.before), ("after", self.after), ) } for source, listener in self.measured }, "details": self.details, }
[docs] def with_absorption(scene: Scene, materials: Sequence[str], absorption: np.ndarray) -> Scene: """A copy of ``scene`` whose ``materials`` take ``absorption`` (materials, octave bands), as calibrated to measurements (:func:`~acoustic_spaces.engine.reweight.with_absorption`).""" return reweight.with_absorption( scene, materials, absorption, "absorption calibrated to measurements" )
def _jnd_differences(name: str, simulated, measured) -> np.ndarray: """(simulated - measured) in JNDs, NaN where either is missing.""" s, m = (np.asarray(v, dtype=float) for v in (simulated, measured)) step, relative = JND[name] jnd = step * np.abs(m) if relative else np.full(m.shape, step) out = np.full(m.shape, math.nan) ok = np.isfinite(s) & np.isfinite(m) & (jnd > 0) out[ok] = (s[ok] - m[ok]) / jnd[ok] return out @dataclass class _Band: """One response's energy in one band, ready to re-weight.""" slots: int time_step: float onset: float reference: float early_slot: np.ndarray # (paths,) early_energy: np.ndarray # (paths,) counts: np.ndarray # (paths, groups) late: np.ndarray # (slots,) mean: np.ndarray # (groups, moment slots) second: np.ndarray # (groups, groups, moment slots): E[n_i n_j] moment_slot: np.ndarray # (slots,) the moment slot of each slot #: Where the early paths add in pressure (:mod:`~acoustic_spaces.engine.coherent`): #: the reflection counts (U, groups) the paths come in, the pressure of each set #: of paths alike through the band's filter (U, samples), the slot of each sample #: and the factor from squared pressure to energy; else None. pressure: tuple[np.ndarray, np.ndarray, np.ndarray, float] | None = None @classmethod def of(cls, response: Response, band: int, groups: int, face_group: np.ndarray) -> _Band: step = response.time_step slots = int(math.ceil(response.length_s / step - 1e-9)) early = response.early index = np.maximum(early.delay_s / step, 0.0).astype(np.int64) # as the echogram keep = index < slots every = reweight.path_counts(early, face_group, groups) counts = every[keep] pressure = None if band < filtered_bands(early) and len(early): # Paths that reflect alike re-weight alike: their pressure is summed once. alike, label = np.unique(every, axis=0, return_inverse=True) weights = np.zeros((len(early), len(alike))) weights[np.arange(len(early)), label.reshape(-1)] = 1.0 signals = EarlyPressure(with_mean_phases(early), weights).band( band, step, slots, start=response.direct_delay_s ) pressure = (alike, *signals) moments = response.late_moments[:, band] # (terms, moment slots) total = moments[0] safe = np.where(total > 0.0, total, 1.0) mean = np.where(total > 0.0, moments[1 : 1 + groups] / safe, 0.0) second = np.zeros((groups, groups, moments.shape[1])) t = 1 + groups for i in range(groups): for j in range(i, groups): second[i, j] = second[j, i] = np.where(total > 0.0, moments[t] / safe, 0.0) t += 1 late = np.zeros(slots) n = min(slots, response.late.shape[1]) late[:n] = response.late[band, :n] moment_slot = ((np.arange(slots) + 0.5) * step / response.moment_step).astype(np.int64) return cls( slots=slots, time_step=step, onset=response.direct_delay_s, reference=float(response._reference()[band]), early_slot=index[keep], early_energy=early.energy[keep, band], counts=counts, late=late, mean=mean, second=second, moment_slot=np.minimum(moment_slot, moments.shape[1] - 1), pressure=pressure, ) def energy(self, ratio: np.ndarray) -> np.ndarray: """(slots,) the echogram for the change per reflection ``ratio`` (groups,).""" covariance = self.second - self.mean[:, None] * self.mean[None, :] exponent = ratio @ self.mean + 0.5 * np.einsum("i,ijs,j->s", ratio, covariance, ratio) out = self.late * np.exp(np.minimum(exponent, 50.0))[self.moment_slot] if self.pressure is not None: alike, pressure, slot, scale = self.pressure p = products.product(np.exp(0.5 * products.product(alike, ratio)), pressure) return out + np.bincount(slot, weights=scale * p**2, minlength=self.slots)[: self.slots] early = self.early_energy * np.exp(products.product(self.counts, ratio)) return out + np.bincount(self.early_slot, weights=early, minlength=self.slots) def parameters(self, ratio: np.ndarray) -> RoomParameters: return iso3382.from_energy( self.energy(ratio)[None], self.time_step, self.onset, reference_energy=self.reference ) def _initial_absorption(room: Room, materials: Sequence[str]) -> np.ndarray: scene = room.scene return np.array([scene.materials[m].coefficients("octave")[0] for m in materials]) def _lowest(room: Room, materials: Sequence[str], low: float) -> np.ndarray: """(materials, bands) the least absorption each may take: ``low``, or what it lets through where that is more (in the third octave of the band that lets most through).""" out = np.full((len(materials), len(OCTAVE_BANDS_HZ)), low) for k, name in enumerate(materials): passing = room.scene.materials[name].transmission_coefficients("third_octave") if passing is not None: most = np.asarray(passing).reshape(-1, 3).max(axis=1) out[k] = np.maximum(out[k], most + 1e-6) return out def _default_materials(room: Room) -> list[str]: used = sorted(set(np.asarray(room.face_materials)[np.asarray(room.face_materials) >= 0])) names = [room.material_names[k] for k in used] # Openings reflect nothing: there is nothing to fit; an impedance gives its own. materials = room.scene.materials return [ n for n in names if min(materials[n].coefficients("octave")[0]) < 1.0 and materials[n].impedance is None ] def jacobian_of(function, x: np.ndarray, lowest: np.ndarray, upper: np.ndarray) -> np.ndarray: """Central differences of ``function`` a step of absorption (``_STEP``) apart, kept within the bounds. The parameters come from decay curves sampled every millisecond, which jump by tiny amounts as slots cross the levels they are read at: smaller steps would see only those jumps.""" columns = [] for m in range(len(x)): up, down = x.copy(), x.copy() up[m] = min(x[m] + _STEP, upper[m]) down[m] = max(x[m] - _STEP, lowest[m]) columns.append((function(up) - function(down)) / (up[m] - down[m])) return np.array(columns).T def _fit_band( prepared: dict[Pair, _Band], targets: dict[Pair, list[float]], parameters: tuple[str, ...], start: np.ndarray, prior: np.ndarray, lowest: np.ndarray, high: float, ) -> tuple[np.ndarray, np.ndarray] | None: """One band's absorption per material, re-weighting the rays traced at ``start``, and its uncertainty; None when nothing was measured in the band.""" from scipy.optimize import least_squares def misses(x: np.ndarray) -> np.ndarray: ratio = np.log1p(-x) - np.log1p(-start) out = [] for p, band in prepared.items(): found = band.parameters(ratio) for name, target in zip(parameters, targets[p], strict=True): value = float(getattr(found, name)[0]) step, relative = JND[name] jnd = step * abs(target) if relative else step if math.isfinite(target) and jnd > 0: # A response too short or too flat for the parameter misses it by much. out.append((value - target) / jnd if math.isfinite(value) else 10.0) return np.array(out) if len(misses(start)) == 0: return None reference = np.log(np.maximum(prior, lowest)) def residuals(x: np.ndarray) -> np.ndarray: scaled = np.log(x) - reference return np.concatenate([misses(x), (scaled - scaled.mean()) / math.log(PRIOR_FACTOR)]) upper = np.full(len(start), high) x0 = np.clip(start, lowest, upper) solution = least_squares( residuals, x0, jac=lambda x: jacobian_of(residuals, x, lowest, upper), bounds=(lowest, upper), ) # The standard error of each material, for misses of one JND: how far it can move, # the others following, before the sum of the squared misses grows by one JND squared. data = jacobian_of(misses, solution.x, lowest, upper) try: spread = np.sqrt(np.maximum(np.diag(np.linalg.inv(products.product(data.T, data))), 0.0)) except np.linalg.LinAlgError: spread = np.full(len(start), math.inf) return solution.x, spread
[docs] def calibrate( room: Room | Scene | str | Path, measured: Mapping[Pair, RoomParameters], materials: Sequence[str] | None = None, *, parameters: Sequence[str] = DEFAULT_PARAMETERS, rounds: int = 4, bounds: tuple[float, float] = (0.01, 0.99), tolerance: float = 0.01, threads: int | None = None, progress: Callable[[str], None] | None = None, ) -> Calibration: """Fit the absorption of ``materials`` (default: every material on a surface but openings, at most 16) so that the simulated ``parameters`` (edt, t20, t30, c50, c80, d50, ts and g) match those ``measured`` at each (source, listener) pair of the scene, band by band, in JNDs. The scene's simulation settings (rays, response length, seed, and threads unless ``threads`` is given) are used, with stochastic ray tracing in octave bands and no wave solver. At most ``rounds`` traces at new absorption are made; it stops sooner once no value moves by more than ``tolerance``. Absorption stays within ``bounds`` (the lower one above 0, as the prior takes the logarithm of the absorption), and above what a material lets through. """ room = _as_room(room) scene = room.scene say = progress or (lambda _: None) sim = scene.simulation if sim.late.method != "stochastic_ray_tracing": raise ValueError("calibration re-weights traced rays: use stochastic ray tracing") if sim.bands != "octave": raise ValueError("calibration works in octave bands: set simulation bands to octave") if sim.wave.enabled: raise ValueError("calibration re-weights rays; switch the wave solver off for it") if room.outdoor is not None: raise ValueError("calibration fits a room's absorption to how it decays; not outdoors") # The re-weighted echogram has no directions: no LF, LFC, IACC or directional decay times. fitted = [n for n in JND if n in iso3382.PARAMETERS] unknown = [n for n in parameters if n not in fitted] if unknown: raise ValueError(f"cannot fit {', '.join(unknown)}; choose from {', '.join(fitted)}") parameters = tuple(parameters) pairs = list(measured) if not pairs: raise ValueError("no measurements to fit") for p in pairs: for name in parameters: if np.shape(getattr(measured[p], name)) != (len(OCTAVE_BANDS_HZ),): raise ValueError( f"the measured {name} of {p[0]}/{p[1]} is not in octave bands " f"({len(OCTAVE_BANDS_HZ)} values, 63 Hz to 8 kHz)" ) sources = {s.name for s in scene.sources} listeners = {lis.name for lis in scene.listeners} missing = [f"{s}/{lis}" for s, lis in pairs if s not in sources or lis not in listeners] if missing: raise ValueError(f"the scene has no source and listener for {', '.join(missing)}") named = materials is not None materials = list(materials) if named else _default_materials(room) if not materials: raise ValueError("no material to fit") if len(materials) > MAX_GROUPS: where = "named" if named else "on the surfaces" raise ValueError( f"at most {MAX_GROUPS} materials at once ({len(materials)} {where}); " "name the ones to fit" ) reweight.face_groups(room, materials) # each known, and named once grounds = [m for m in materials if scene.materials[m].impedance is not None] if grounds: raise ValueError( f"{', '.join(grounds)} take their absorption from an impedance; calibration " "fits absorption coefficients" ) on_faces = {room.material_names[k] for k in np.unique(room.face_materials) if k >= 0} unused = [m for m in materials if m not in on_faces] if unused: raise ValueError(f"no surface has the material {', '.join(unused)}") if rounds < 1: raise ValueError("calibration needs at least one round") low, high = bounds if not 0.0 < low < high < 1.0: raise ValueError("bounds must be 0 < low < high < 1") groups = len(materials) initial = _initial_absorption(room, materials) lowest = _lowest(room, materials, low) current = np.clip(initial, lowest, high) used_sources = sorted({s for s, _ in pairs}) used_listeners = sorted({lis for _, lis in pairs}) def trace(absorption: np.ndarray, label: str): """The responses at ``absorption``, with the absorption traced (rounded, and averaged from third octaves).""" say(f"Calibration: {label}") traced = Room.from_scene(with_absorption(scene, materials, absorption)) face_group = reweight.face_groups(traced, materials) result = simulate( traced, sources=used_sources, listeners=used_listeners, threads=threads, groups=face_group, ) actual = _initial_absorption(traced, materials) return face_group, {p: result[p] for p in pairs}, actual def fit(face_group, responses, around: np.ndarray) -> tuple[np.ndarray, np.ndarray]: fitted = around.copy() spread = np.full(around.shape, math.nan) for b in range(len(OCTAVE_BANDS_HZ)): prepared = {p: _Band.of(r, b, groups, face_group) for p, r in responses.items()} targets = { p: [float(getattr(measured[p], name)[b]) for name in parameters] for p in pairs } found = _fit_band( prepared, targets, parameters, around[:, b], initial[:, b], lowest[:, b], high ) if found is not None: fitted[:, b], spread[:, b] = found return fitted, spread face_group, responses, current = trace(current, "tracing at the starting absorption") before = {p: r.parameters() for p, r in responses.items()} done = 0 change = math.nan uncertainty = np.full(current.shape, math.nan) for k in range(rounds): say(f"Calibration: fitting, round {k + 1}") fitted, uncertainty = fit(face_group, responses, current) change = float(np.max(np.abs(fitted - current))) current = fitted done += 1 face_group, responses, current = trace( current, f"tracing at the fitted absorption ({done})" ) if change < tolerance: break after = {p: r.parameters() for p, r in responses.items()} return Calibration( scene=scene, materials=materials, parameters=parameters, initial=initial, absorption=current, uncertainty=uncertainty, measured=dict(measured), before=before, after=after, rounds=done, details={"last_change": change}, )
__all__ = [ "DEFAULT_PARAMETERS", "PRIOR_FACTOR", "Calibration", "calibrate", "with_absorption", ]