"""Re-weighting a traced response for new absorption, without tracing it again.
The energy of every arrival is what left the source that way times, at each reflection,
the share the surface reflects, 1 - a, and factors that do not depend on the absorption
(scattering, air, the source's directivity, what a partition lets through). With other
absorption a', the same paths bring each arrival times the product over its reflections
of (1 - a') / (1 - a). The paths themselves need not be traced again: where a ray goes
depends on the scattering, not on the absorption. (Russian roulette and splitting chose
rays by their energies, but those choices only weight the estimate; it stays unbiased.)
An early reflection off a ground with an impedance is not of this kind: it takes the
impedance's reflection factor in place of 1 - a, and that impedance cannot change
without tracing again (:func:`reweighted_result`). Nor quite one off a ground with
zones, which takes the factors of the grounds its Fresnel zone covers and is
re-weighted as off the ground it meets alone. With source and listener 0.5 and 1.5 m
high and 30 m apart, and a zone without an impedance taken from an absorption of 0.1 to
0.2, a reflection half a metre inside the zone's edge falls by 0.5 dB re-weighted and
by 0.13 to 0.20 dB traced again; half a metre outside it, by none and by 0.11 to
0.16 dB. Nor is the path of the solver for whole rows
(:mod:`~acoustic_spaces.engine.row_paths`): it reflects off no face, and its sound
depends on the absorption of a ground without an impedance through the admittance fitted
to it. A result with such a path is not re-weighted for another absorption of such a
ground (:func:`reweighted_result`); a spread's draws and a calibration's fits, which
re-weight response by response, leave that path as it was traced.
The other early paths carry the faces they reflect off, so their energies re-weight exactly. Where
they add in pressure (:mod:`~acoustic_spaces.engine.coherent`), a reflection also
shifts the phase, by that of its reflection factor, which comes from the admittance
fitted to its face's absorption and the angle it meets the face at; the paths keep
those angles (:attr:`~acoustic_spaces.engine.early.EarlyReflections.cosines`), so their
phases turn to the new absorption's exactly too (:func:`turned_paths`). Of a diffracted
path only the reflections on its way count, not the faces of the edge it bends round,
nor how it interferes with the reflection it shades. The late part's arrivals are far
too many to keep, so the tracer sums, per listener and slot
of ``MOMENT_STEP``, the energy times the reflections each ray has had off each group of
faces and their products (:func:`~acoustic_spaces.engine.late.stochastic_energy` with
``groups``): the energy-weighted mean mu and covariance C of the counts n in the slot.
With l_i = ln((1 - a'_i) / (1 - a_i)) for group i, a slot's energy becomes E exp(K),
K = ln of the mean of exp(n . l) over its arrivals, which mu and C give to second order
in l as mu . l + 1/2 l' C l. That form alone holds near the traced absorption only: for
much more absorption its square term outgrows the first and the energy rises again,
without bound. :func:`moment_exponent` takes instead the form the counts of a diffuse
field lead to. There a ray's N reflections fall on the groups by chance (a multinomial),
and with u_i = exp(l_i) - 1, the change of what group i reflects,
K = N ln(1 + sum_i mu_i u_i / N),
which is Eyring's decay for the new absorption over that for the old. N comes from the
covariance: 1 / N = -mu' F mu / (mu . mu)^2 with F = C - diag(mu), which is -mu mu' / N
for a multinomial. It is held within plus and minus one over the sum of mu: a ray has
had at least the reflections the groups count, and counts that spread wider than by
chance make it negative. What of the covariance it leaves, R = F + mu mu' / N, adds
1/2 w' R w, with w_i = u_i for more absorption and l_i for less. K is then the same to
second order in l as the form above, exact for the same absorption and for counts that
fall by chance, and held to what holds for any counts: at least mu . l (Jensen's
inequality), and no gain where no group reflects more. Further from the traced
absorption it stays an estimate from two moments. In a box of 8 by 6 by 3.5 m traced
with a ceiling that absorbs 0.5 (20 000 rays, at 1 kHz), the late part's decay time for
a ceiling of 0.9 is within 1 % of tracing again, for 0.99 within 5 %, and for 0.1 it is
6 % too short; with a ceiling of 0.85 taken to 0.2, 16 % too short. So
:func:`~acoustic_spaces.calibration.calibrate` traces again at the absorption it arrives
at. Its fit within a round keeps the early paths' phases as traced, which that next
trace turns.
"""
from __future__ import annotations
import dataclasses
from collections.abc import Sequence
import numpy as np
from acoustic_spaces import products
from acoustic_spaces.engine.coherent import SameDelays, absorption_phases, sample_frequencies
from acoustic_spaces.engine.early import EarlyReflections
from acoustic_spaces.engine.late import MAX_GROUPS, MOMENT_STEP
from acoustic_spaces.materials.bands import THIRD_OCTAVE_BANDS_HZ
[docs]
def face_groups(room, materials: Sequence[str]) -> np.ndarray:
"""(faces,) the index in ``materials`` of each face's material, or -1 for faces of
other materials."""
names = list(room.material_names)
unknown = [m for m in materials if m not in names]
if unknown:
raise ValueError(
f"no surface has the material {', '.join(unknown)}; "
f"the model's materials are: {', '.join(names)}"
)
if len(set(materials)) != len(materials):
raise ValueError("each material may be named once")
index = {name: k for k, name in enumerate(materials)}
lookup = np.array([index.get(name, -1) for name in names] + [-1], dtype=np.int64)
return lookup[np.asarray(room.face_materials)]
[docs]
def groups_of(room, settings=None) -> tuple[np.ndarray, list[str]] | None:
"""Face groups to trace ``room`` with so that its absorption can change afterwards
(:func:`reweighted_result`): the group of each face and the materials, those on
surfaces that absorb less than everything in some band (a band in which one absorbs
everything keeps that: no energy is left there to re-weight). None when its
simulation settings (``settings``, default the scene's) do not keep what
re-weighting needs (:func:`cannot_reweight`) or no material is left."""
if cannot_reweight(room, settings) is not None:
return None
materials = reweighted_materials(room)
return (face_groups(room, materials), materials) if materials else None
[docs]
def reweighted_materials(room) -> list[str]:
"""The materials on ``room``'s surfaces that absorb less than everything in some
band: those whose absorption a re-weighting can change."""
used = np.unique(np.asarray(room.face_materials))
names = [room.material_names[k] for k in used if k >= 0]
return [n for n in names if min(room.scene.materials[n].coefficients("octave")[0]) < 1]
[docs]
def cannot_reweight(room, settings=None) -> str | None:
"""Why a run of ``room`` with ``settings`` (default the scene's) cannot be
re-weighted for other absorption, in words that follow "it needs", or None when it
can: another late method, third-octave bands, the wave solver, or more than
``MAX_GROUPS`` materials on its surfaces."""
sim = room.scene.simulation if settings is None else settings
if sim.late.method != "stochastic_ray_tracing":
return "stochastic ray tracing for the late part"
if sim.bands != "octave":
return "octave bands"
if sim.wave.enabled:
return "a run without the wave solver"
count = len(reweighted_materials(room))
if count > MAX_GROUPS:
return f"at most {MAX_GROUPS} materials on the surfaces, and there are {count}"
return None
def with_absorption(
scene, materials: Sequence[str], absorption, source: str, digits: int | None = 4
):
"""A copy of ``scene`` whose ``materials`` take ``absorption`` (for each, its octave
bands), their other properties kept. A material given in third octaves keeps its
shape within each octave: its three values move together, by what the octave does;
one that would pass 1, or fall below what the surface lets through, stays there, and
the octave's others take up what it could not, so that the octave is what was asked.
Given its third-octave values instead, it takes them as they are. Each one's source
then reads ``source``, with what it was after it; the values are rounded to
``digits`` decimals (None: as given)."""
out = scene.model_copy(deep=True)
for name, values in zip(materials, absorption, strict=True):
values = np.asarray(values, dtype=float)
material = out.materials[name]
old = np.asarray(material.absorption, dtype=float)
if len(old) == len(THIRD_OCTAVE_BANDS_HZ) and len(values) != len(old):
passing = material.transmission_coefficients("third_octave")
least = np.zeros(len(old)) if passing is None else np.asarray(passing, dtype=float)
values = _thirds_at(old.reshape(-1, 3), values, least.reshape(-1, 3)).ravel()
was = f"; was: {material.source}" if material.source else ""
out.materials[name] = material.model_copy(
update={
"absorption": [
float(v) if digits is None else round(float(v), digits) for v in values
],
"source": f"{source}{was}",
}
)
return out
def _thirds_at(thirds: np.ndarray, octaves: np.ndarray, least: np.ndarray) -> np.ndarray:
"""The third-octave values ``thirds`` (octaves, 3) moved together so that each
octave's mean is that of ``octaves``, each held between its ``least`` and 1. Where
one is held, the octave's others take up evenly what it could not, as far as their
own limits let them."""
shifted = thirds + (octaves - thirds.mean(axis=1))[:, None]
moved = np.clip(shifted, least, 1.0)
held = np.any(moved != shifted, axis=1)
for _ in range(2):
short = np.where(held, octaves - moved.mean(axis=1), 0.0)
free = np.where(short[:, None] > 0.0, moved < 1.0, moved > least)
count = free.sum(axis=1)
each = np.divide(3.0 * short, count, out=np.zeros_like(short), where=count > 0)
moved = np.clip(moved + np.where(free, each[:, None], 0.0), least, 1.0)
return moved
def _without_absorption(scene) -> dict:
data = scene.model_dump()
for material in data["materials"].values():
for key in ("absorption", "source", "preset", "file", "uncertainty"):
material.pop(key, None)
return data
[docs]
def reweighted_result(result, traced, face_group: np.ndarray, materials: Sequence[str], scene):
"""``result``, simulated from the scene ``traced`` with ``face_group`` for
``materials`` (:func:`groups_of`), for the absorption of ``scene``: re-weighted,
without tracing again. None when ``scene`` differs from ``traced`` in more than the
absorption of its materials, a material changed that re-weighting does not cover,
or one did that the solver for whole rows took for a response
(:func:`solver_grounds`)."""
if scene is traced:
return result
if _without_absorption(scene) != _without_absorption(traced):
return None
old = {n: m.coefficients("octave")[0] for n, m in traced.materials.items()}
new = {n: m.coefficients("octave")[0] for n, m in scene.materials.items()}
if any(old[n] != new[n] for n in old if n not in materials):
return None
if any(old[n] != new[n] for n in solver_grounds(result)):
return None
fresh = np.array([new[n] for n in materials])
traced_absorption = np.array([old[n] for n in materials])
# A band that absorbs everything has no energy to re-weight, to it or from it.
if np.any((fresh >= 1.0) != (traced_absorption >= 1.0)):
return None
ratio = log_ratio(traced_absorption, fresh)
responses = {
key: r.reweighted(face_group, ratio, absorption=(traced_absorption, fresh))
for key, r in result.responses.items()
}
# The runs without the removed parts and in the weather classes are not re-weighted:
# their insertion loss and the long-term levels go, and so does the spread drawn
# around the absorption as traced.
return dataclasses.replace(
result, responses=responses, removed=(), insertion_loss={}, long_term=None, spreads={}
)
[docs]
def solver_grounds(result) -> list[str]:
"""The materials without an impedance on the ground of ``result``'s scene, where
some response of it has the path of the solver for whole rows
(:mod:`~acoustic_spaces.engine.row_paths`) among its early paths; none otherwise.
That path's sound depends on those grounds' absorption, through the admittance
fitted to it, and reflects off no face that a re-weighting counts."""
from acoustic_spaces.engine.model import _ground_faces
from acoustic_spaces.engine.section import ROW
room = result.room
if room.outdoor is None or not any(
r.early.edge is not None and np.any(r.early.edge == ROW) for r in result.responses.values()
):
return []
used = np.unique(np.asarray(room.face_materials)[_ground_faces(room)])
names = [room.material_names[k] for k in used if k >= 0]
return [n for n in names if room.scene.materials[n].impedance is None]
[docs]
def log_ratio(old: np.ndarray, new: np.ndarray) -> np.ndarray:
"""(groups, bands) ln((1 - new) / (1 - old)): the change in level per reflection;
0 where both absorb everything, which leaves no energy to change."""
old, new = (np.asarray(a, dtype=float) for a in (old, new))
full = old >= 1.0
if np.any(full != (new >= 1.0)):
raise ValueError(
"re-weighting needs absorption below 1, or 1 before and after: a band that "
"absorbs everything has no energy to re-weight"
)
kept = np.where(full, 0.0, new), np.where(full, 0.0, old)
return np.log1p(-kept[0]) - np.log1p(-kept[1])
[docs]
def path_counts(paths: EarlyReflections, face_group: np.ndarray, groups: int) -> np.ndarray:
"""(paths, groups) how often each early path reflects off each group of faces."""
counts = np.zeros((len(paths), groups))
for k, faces in enumerate(paths.faces):
found = face_group[np.asarray(faces, dtype=np.int64)]
np.add.at(counts[k], found[found >= 0], 1.0)
return counts
[docs]
def moment_exponent(moments: np.ndarray, ratio: np.ndarray) -> np.ndarray:
"""(bands, slots) the exponent by which each slot of late energy changes, from the
moments of the counts (terms, bands, slots) and ``log_ratio`` (groups, bands): the
multinomial's form with the rest of the covariance to second order, within the
bounds that hold for any counts (see the module's text)."""
groups = ratio.shape[0]
total = moments[0]
safe = np.where(total > 0.0, total, 1.0)
mean = moments[1 : 1 + groups] / safe # (groups, bands, slots)
change = np.expm1(ratio) # u: what each group reflects, over what it did, less 1
rest_by = np.where(ratio > 0.0, ratio, change) # w
shift = np.einsum("ibs,ib->bs", mean, ratio) # mu . l
first = np.einsum("ibs,ib->bs", mean, change) # mu . u
along = np.einsum("ibs,ib->bs", mean, rest_by) # mu . w
count = mean.sum(axis=0)
square = np.einsum("ibs,ibs->bs", mean, mean)
# mu' F mu and w' F w, F the covariance less the means on its diagonal.
spread = np.zeros_like(total)
rest = np.zeros_like(total)
t = 1 + groups
for i in range(groups):
for j in range(i, groups):
factorial = moments[t] / safe - mean[i] * mean[j]
if i == j:
factorial = factorial - mean[i]
weight = 1.0 if i == j else 2.0 # F_ij and F_ji both
spread += weight * factorial * mean[i] * mean[j]
rest += weight * factorial * (rest_by[i] * rest_by[j])[:, None]
t += 1
some = (total > 0.0) & (count > 0.0)
limit = 1.0 / np.where(some, count, 1.0)
inverse = np.clip(-spread / np.where(some, square, 1.0) ** 2, -limit, limit) # 1 / N
x = inverse * first
small = np.abs(x) < 1e-6
exponent = np.where(
small,
first * (1.0 - 0.5 * x),
np.log1p(np.maximum(x, -1.0 + 1e-12)) / np.where(small, 1.0, inverse),
)
# Counts spread wider than by chance, and less absorption: the form has a pole
# there, so its first two terms stand for it.
exponent = np.where((inverse < 0.0) & (first > 0.0), first * (1.0 - 0.5 * x), exponent)
exponent += 0.5 * (rest + inverse * along * along)
exponent = np.maximum(exponent, shift)
no_gain = np.all(ratio <= 0.0, axis=0)[:, None]
exponent = np.where(no_gain, np.minimum(exponent, 0.0), exponent)
return np.where(some, exponent, 0.0)
[docs]
def slot_factor(exponent: np.ndarray, slots: int, time_step: float, moment_step: float):
"""(bands, slots) the factor on each of ``slots`` slots of ``time_step``, taking that
of the moment slot it lies in."""
index = ((np.arange(slots) + 0.5) * time_step / moment_step).astype(np.int64)
index = np.minimum(index, exponent.shape[1] - 1)
return np.exp(np.minimum(exponent[:, index], 50.0))
[docs]
def reweighted_paths(paths: EarlyReflections, counts: np.ndarray, ratio: np.ndarray):
"""``paths`` with their energies for the new absorption (``counts`` from
:func:`path_counts`, ``ratio`` from :func:`log_ratio`)."""
if len(paths) == 0:
return paths
return dataclasses.replace(paths, energy=paths.energy * np.exp(products.product(counts, ratio)))
[docs]
def turned_paths(
paths: EarlyReflections,
face_group: np.ndarray,
old: np.ndarray,
new: np.ndarray,
admittance_of=None,
) -> EarlyReflections:
"""``paths`` with the phase of each reflection off a group of faces (``face_group``)
turned, in the bands where they add in pressure, from that of the group's absorption
``old`` (groups, bands) to that of ``new``: from the angle each meets its face at
(:attr:`~acoustic_spaces.engine.early.EarlyReflections.cosines`). Reflections whose
phase their face's absorption does not give keep theirs. ``admittance_of`` gives the
admittance of an absorption row (:func:`~acoustic_spaces.engine.coherent.
absorption_phases`; by default the one fitted to it)."""
if paths.spectrum is None or len(paths) == 0 or not paths.cosines:
return paths
old, new = (np.asarray(a, dtype=float) for a in (old, new))
rows, groups, cosines = _turned_reflections(paths, face_group, np.any(old != new, axis=1))
if not rows:
return paths
f = sample_frequencies(old.shape[1], paths.spectrum.shape[1])
turn = absorption_phases(new[groups], cosines, f, admittance_of) * np.conj(
absorption_phases(old[groups], cosines, f, admittance_of)
)
return _turned(paths, rows, turn)
def _turned_reflections(
paths: EarlyReflections, face_group: np.ndarray, changed: np.ndarray
) -> tuple[list[int], np.ndarray, list[float]]:
"""The reflections :func:`turned_paths` turns, those off a group ``changed`` (groups,)
at a known angle: the path of each, its group and its incidence cosine."""
rows, groups, cosines = [], [], []
for k, (faces, angles) in enumerate(zip(paths.faces, paths.cosines, strict=True)):
group = face_group[np.asarray(faces, dtype=np.int64)]
mine = group >= 0
mine[mine] = changed[group[mine]]
mine &= np.isfinite(angles)
rows.extend([k] * int(mine.sum()))
groups.extend(group[mine])
cosines.extend(angles[mine])
return rows, np.asarray(groups, dtype=np.int64), cosines
def _turned(paths: EarlyReflections, rows: list[int], turn: np.ndarray) -> EarlyReflections:
"""``paths`` with the spectrum of path ``rows[i]`` times ``turn[i]``, in turn."""
spectrum = paths.spectrum.copy()
np.multiply.at(spectrum, np.asarray(rows), turn)
return dataclasses.replace(paths, spectrum=spectrum)
[docs]
class Redraws:
"""What re-weighting the early paths ``paths`` of one traced response
(:meth:`~acoustic_spaces.engine.response.Response.reweighted`) for draw after draw of
the absorption of ``groups`` groups of faces (``face_group``) takes that does not
depend on the draw: how often each path reflects off each group
(:func:`path_counts`); for each set of groups a draw changes, the reflections
:func:`turned_paths` turns and the phases of the absorption ``old`` as traced that it
turns them from, with ``admittance_of``; and what the coherent bands' echograms of
the draws share (``delays``, a :class:`~acoustic_spaces.engine.coherent.SameDelays`).
A draw comes out the same with it as without it: for other paths, groups, traced
absorption or admittances than its own, each is worked out as without it. Made from
its arguments alone, for one response's draws, and dropped after them."""
def __init__(
self,
paths: EarlyReflections,
face_group: np.ndarray,
groups: int,
old: np.ndarray,
admittance_of=None,
) -> None:
self._paths, self._groups = paths, groups
self._face_group = np.array(face_group)
self._old = np.array(old, dtype=float)
self._admittance_of = admittance_of
self._counts = path_counts(paths, self._face_group, groups)
self._counts.flags.writeable = False
self._turned: dict[bytes, tuple] = {}
self.delays = SameDelays()
def _mine(self, paths: EarlyReflections, face_group: np.ndarray) -> bool:
return paths.faces is self._paths.faces and np.array_equal(face_group, self._face_group)
[docs]
def counts(self, paths: EarlyReflections, face_group: np.ndarray, groups: int) -> np.ndarray:
""":func:`path_counts` of these arguments (read-only)."""
if paths is self._paths and groups == self._groups and self._mine(paths, face_group):
return self._counts
return path_counts(paths, face_group, groups)
[docs]
def turned(
self,
paths: EarlyReflections,
face_group: np.ndarray,
old: np.ndarray,
new: np.ndarray,
admittance_of=None,
) -> EarlyReflections:
""":func:`turned_paths` of these arguments, for ``paths`` that are this one's re-weighted
(:func:`reweighted_paths`)."""
old, new = (np.asarray(a, dtype=float) for a in (old, new))
if not (
paths.cosines is self._paths.cosines
and paths.spectrum is self._paths.spectrum
and admittance_of is self._admittance_of
and old.shape == self._old.shape
and np.array_equal(old, self._old)
and self._mine(paths, face_group)
):
return turned_paths(paths, face_group, old, new, admittance_of)
if paths.spectrum is None or len(paths) == 0 or not paths.cosines:
return paths
changed = np.any(old != new, axis=1)
held = self._turned.get(changed.tobytes())
if held is None:
rows, groups, cosines = _turned_reflections(paths, face_group, changed)
back = None
f = sample_frequencies(old.shape[1], paths.spectrum.shape[1])
if rows:
back = np.conj(absorption_phases(old[groups], cosines, f, admittance_of))
back.flags.writeable = False
held = self._turned[changed.tobytes()] = (rows, groups, cosines, f, back)
rows, groups, cosines, f, back = held
if not rows:
return paths
return _turned(
paths, rows, absorption_phases(new[groups], cosines, f, admittance_of) * back
)
__all__ = [
"MOMENT_STEP",
"Redraws",
"cannot_reweight",
"face_groups",
"groups_of",
"log_ratio",
"moment_exponent",
"path_counts",
"reweighted_paths",
"reweighted_materials",
"reweighted_result",
"solver_grounds",
"slot_factor",
"turned_paths",
]