Source code for acoustic_spaces.results

"""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", ]