"""The insertion loss of an outdoor scene's buildings, barriers and vegetation.
The scene is run as it is and again without them (:meth:`~acoustic_spaces.scene.Scene.
without`), with the same settings and seed, so that the two runs' rays start alike;
the insertion loss is the level without them less the level with them, per octave band
(and A-weighted, for the sound power of each source). A barrier that takes 10 dB off has
an insertion loss of 10 dB; a building that sends sound back towards the listener can
have a negative one.
``simulation.insertion_loss_of`` names what to take away; :func:`simulate` and
:func:`coverage_map` read it unless given ``without``, and are :func:`~acoustic_spaces.
engine.simulate` and :func:`~acoustic_spaces.engine.coverage.coverage_map` when it names
nothing.
"""
from __future__ import annotations
import dataclasses
import time
from collections.abc import Callable, Sequence
from pathlib import Path
import numpy as np
from acoustic_spaces.engine import coverage as coverage_stage
from acoustic_spaces.engine.response import Response
from acoustic_spaces.engine.simulate import SimulationResult, _as_room
from acoustic_spaces.engine.simulate import simulate as simulate_stage
from acoustic_spaces.parameters import A_WEIGHTING_DB, a_weighted
from acoustic_spaces.room import Room
from acoustic_spaces.scene import Coverage, Scene
from acoustic_spaces.scene.model import Simulation, insertion_loss_problem
def _names(room: Room, settings: Simulation, without: Sequence[str] | None) -> list[str]:
"""What to take away, checked as a scene checks ``insertion_loss_of`` before
anything runs: this outdoor scene's buildings, barriers or vegetation, each once."""
names = list(settings.insertion_loss_of or []) if without is None else list(without)
what = "simulation.insertion_loss_of" if without is None else "without"
problem = insertion_loss_problem(room.scene.geometry, names, what) if names else None
if problem is not None:
raise ValueError(problem)
return names
def _seeded(settings: Simulation) -> Simulation:
"""The settings with a seed of their own, so that both runs trace the same rays, and
without ``insertion_loss_of``."""
seed = settings.seed
if seed is None:
seed = int(np.random.SeedSequence().generate_state(1, np.uint32)[0])
return settings.model_copy(update={"seed": seed, "insertion_loss_of": None})
[docs]
def bare_room(room: Room, names: Sequence[str]) -> Room:
"""The room without the buildings, barriers and vegetation of these names."""
return Room.from_scene(room.scene.without(names))
def _loss(bare: Response, kept: Response) -> np.ndarray:
"""The insertion loss per octave band (dB) from the energy each response holds:
nothing is extrapolated past their ends, as G does for a room's decay. Infinite where
only one of them holds any, NaN where neither does."""
with np.errstate(divide="ignore", invalid="ignore"):
return 10.0 * np.log10(bare.octave_energy().sum(axis=1) / kept.octave_energy().sum(axis=1))
[docs]
def simulate(
room: Room | Scene | str | Path,
*,
without: Sequence[str] | None = None,
settings: Simulation | None = None,
sources: Sequence[str] | None = None,
listeners: Sequence[str] | None = None,
threads: int | None = None,
progress: Callable[[str], None] | None = None,
groups: np.ndarray | None = None,
) -> SimulationResult:
""":func:`~acoustic_spaces.engine.simulate`, and the insertion loss of the
buildings, barriers and vegetation named in ``without`` (default:
``simulation.insertion_loss_of``) at every listener: the result is the scene's as it
is, with ``removed`` and ``insertion_loss`` (dB per octave band, the level without
them less the level with them; NaN where either level is undefined). ``groups`` are
for the run of the scene as it is."""
room = _as_room(room)
settings = settings or room.scene.simulation
names = _names(room, settings, without)
if not names:
return simulate_stage(
room,
settings=settings,
sources=sources,
listeners=listeners,
threads=threads,
progress=progress,
groups=groups,
)
say = progress or (lambda _: None)
started = time.perf_counter()
settings = _seeded(settings)
say(f"Insertion loss: the scene as it is, then without {', '.join(names)}")
with_parts = simulate_stage(
room,
settings=settings,
sources=sources,
listeners=listeners,
threads=threads,
progress=progress,
groups=groups,
)
bare = bare_room(room, names)
say(f"Insertion loss: the scene without {', '.join(names)}")
without_parts = simulate_stage(
bare,
settings=settings,
sources=sources,
listeners=listeners,
threads=threads,
progress=progress,
)
loss = {
key: _loss(without_parts.responses[key], response)
for key, response in with_parts.responses.items()
}
details = dict(with_parts.details)
details["insertion_loss"] = {
"parts": float(len(names)),
"seconds": time.perf_counter() - started,
}
return dataclasses.replace(
with_parts, details=details, removed=tuple(names), insertion_loss=loss
)
[docs]
def coverage_map(
room: Room | Scene | str | Path,
*,
without: Sequence[str] | None = None,
settings: Coverage | None = None,
simulation: Simulation | None = None,
sources: Sequence[str] | None = None,
threads: int | None = None,
progress: Callable[[str], None] | None = None,
grid: coverage_stage.MapGrid | None = None,
rays_of: Scene | None = None,
) -> coverage_stage.CoverageResult:
""":func:`~acoustic_spaces.engine.coverage.coverage_map`, and the insertion loss of
the buildings, barriers and vegetation named in ``without`` (default:
``simulation.insertion_loss_of``) at every map point: each map gains
``insertion_loss`` (dB per octave band) and ``insertion_loss_a`` (dB(A), for the
sources' sound power), the level without them less the level with them. Both runs
share the map's points, those of the scene as it is (or ``grid``, as
:func:`~acoustic_spaces.engine.coverage.coverage_map` takes it, as it does
``rays_of``, for both runs)."""
room = _as_room(room)
simulation = simulation or room.scene.simulation
names = _names(room, simulation, without)
run = coverage_stage.coverage_map
if not names:
return run(
room,
settings=settings,
simulation=simulation,
sources=sources,
threads=threads,
progress=progress,
grid=grid,
rays_of=rays_of,
)
say = progress or (lambda _: None)
started = time.perf_counter()
simulation = _seeded(simulation)
say(f"Insertion loss: the map as it is, then without {', '.join(names)}")
with_parts = run(
room,
settings=settings,
simulation=simulation,
sources=sources,
threads=threads,
progress=progress,
grid=grid,
rays_of=rays_of,
)
say(f"Insertion loss: the map without {', '.join(names)}")
without_parts = run(
bare_room(room, names),
settings=with_parts.settings,
simulation=simulation,
sources=sources,
threads=threads,
progress=progress,
grid=with_parts.grid,
rays_of=rays_of,
)
def with_loss(
kept: coverage_stage.CoverageMap, bare: coverage_stage.CoverageMap
) -> coverage_stage.CoverageMap:
# Both maps hold the same free field at the same points, so the difference of
# their levels relative to it is that of the energies they hold.
loss = bare.values["re_free_field"] - kept.values["re_free_field"]
spl = kept.values["spl"]
values = {
**kept.values,
"insertion_loss": loss,
"insertion_loss_a": _a_weighted_rows(spl + loss) - _a_weighted_rows(spl),
}
return dataclasses.replace(kept, values=values)
maps = {
name: with_loss(kept, without_parts.maps[name]) for name, kept in with_parts.maps.items()
}
combined = with_parts.combined
if combined is not None:
combined = with_loss(combined, without_parts.combined)
details = dict(with_parts.details)
details["insertion_loss"] = {
"parts": float(len(names)),
"seconds": time.perf_counter() - started,
}
return dataclasses.replace(
with_parts, maps=maps, combined=combined, details=details, removed=tuple(names)
)
[docs]
def a_weighted_loss(spl: np.ndarray, loss: np.ndarray) -> float:
"""The A-weighted insertion loss (dB) from the levels with the parts per octave band
(dB SPL) and their insertion loss per band: the A-weighted level without them less
that with them."""
spl = np.asarray(spl, dtype=float)
return float(a_weighted(spl + np.asarray(loss, dtype=float)) - a_weighted(spl))
def _a_weighted_rows(levels: np.ndarray) -> np.ndarray:
""":func:`~acoustic_spaces.parameters.a_weighted` of every row of (points, bands)."""
weighted = np.asarray(levels, dtype=float) + np.array(A_WEIGHTING_DB)
with np.errstate(divide="ignore"):
return 10.0 * np.log10(np.sum(10.0 ** (weighted / 10.0), axis=1))
__all__ = ["a_weighted_loss", "bare_room", "coverage_map", "simulate"]