"""Locally reacting surfaces for the wave solver: frequency-dependent admittances fitted
to a material's absorption coefficients.
A material table gives each band's random-incidence absorption. The wave solver needs
the surface's specific admittance (the normal velocity times rho c over the pressure),
as a function of frequency it can step in time. :class:`Admittance` is a constant
conductance beta plus parallel mass-resistance-stiffness branches,
Y(s) = beta + sum_j 1 / (M_j s + R_j + S_j / s),
each resonant (at f_j, with quality factor Q_j) and passive, so the scheme stays stable
whatever the values. :func:`fit_admittance` chooses beta and the branches so that the
random-incidence absorption of Y (Paris's formula for a locally reacting surface),
counted through the analysis's band filters, matches the material's in every band the
wave solver covers: one branch at each band's centre and one beyond each end. It fits
the admittance the scheme actually has at its time step, which bends a little from Y
towards the grid's Nyquist frequency.
A locally reacting surface absorbs at most :data:`MAX_ABSORPTION` (0.951) at random
incidence; higher coefficients get that. The band filters overlap, so bands whose
coefficients change steeply from one to the next (0.1 to 0.6 in an octave) are matched
only roughly; :attr:`Admittance.achieved` holds what the fit reached.
"""
from __future__ import annotations
import functools
import math
from collections.abc import Callable, Sequence
from dataclasses import dataclass, field
import numpy as np
#: Highest random-incidence absorption a locally reacting surface reaches (Paris's
#: formula), and the normalised impedance that reaches it.
MAX_ABSORPTION = 0.951
_BEST_IMPEDANCE = 1.5672
#: Frequencies per octave the fit evaluates the absorption at.
_PER_OCTAVE = 32
#: The fit frees each branch's quality factor when fixed ones miss by more than this.
_TOLERANCE = 0.005
#: Bounds of the quality factors, and how much it costs (in absorption) to move one by
#: a factor of e from the bands' own.
_QUALITY = (0.5, 10.0)
_QUALITY_COST = 0.02
#: The fit's forward differences step each unknown by this times its size (1 at least):
#: the square root of the machine epsilon, which scipy's ``least_squares`` takes for
#: ``jac="2-point"``.
_STEP = math.sqrt(np.finfo(float).eps)
[docs]
def absorption_of_impedance(impedance: np.ndarray) -> np.ndarray:
"""Random-incidence absorption of a locally reacting surface with a real normalised
impedance (Paris's formula, for a diffuse field)."""
z = np.asarray(impedance, dtype=float)
return 8.0 / z * (1.0 + 1.0 / (1.0 + z) - 2.0 / z * np.log1p(z))
[docs]
def random_incidence_absorption(admittance: np.ndarray) -> np.ndarray:
"""Random-incidence absorption of a locally reacting surface with the complex
specific admittance ``admittance``: Paris's formula, the integral over incidence of
``1 - |R|^2`` weighted by ``sin(2 theta)``, in closed form."""
y = np.asarray(admittance, dtype=complex)
return _paris(y.real, y.imag, np.arctan, np.log)
def _paris(g: np.ndarray, b: np.ndarray, arctan, log) -> np.ndarray:
""":func:`random_incidence_absorption` of the admittances ``g + 1j * b``, with the
arc tangent and the logarithm taken by ``arctan`` and ``log``."""
gg, bb = g * g, b * b
d = g + gg + bb
safe = np.where(d > 0.0, d, 1.0)
x = b / safe
# atan(b / d) / b without dividing by zero for a real admittance.
small = np.abs(x) < 1e-4
ratio = np.where(small, 1.0 - x * x / 3.0, arctan(x) / np.where(small, 1.0, x)) / safe
magnitude = gg + bb
logarithm = log(((1.0 + g) ** 2 + bb) / np.where(magnitude > 0.0, magnitude, 1.0))
alpha = 8.0 * g * (1.0 - g * logarithm + (gg - bb) * ratio)
return np.where(g > 0.0, alpha, 0.0)
def _row_by_row(function):
"""``function`` (a NumPy one of each value) of a 2-D array, taken one row at a time.
NumPy rounds its arc tangent and logarithm as the platform's library does, which
may depend on where a value lies in the array it is given: row by row, each value
lies where it does when its row is given alone."""
def rows(a: np.ndarray) -> np.ndarray:
out = np.empty_like(a)
for row, values in zip(out, a, strict=True):
function(values, out=row)
return out
return rows
[docs]
def admittance(absorption: np.ndarray) -> np.ndarray:
"""Real specific (normalised) admittance of a locally reacting surface whose
random-incidence absorption is ``absorption``: the inverse of Paris's formula, on
the side of hard surfaces. Coefficients from :data:`MAX_ABSORPTION` up get the most
absorbing admittance."""
alpha = np.clip(np.asarray(absorption, dtype=float), 0.0, 1.0)
low = np.full(alpha.shape, math.log(_BEST_IMPEDANCE))
high = np.full(alpha.shape, math.log(1e9))
for _ in range(60): # bisection in log(impedance); absorption falls as it grows
mid = 0.5 * (low + high)
above = absorption_of_impedance(np.exp(mid)) > alpha
low = np.where(above, mid, low)
high = np.where(above, high, mid)
beta = np.exp(-0.5 * (low + high))
return np.where(alpha <= 0.0, 0.0, beta)
def _branch_values(
f: np.ndarray, conductance, quality, frequency, rate: float | None
) -> np.ndarray:
"""The branches' admittances (branches, len(f)): exact, or with ``rate`` the
scheme's at that time step."""
return _with_conductances(conductance, *_branch_terms(f, quality, frequency, rate))
def _branch_terms(
f: np.ndarray, quality, frequency, rate: float | None
) -> tuple[np.ndarray | None, np.ndarray]:
"""What of the branches' admittances does not depend on their conductances: the
numerator (None: 1) and the denominator of the admittance of each branch at
conductance 1, for :func:`_with_conductances`."""
w = 2.0 * np.pi * np.asarray(f, dtype=float)[None, :]
q = np.asarray(quality, float)[:, None]
w0 = 2.0 * np.pi * np.asarray(frequency, float)[:, None]
if rate is None:
return None, 1.0 + 1j * q * (w / w0 - w0 / w)
# m (z - 2 + 1/z) W + r (z - 1/z) W / 2 + q (z + 1/z) W / 2 = (z - 1/z) P / 2, with
# M = Q R / w0, S = Q R w0 and R = 1 / conductance; divided through by R.
t = 1.0 / rate
s, c = np.sin(w * t), np.cos(w * t)
half = np.sin(0.5 * w * t) ** 2
return 1j * s, -4.0 * q / (w0 * t) * half + 1j * s + q * w0 * t * c
def _with_conductances(
conductance, numerator: np.ndarray | None, denominator: np.ndarray
) -> np.ndarray:
"""The branches' admittances (branches, frequencies) at the conductances
``conductance``, from :func:`_branch_terms`."""
gamma = np.asarray(conductance, float)[:, None]
if numerator is None:
return gamma / denominator
return numerator * gamma / denominator
def _relaxation_values(f: np.ndarray, conductance, corner, rate: float | None) -> np.ndarray:
"""The admittances (branches, len(f)) of branches without mass, 1 / (R + S / s),
of conductance 1 / R and corner frequency S / (2 pi R): exact, or with ``rate`` the
scheme's at that time step."""
w = 2.0 * np.pi * np.asarray(f, dtype=float)[None, :]
gamma = np.asarray(conductance, float)[:, None]
wc = 2.0 * np.pi * np.asarray(corner, float)[:, None]
if rate is None:
return gamma * 1j * w / (1j * w + wc)
# r (z - 1/z) W / 2 + q (z + 1/z) W / 2 = (z - 1/z) P / 2, with q = S T.
t = 1.0 / rate
s, c = np.sin(w * t), np.cos(w * t)
return gamma * 1j * s / (1j * s + wc * t * c)
[docs]
@dataclass(frozen=True)
class Admittance:
"""A locally reacting surface's specific admittance: ``beta`` plus one resonant
branch per entry of ``conductance`` (its admittance at resonance, 1 / R), ``quality``
and ``frequency_hz``, and one branch without mass per entry of ``relaxation`` (its
admittance at high frequencies, 1 / R) and ``relaxation_hz`` (its corner frequency,
S / (2 pi R)), as a porous ground's admittance needs."""
beta: float
conductance: np.ndarray = field(default_factory=lambda: np.zeros(0))
quality: np.ndarray = field(default_factory=lambda: np.zeros(0))
frequency_hz: np.ndarray = field(default_factory=lambda: np.zeros(0))
#: The band absorption the fit reached, or None when not fitted.
achieved: np.ndarray | None = None
relaxation: np.ndarray = field(default_factory=lambda: np.zeros(0))
relaxation_hz: np.ndarray = field(default_factory=lambda: np.zeros(0))
def __call__(self, f: np.ndarray, rate: float | None = None) -> np.ndarray:
"""The admittance at frequencies ``f`` (Hz): exact, or with ``rate`` the one the
scheme has at that many steps a second."""
f = np.asarray(f, dtype=float)
branches = _branch_values(
f.ravel(), self.conductance, self.quality, self.frequency_hz, rate
)
out = self.beta + branches.sum(axis=0)
if len(self.relaxation):
out = out + _relaxation_values(
f.ravel(), self.relaxation, self.relaxation_hz, rate
).sum(axis=0)
return out.reshape(f.shape)
[docs]
def branches(self, rate: float) -> np.ndarray:
"""The branches as the wave solver takes them (branches, 3): mass over the time
step, resistance, and stiffness times the time step."""
t = 1.0 / rate
r = 1.0 / np.asarray(self.conductance, float)
w0 = 2.0 * np.pi * np.asarray(self.frequency_hz, float)
q = np.asarray(self.quality, float)
out = np.column_stack([q * r / (w0 * t), r, q * r * w0 * t]).reshape(-1, 3)
if len(self.relaxation):
r = 1.0 / np.asarray(self.relaxation, float)
wc = 2.0 * np.pi * np.asarray(self.relaxation_hz, float)
out = np.vstack([out, np.column_stack([np.zeros(len(r)), r, r * wc * t])])
return out
[docs]
def band_weights(f: np.ndarray, bands: int, total: int) -> np.ndarray:
"""How much each of the frequencies ``f`` (on a log grid) counts in each of the
lowest ``bands`` of the ``total`` (8 octave or 24 third-octave) bands (bands,
len(f)): the energy of white noise through the analysis's band filters."""
from acoustic_spaces.materials.bands import BANDS_PER_OCTAVE, exact_centres, resolution_of
from acoustic_spaces.parameters import FILTER_ORDER, OCTAVE_RATIO
resolution = resolution_of(total)
fm = exact_centres(resolution)[:bands, None]
half = OCTAVE_RATIO ** (0.5 / BANDS_PER_OCTAVE[resolution])
width = half - 1.0 / half
gains = f / (1.0 + ((f / fm - fm / f) / width) ** (2 * FILTER_ORDER)) # |H|^2 df
return gains / gains.sum(axis=1, keepdims=True)
def _frequencies(bands: int, total: int) -> np.ndarray:
from acoustic_spaces.materials.bands import exact_centres, resolution_of
fm = exact_centres(resolution_of(total))[:bands]
lo, hi = fm[0] / 4.0, fm[-1] * 4.0
return np.geomspace(lo, hi, int(round(_PER_OCTAVE * math.log2(hi / lo))) + 1)
[docs]
def band_absorption(
admittance: Admittance, bands: int, total: int, rate: float | None = None
) -> np.ndarray:
"""The random-incidence absorption of ``admittance`` in the lowest ``bands`` of the
``total`` bands, counted as :func:`fit_admittance` counts it."""
f = _frequencies(bands, total)
return band_weights(f, bands, total) @ random_incidence_absorption(admittance(f, rate))
def _forward_steps(x: np.ndarray, lower: np.ndarray, upper: np.ndarray) -> np.ndarray:
"""The step of each unknown for the forward differences of a fit between ``lower``
and ``upper``: :data:`_STEP` times its size (1 at least), away from zero, turned
back where it would pass a bound, and to the farther bound where neither way has the
room: the steps scipy's ``least_squares`` takes for ``jac="2-point"``."""
step = _STEP * ((x >= 0).astype(float) * 2 - 1) * np.maximum(1.0, np.abs(x))
below, above = x - lower, upper - x
moved = x + step
outside = (moved < lower) | (moved > upper)
room = np.abs(step) <= np.maximum(below, above)
step[outside & room] *= -1
up = (above >= below) & ~room
step[up] = above[up]
down = (above < below) & ~room
step[down] = -below[down]
return step
def _sums_with_one_changed(rows: np.ndarray, changed: np.ndarray) -> np.ndarray:
"""(n, m) for each k the sum of ``rows`` (n, m) over the first axis with row k
replaced by ``changed[k]``: the rows added one after the other from the first, as
``sum(axis=0)`` adds them, so that each sum is, bit for bit, that of the array with
the row replaced. The rows before the changed one are added once for all."""
partial = np.add.accumulate(rows, axis=0)
out = np.empty_like(rows)
out[0] = changed[0]
for k in range(1, len(rows)):
out[k] = partial[k - 1] + changed[k]
out[:k] += rows[k]
return out
[docs]
def fit_admittance(
absorption: Sequence[float], total: int, rate: float | None = None
) -> Admittance:
"""The admittance whose random-incidence absorption, at ``rate`` steps a second
(None: exactly), matches ``absorption`` in each of the lowest len(absorption) of the
``total`` (8 octave or 24 third-octave) bands."""
target = tuple(float(a) for a in np.clip(np.asarray(absorption, float), 0.0, MAX_ABSORPTION))
return _fit(target, int(total), None if rate is None else float(rate))
class _Misses:
"""What a fit of the lowest bands of the ``total`` to ``goal`` misses by, and its
forward differences. The unknowns are the constant, the branches' conductances
and, when the quality factors are ``free``, their logarithms too (else the bands'
own): calling it gives the misses in each band, with the cost of the quality
factors that are free after them."""
def __init__(self, goal: np.ndarray, total: int, rate: float | None) -> None:
from acoustic_spaces.materials.bands import (
BANDS_PER_OCTAVE,
exact_centres,
resolution_of,
)
self.goal = goal
self.bands = bands = len(goal)
self.rate = rate
resolution = resolution_of(total)
step = 2.0 ** (1.0 / BANDS_PER_OCTAVE[resolution])
fm = exact_centres(resolution)[:bands]
self.resonance = np.concatenate([[fm[0] / step], fm, [fm[-1] * step]])
self.own_quality = 1.0 / (math.sqrt(step) - 1.0 / math.sqrt(step))
self.f = _frequencies(bands, total)
self.weights = band_weights(self.f, bands, total)
self.n = n = len(self.resonance)
self.own = self.own_quality * np.ones(n)
self.log_own = math.log(self.own_quality)
# The branches at the bands' own quality factors, which the fit starts with, are
# the same at every step but for their conductances.
self.own_terms = _branch_terms(self.f, self.own, self.resonance, rate)
self.lower = np.concatenate([np.zeros(1 + n), np.full(n, math.log(_QUALITY[0]))])
self.upper = np.concatenate([np.full(1 + n, np.inf), np.full(n, math.log(_QUALITY[1]))])
def terms(self, x: np.ndarray, free: bool) -> tuple[np.ndarray | None, np.ndarray]:
""":func:`_branch_terms` of the branches at the unknowns ``x``."""
if not free:
return self.own_terms
return _branch_terms(self.f, np.exp(x[1 + self.n :]), self.resonance, self.rate)
def admittance(self, x: np.ndarray, free: bool) -> np.ndarray:
"""(frequencies,) the admittance at the unknowns ``x``."""
n = self.n
return x[0] + _with_conductances(x[1 : 1 + n], *self.terms(x, free)).sum(axis=0)
def __call__(self, x: np.ndarray, free: bool) -> np.ndarray:
found = self.weights @ random_incidence_absorption(self.admittance(x, free))
if not free:
return found - self.goal
cost = _QUALITY_COST * (x[1 + self.n :] - self.log_own)
return np.concatenate([found - self.goal, cost])
def moved(self, x: np.ndarray, free: bool) -> tuple[np.ndarray, np.ndarray]:
"""Each unknown moved by its forward step (``least_squares``' own), and
(unknowns + 1, frequencies) the admittance with each unknown moved in turn,
and last as it is. Moving one unknown changes one branch (the constant, none):
each row takes that branch's values and adds the others, which are the same
for all, in the order :meth:`admittance` adds them."""
n = self.n
step = _forward_steps(x, self.lower[: len(x)], self.upper[: len(x)])
moved = x + step
terms = self.terms(x, free)
rows = _with_conductances(x[1 : 1 + n], *terms)
y = np.empty((len(x) + 1, len(self.f)), dtype=complex)
summed = rows.sum(axis=0)
y[-1] = x[0] + summed
y[0] = moved[0] + summed
changed = _with_conductances(moved[1 : 1 + n], *terms)
y[1 : 1 + n] = x[0] + _sums_with_one_changed(rows, changed)
if free:
changed = _with_conductances(x[1 : 1 + n], *self.terms(moved, free))
y[1 + n : -1] = x[0] + _sums_with_one_changed(rows, changed)
return moved, y
def absorption(self, y: np.ndarray) -> np.ndarray:
"""(rows, frequencies) the random-incidence absorption at the admittances ``y``
(rows, frequencies), by the operations of :func:`random_incidence_absorption`
on each row: the arc tangent and the logarithm are taken row by row, so that
each value lies where it does when its row is worked out alone."""
return _paris(
np.ascontiguousarray(y.real),
np.ascontiguousarray(y.imag),
_row_by_row(np.arctan),
_row_by_row(np.log),
)
def absorbed(self, absorption: np.ndarray) -> np.ndarray:
"""(rows, bands) the absorption in each band of the rows of ``absorption``
(rows, frequencies), each row's by the product :meth:`__call__` takes of its
own."""
return np.array([self.weights @ row for row in absorption])
def slopes(self, x: np.ndarray, free: bool) -> np.ndarray:
"""(misses, unknowns) the misses' forward differences, as ``least_squares``
takes them itself for ``jac="2-point"``: with its steps, and each value by the
operations that give it when the misses are worked out once more for each
unknown, at a fraction of that cost (:meth:`moved`)."""
n, bands = self.n, self.bands
moved, y = self.moved(x, free)
found = self.absorbed(self.absorption(y)) - self.goal
# A row for each unknown, transposed at the end: the layout of least_squares'
# own differences, on which the order its linear algebra adds in depends.
out = np.empty((len(x), bands + (n if free else 0)))
out[:, :bands] = (found[:-1] - found[-1]) / (moved - x)[:, None]
if free:
cost = np.zeros((len(x), n))
cost[1 + n + np.arange(n), np.arange(n)] = _QUALITY_COST * (
moved[1 + n :] - self.log_own
) - _QUALITY_COST * (x[1 + n :] - self.log_own)
out[:, bands:] = cost / (moved - x)[:, None]
return out.T
@functools.lru_cache(maxsize=256)
def _fit(target: tuple[float, ...], total: int, rate: float | None) -> Admittance:
from scipy.optimize import least_squares
goal = np.array(target)
bands = len(goal)
if np.all(goal <= 0.0):
return Admittance(0.0, achieved=np.zeros(bands))
if np.ptp(goal) < 1e-9: # the same in every band: a constant
beta = float(admittance(goal[:1])[0])
out = Admittance(beta)
return Admittance(beta, achieved=band_absorption(out, bands, total, rate))
misses = _Misses(goal, total, rate)
n = misses.n
# Start from the lowest band's constant, each branch adding the rest of its band's.
base = float(admittance(np.array([goal.min()]))[0])
ends = np.concatenate([[goal[0]], goal, [goal[-1]]])
start = np.concatenate([[base], np.maximum(admittance(ends) - base, 1e-4)])
fixed = least_squares(misses, start, jac=misses.slopes, bounds=(0.0, np.inf), args=(False,))
x, quality = fixed.x, misses.own
if np.abs(fixed.fun).max() > _TOLERANCE:
log_q = np.full(n, misses.log_own)
free = least_squares(
misses,
np.concatenate([x, log_q]),
jac=misses.slopes,
bounds=(misses.lower, misses.upper),
args=(True,),
)
if np.abs(free.fun[:bands]).max() < np.abs(fixed.fun).max():
x, quality = free.x[: 1 + n], np.exp(free.x[1 + n :])
used = x[1:] > 1e-9
out = Admittance(float(x[0]), x[1:][used], quality[used], misses.resonance[used])
return Admittance(
out.beta,
out.conductance,
out.quality,
out.frequency_hz,
achieved=band_absorption(out, bands, total, rate),
)
#: Corner frequencies of :func:`fit_impedance`'s branches: this many per octave, from
#: :data:`_RELAXATION_REACH` octaves below the lowest band to as many above the highest.
_RELAXATION_PER_OCTAVE = 1
_RELAXATION_REACH = 3
[docs]
def fit_impedance(
admittance: Callable[[np.ndarray], np.ndarray],
bands: int,
total: int,
rate: float | None = None,
) -> Admittance:
"""The admittance whose value, at ``rate`` steps a second (None: exactly), matches
that of a surface with an impedance, ``admittance(f)`` (normalised, complex, in the
engine's convention, at frequencies f in Hz), over the lowest ``bands`` of the
``total`` bands: its reflection at every angle and its phase, not only its
random-incidence absorption, as a ground's dip needs.
A porous ground's admittance grows with frequency at a nearly constant phase, as no
resonant branch does: the fit is ``beta`` and branches without mass whose corner
frequencies are spread evenly in log frequency, whose sum makes that shape (as a
ladder of resistors and capacitors makes a fractional-order element). With the
corners fixed the admittance is linear in the branches' conductances, which the fit
finds by least squares, at least 0 each, with the misses relative to the
admittance's size."""
from acoustic_spaces.materials.bands import BANDS_PER_OCTAVE, exact_centres, resolution_of
resolution = resolution_of(total)
half = 2.0 ** (0.5 / BANDS_PER_OCTAVE[resolution])
fm = exact_centres(resolution)[:bands]
f = _frequencies(bands, total)
f = f[(f >= fm[0] / half) & (f <= fm[-1] * half)]
target = np.asarray(admittance(f), dtype=complex)
return _fit_values(
tuple(target.real.tolist()),
tuple(target.imag.tolist()),
bands,
int(total),
None if rate is None else float(rate),
)
@functools.lru_cache(maxsize=64)
def _fit_values(
real: tuple[float, ...], imag: tuple[float, ...], bands: int, total: int, rate: float | None
) -> Admittance:
from scipy.optimize import least_squares
from acoustic_spaces.materials.bands import BANDS_PER_OCTAVE, exact_centres, resolution_of
resolution = resolution_of(total)
half = 2.0 ** (0.5 / BANDS_PER_OCTAVE[resolution])
fm = exact_centres(resolution)[:bands]
f = _frequencies(bands, total)
f = f[(f >= fm[0] / half) & (f <= fm[-1] * half)]
target = np.array(real) + 1j * np.array(imag)
scale = np.abs(target) + 1e-3
low = fm[0] / 2.0**_RELAXATION_REACH
octaves = math.log2(fm[-1] / fm[0]) + 2 * _RELAXATION_REACH
corner = low * 2.0 ** (
np.arange(int(round(octaves * _RELAXATION_PER_OCTAVE)) + 1) / _RELAXATION_PER_OCTAVE
)
columns = np.vstack(
[np.ones((1, len(f))), _relaxation_values(f, np.ones(len(corner)), corner, rate)]
)
a = columns.T / scale[:, None] # (frequencies, 1 + branches)
matrix = np.vstack([a.real, a.imag])
goal = np.concatenate([(target / scale).real, (target / scale).imag])
start = np.full(matrix.shape[1], 1e-3)
x = least_squares(lambda x: matrix @ x - goal, start, bounds=(0.0, np.inf)).x
used = x[1:] > 1e-9
out = Admittance(float(x[0]), relaxation=x[1:][used], relaxation_hz=corner[used])
return Admittance(
out.beta,
achieved=band_absorption(out, bands, total, rate),
relaxation=out.relaxation,
relaxation_hz=out.relaxation_hz,
)
__all__ = [
"MAX_ABSORPTION",
"Admittance",
"absorption_of_impedance",
"admittance",
"band_absorption",
"band_weights",
"fit_admittance",
"fit_impedance",
"random_incidence_absorption",
]