"""Write a simulation's responses to a folder: the files ``acoustic-spaces simulate``
and the editor's Export produce.
For every (source, listener) pair, one WAV file per output format
(``<source>__<listener>.wav`` for mono, ``<source>__<listener>.<format>.wav`` for the
others, with ``-2``, ``-3``... after the names or the format where two files would
otherwise be the same), and for the whole run ``parameters.json``: the settings, run details and the
ISO 3382-1 parameters of every response (with IACC when a binaural response is written,
from the first if there are several), its STI, STIPA and U50, and its echo criteria.
Outdoors also its level relative to free field, and the insertion loss of the buildings,
barriers or vegetation the run was also made without (``simulation.insertion_loss_of``).
``acoustic-spaces auralize`` reads that folder.
"""
from __future__ import annotations
import dataclasses
import json
import math
import os
import re
import shutil
import tempfile
from collections.abc import Callable, Sequence
from concurrent.futures import ThreadPoolExecutor
from pathlib import Path
from typing import TYPE_CHECKING
import numpy as np
from acoustic_spaces import parameters as iso3382
from acoustic_spaces.audio import read_wav, write_wav
from acoustic_spaces.materials import OCTAVE_BANDS_HZ
if TYPE_CHECKING:
from acoustic_spaces.engine import SimulationResult
from acoustic_spaces.spatial import Format
REPORT_FILE = "parameters.json"
#: How the hidden folder starts that the files are written into before they move into
#: place (see :func:`write_results`).
_STAGING = ".writing-"
[docs]
def file_name(text: str) -> str:
"""``text`` with anything but letters, digits, dots, dashes and underscores replaced."""
return re.sub(r"[^A-Za-z0-9._-]+", "_", text).strip("_") or "unnamed"
def response_stem(source: str, listener: str) -> str:
return f"{file_name(source)}__{file_name(listener)}"
[docs]
def unique_stems(stems: Sequence[str], suffixes: Sequence[str] = ("",)) -> list[str]:
"""``stems``, each that would name the same file as one before it with any of
``suffixes`` given ``-2``, ``-3``... in turn, also where the names differ only in
case (the file systems of Windows and macOS ignore it): :func:`file_name` turns
``A/B`` and ``A_B`` into the same name, and names in other scripts into
``unnamed``."""
taken: set[str] = set()
out = []
for stem in stems:
unique, k = stem, 1
while any((unique + suffix).casefold() in taken for suffix in suffixes):
k += 1
unique = f"{stem}-{k}"
taken.update((unique + suffix).casefold() for suffix in suffixes)
out.append(unique)
return out
[docs]
def results_folder(out: str | Path) -> Path:
"""The folder ``out`` ready for results: made where it is missing, and found to take
files. Otherwise an OSError says why not: ``out`` is a file, or the folder cannot be
made or written in. ``acoustic-spaces simulate`` asks before its run, so that a run is
not lost at its end."""
out = Path(out)
if out.exists() and not out.is_dir():
raise NotADirectoryError(f"{out} is a file, not a folder")
out.mkdir(parents=True, exist_ok=True)
Path(tempfile.mkdtemp(prefix=_STAGING, dir=out)).rmdir()
return out
[docs]
def write_results(
result: SimulationResult,
out: str | Path,
formats: Sequence[Format] | None = None,
*,
sample_rate: int | None = None,
normalize: bool = False,
plots: bool = False,
progress: Callable[[str], None] | None = None,
) -> dict:
"""Write every response of ``result`` into the folder ``out`` and return the report
saved as ``parameters.json``.
``formats`` are formats of :mod:`acoustic_spaces.spatial` (default: the scene's
``outputs``); ``sample_rate`` defaults to the simulation's. ``normalize`` scales all
files together so the loudest sample is at -1 dBFS; otherwise they keep the
simulation's levels, which exceed full scale when a listener is closer than 1 m to
a source (the report's ``peak`` says by how much). ``plots`` adds the echogram and
direction plots of :mod:`acoustic_spaces.viz` when matplotlib is installed.
Each response's spread from its materials' absorption uncertainty, where the result
has it (``spreads``), goes into the report too.
The files are written into a hidden folder in ``out`` first and moved into place
once all of them are, the report last, so that a run that fails or is cancelled
while writing (a full disk, say) leaves ``out`` as it was. Each response is rendered
and written in turn (on the run's threads, one each), so memory holds a response's
files at a time, not the whole run's, and its late part while its formats are
rendered; threads the responses leave free render the channels of each side by
side, a channel's band signals in memory for each, the channels in progress held
to a quarter of the computer's memory. With ``normalize`` the files are
scaled once all are written, by one rounding to single precision more.
"""
out = results_folder(out)
staging = Path(tempfile.mkdtemp(prefix=_STAGING, dir=out))
try:
report = _write_results(
result,
staging,
formats,
sample_rate,
normalize,
plots,
progress or (lambda _: None),
)
# Into place, the report last: until it is, the folder's report is the one before.
for path in sorted(staging.iterdir(), key=lambda path: path.name == REPORT_FILE):
os.replace(path, out / path.name)
finally:
shutil.rmtree(staging, ignore_errors=True)
return report
def _write_results(result, out: Path, formats, sample_rate, normalize, plots, say) -> dict:
""":func:`write_results`, its files written straight into ``out``."""
from acoustic_spaces.spatial import Binaural, for_listener, from_output
from acoustic_spaces.spatial.render import channel_threads, sharing_late_parts
if formats is None:
formats = [from_output(o) for o in result.room.scene.outputs]
sample_rate = int(sample_rate or result.settings.sample_rate)
from acoustic_spaces.engine.run_size import worker_threads
# The responses side by side, on the run's threads: each is rendered and read as it
# would be alone, so the files and the report are the same as one after another.
threads = worker_threads(result.settings.performance.threads)
workers = max(1, min(threads, len(result.responses)))
# The threads the responses leave free render each one's channels side by side, as
# far as the memory lets that many channels be in progress at once.
inner = max(1, threads // workers)
# File names that no two responses or formats share, though their names may give
# the same (two binaural outputs with HRTF files of the same name, say).
parts = unique_stems(
["" if fmt.label == "mono" else f".{file_name(fmt.label)}" for fmt in formats]
)
suffixes = [f"{part}.wav" for part in parts] + [".png", ".directions.png"]
stems = dict(
zip(
result.responses,
unique_stems([response_stem(*key) for key in result.responses], suffixes),
strict=True,
)
)
masks = [fmt.channel_mask() if hasattr(fmt, "channel_mask") else None for fmt in formats]
binaural = [k for k, fmt in enumerate(formats) if isinstance(fmt, Binaural)]
mono_at = [k for k, fmt in enumerate(formats) if fmt.label == "mono"]
scene = result.room.scene
listeners = {item.name: item for item in scene.listeners}
long_term = result.long_term
def write(key) -> tuple[dict, float]:
"""Render the response in each format and write its files, at the simulation's
levels; its entry in the report, without plots, and its loudest sample."""
source, listener = key
response = result.responses[key]
stem = stems[key]
written, peak, ears, mono = [], 0.0, None, None
# The formats take the response's late part from the first that works it out.
with sharing_late_parts():
for k, (fmt, part) in enumerate(zip(formats, parts, strict=True)):
# The mono output through the listener's microphone, when it has a pattern.
heard = for_listener(fmt, listeners.get(listener))
say(f"{source} -> {listener}: rendering {heard.label}")
ir = response.spatial_impulse_response(
heard,
sample_rate,
threads=channel_threads(response, sample_rate, inner, workers, heard),
)
peak = max(peak, float(abs(ir).max(initial=0.0)))
name = f"{stem}{part}.wav"
write_wav(out / name, ir, sample_rate, masks[k])
output = {"format": fmt.label, "wav": name, "channels": heard.channel_names}
if heard is not fmt:
output["microphone"] = heard.label
written.append(output)
if binaural and k == binaural[0]:
ears = ir
if mono_at and k == mono_at[0] and heard is fmt:
mono = ir[:, 0]
params = response.parameters()
if ears is not None:
params = dataclasses.replace(
params, **iso3382.interaural_cross_correlation(ears, sample_rate)
)
if mono is None:
mono = response.impulse_response(sample_rate)
power, noise_db, talker = scene.level_inputs(source)
spl = response.levels_or_held(power, params)
entry = {
"source": source,
"listener": listener,
"outputs": written,
"direct_delay_s": response.direct_delay_s,
"early_paths": len(response.early),
"diffracted_paths": int(response.early.diffracted.sum()),
"parameters": params.as_dict(),
"spl_db": [_plain(v) for v in spl],
"spl_a_db": _plain(iso3382.a_weighted(spl)),
"speech": response.speech(power, noise_db, parameters=params, talker=talker).as_dict(),
"echo": _echo(mono, sample_rate),
}
errors = response.standard_errors()
if errors is not None:
entry["standard_errors"] = errors.as_dict()
if key in result.spreads:
entry["uncertainty"] = result.spreads[key].as_dict()
# In a band no sound arrives in (spl -inf), neither the level in free field nor
# the level without what was left out can be read back from spl: their
# A-weighted values are then NaN (null).
if response.free_field is not None:
relative = response.relative_to_free_field()
entry["re_free_field_db"] = [_plain(v) for v in relative]
with np.errstate(invalid="ignore"):
free = spl - relative
entry["re_free_field_a_db"] = _plain(iso3382.a_weighted(spl) - iso3382.a_weighted(free))
loss = result.insertion_loss.get((source, listener))
if loss is not None:
entry["insertion_loss_db"] = [_plain(v) for v in loss]
with np.errstate(invalid="ignore"):
bare = spl + loss
entry["insertion_loss_a_db"] = _plain(
iso3382.a_weighted(bare) - iso3382.a_weighted(spl)
)
if long_term is not None and (source, listener) in long_term.levels:
entry["long_term"] = _long_term_entry(long_term, (source, listener))
return entry, peak
with ThreadPoolExecutor(workers) as pool:
done = list(pool.map(write, result.responses))
entries = [entry for entry, _ in done]
peak = max((p for _, p in done), default=0.0)
gain = 10.0 ** (-1.0 / 20.0) / peak if normalize and peak > 0 else 1.0
if gain != 1.0:
def scale(entry: dict) -> None:
for output, mask in zip(entry["outputs"], masks, strict=True):
data, _ = read_wav(out / output["wav"])
write_wav(out / output["wav"], data * gain, sample_rate, mask)
with ThreadPoolExecutor(workers) as pool:
list(pool.map(scale, entries))
report = {
"scene": result.room.scene.name,
"bands_hz": list(OCTAVE_BANDS_HZ),
"sample_rate": sample_rate,
"ir_gain": gain,
"peak": peak * gain,
"settings": result.settings.model_dump(mode="json"),
"details": result.details,
# What auralize needs to mix the sources at their power: the responses are per
# unit of it.
"sources": {
source.name: {"sound_power_db": source.sound_power_db} for source in scene.sources
},
"responses": entries,
}
if result.removed:
report["removed"] = list(result.removed)
if long_term is not None:
report["long_term"] = {
"classes": list(long_term.classes),
"shares": {
name: {
period: round(float(share), 6)
for period, share in zip(long_term.periods, row, strict=True)
}
for name, row in zip(long_term.classes, long_term.shares, strict=True)
},
"periods": [
{"name": name, "hours": float(hours), "penalty_db": float(penalty)}
for name, hours, penalty in zip(
long_term.periods, long_term.hours, long_term.penalties, strict=True
)
],
"rating": long_term.rating,
}
# Plots one after another: matplotlib draws in one thread.
for entry, (key, response) in zip(entries, result.responses.items(), strict=True):
stem = stems[key]
if plots:
try:
from acoustic_spaces.viz import plot_directions, plot_response
plot_response(response, out / f"{stem}.png")
plot_directions(response, out / f"{stem}.directions.png")
entry["plot"] = f"{stem}.png"
entry["directions_plot"] = f"{stem}.directions.png"
except ImportError as exc:
say(f"warning: {exc}")
plots = False
(out / REPORT_FILE).write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
return report
def _long_term_entry(long_term, key) -> dict:
"""The levels over a long term at one (source, listener), for the report: the
long-term level, the rating level, and those in each period and each weather class,
per octave band and A-weighted."""
def levels(bands, a) -> dict:
return {"spl_db": [_plain(v) for v in bands], "spl_a_db": _plain(a)}
entry = {
**levels(long_term.levels[key], long_term.levels_a[key]),
"rating_level_db": _plain(long_term.rating_level[key]),
"rating": long_term.rating,
"periods": {
name: levels(long_term.period_levels[key][k], long_term.period_a[key][k])
for k, name in enumerate(long_term.periods)
},
"classes": {
name: levels(long_term.class_levels[key][k], long_term.class_a[key][k])
for k, name in enumerate(long_term.classes)
},
}
for what in ("re_free_field", "insertion_loss"):
bands = getattr(long_term, what).get(key)
if bands is not None:
entry[f"{what}_db"] = [_plain(v) for v in bands]
entry[f"{what}_a_db"] = _plain(getattr(long_term, f"{what}_a")[key])
return entry
def _plain(value: float) -> float | None:
"""A level for JSON: None where it is not finite."""
value = float(value)
return round(value, 2) if math.isfinite(value) else None
def _echo(ir, sample_rate: int) -> dict:
"""The echo criteria of a mono impulse response, for the report."""
out = {}
for kind in iso3382.ECHO_CRITERIA:
value, at = iso3382.echo_criterion(ir, sample_rate, kind)
out[kind] = {
"ec": value if math.isfinite(value) else None,
"at_s": at if math.isfinite(at) else None,
}
return out
__all__ = [
"REPORT_FILE",
"file_name",
"response_stem",
"results_folder",
"unique_stems",
"write_results",
]