Source code for acoustic_spaces.materials.bands

"""Frequency bands and conversion of coefficient data onto them.

A simulation runs in octave bands (``OCTAVE_BANDS_HZ``, the default) or in third-octave
bands (``THIRD_OCTAVE_BANDS_HZ``), three to each octave band with its centre in the
middle. Coefficients come in either; each list converts to the other: an octave value
holds for its three third-octave bands, and an octave takes the mean of its three.
"""

from __future__ import annotations

import math
from collections.abc import Sequence
from typing import Literal

import numpy as np

#: Octave-band centre frequencies used for all frequency-dependent data (Hz).
OCTAVE_BANDS_HZ: tuple[int, ...] = (63, 125, 250, 500, 1000, 2000, 4000, 8000)
#: Third-octave-band centre frequencies (Hz, nominal, IEC 61260-1): three to each octave
#: band of ``OCTAVE_BANDS_HZ``, from 50 Hz to 10 kHz.
THIRD_OCTAVE_BANDS_HZ: tuple[int, ...] = (
    50, 63, 80, 100, 125, 160, 200, 250, 315, 400, 500, 630,
    800, 1000, 1250, 1600, 2000, 2500, 3150, 4000, 5000, 6300, 8000, 10000,
)  # fmt: skip

#: How finely a simulation splits the spectrum.
Resolution = Literal["octave", "third_octave"]
#: Bands per octave at each resolution.
BANDS_PER_OCTAVE: dict[str, int] = {"octave": 1, "third_octave": 3}


[docs] def band_centres(resolution: Resolution = "octave") -> tuple[int, ...]: """Nominal centre frequencies (Hz) of the bands at ``resolution``.""" if resolution == "octave": return OCTAVE_BANDS_HZ if resolution == "third_octave": return THIRD_OCTAVE_BANDS_HZ raise ValueError(f"unknown band resolution {resolution!r}; use 'octave' or 'third_octave'")
def resolution_of(bands: int) -> Resolution: """The resolution with ``bands`` bands: 8 octave bands or 24 third-octave bands.""" if bands == len(OCTAVE_BANDS_HZ): return "octave" if bands == len(THIRD_OCTAVE_BANDS_HZ): return "third_octave" raise ValueError( f"expected {len(OCTAVE_BANDS_HZ)} octave or {len(THIRD_OCTAVE_BANDS_HZ)} " f"third-octave bands, got {bands}" ) def exact_centres(resolution: Resolution = "octave") -> np.ndarray: """Exact mid-band frequencies (Hz, base 10, IEC 61260-1) of the bands at ``resolution``.""" step = 0.3 / BANDS_PER_OCTAVE[resolution] k = np.round(np.log10(np.asarray(band_centres(resolution), float) / 1000.0) / step) return 1000.0 * 10.0 ** (step * k) def exact_limits(resolution: Resolution = "octave") -> tuple[np.ndarray, np.ndarray]: """Lower and upper band-edge frequencies (Hz, base 10, IEC 61260-1) of the bands at ``resolution``: each exact mid-band frequency over and times G^(1/2) for octaves, G^(1/6) for third octaves, G = 10^(3/10). Each band's upper edge is the next one's lower edge: the 63 Hz octave runs from 44.7 to 89.1 Hz, the 8 kHz one to 11.2 kHz.""" centre = exact_centres(resolution) half = 10.0 ** (0.15 / BANDS_PER_OCTAVE[resolution]) return centre / half, centre * half def band_limits(resolution: Resolution = "octave") -> tuple[np.ndarray, np.ndarray]: """Lower and upper edges (Hz) of each band: its nominal centre over and times 2^(1/2) for octaves, 2^(1/6) for third octaves.""" centre = np.asarray(band_centres(resolution), float) half = 2.0 ** (0.5 / BANDS_PER_OCTAVE[resolution]) return centre / half, centre * half def crossover_frequencies(resolution: Resolution = "octave") -> np.ndarray: """Edges between adjacent bands (Hz): the octave bands' nominal centres times 2^(1/2), and between third octaves 1000 Hz times 2^((k + 1/2) / 3).""" if resolution == "octave": return np.array(OCTAVE_BANDS_HZ[:-1], dtype=float) * math.sqrt(2.0) k = np.arange(len(THIRD_OCTAVE_BANDS_HZ) - 1) - THIRD_OCTAVE_BANDS_HZ.index(1000) return 1000.0 * 2.0 ** ((k + 0.5) / 3.0) def octave_of(resolution: Resolution = "octave") -> np.ndarray: """The index in ``OCTAVE_BANDS_HZ`` of the octave band each band lies in.""" per = BANDS_PER_OCTAVE[resolution] return np.arange(len(band_centres(resolution))) // per def convert(values: Sequence[float], resolution: Resolution) -> list[float]: """Per-band ``values`` (octave or third-octave) at ``resolution``: an octave value for each of its three third octaves, or the mean of three third octaves for their octave.""" values = np.asarray(values, dtype=float) have = resolution_of(len(values)) if have == resolution: return [float(v) for v in values] if resolution == "third_octave": return [float(v) for v in np.repeat(values, 3)] return [float(v) for v in values.reshape(-1, 3).mean(axis=1)] def power_levels(levels_db: Sequence[float], resolution: Resolution) -> np.ndarray: """Power levels per band (dB, octave or third-octave) at ``resolution``: an octave's power split evenly between its three third octaves, or three third octaves' summed into their octave.""" levels = np.asarray(levels_db, dtype=float) if resolution_of(len(levels)) == resolution: return levels if resolution == "third_octave": return np.repeat(levels, 3) - 10.0 * math.log10(3.0) with np.errstate(divide="ignore"): return 10.0 * np.log10((10.0 ** (levels / 10.0)).reshape(-1, 3).sum(axis=1)) def gain_levels(gains_db: Sequence[float], resolution: Resolution) -> np.ndarray: """Gains per band (dB, octave or third-octave) at ``resolution``: an octave's gain for each of its three third octaves, or the gain of three third octaves together in their octave, the mean of their power gains.""" gains = np.asarray(gains_db, dtype=float) if resolution_of(len(gains)) == resolution: return gains if resolution == "third_octave": return np.repeat(gains, 3) with np.errstate(divide="ignore"): return 10.0 * np.log10((10.0 ** (gains / 10.0)).reshape(-1, 3).mean(axis=1)) def to_octaves(energy: np.ndarray, axis: int = 0) -> np.ndarray: """Energies with octave or third-octave bands along ``axis``, in octave bands: the mean of each octave's three third octaves. The simulation's band energies are spectral levels (a unit source's direct sound carries 1 / (4 pi r^2) in every band, however wide), so an octave's is the mean of its thirds', each covering a third of it. """ energy = np.asarray(energy, dtype=float) axis = axis % energy.ndim if resolution_of(energy.shape[axis]) == "octave": return energy shape = energy.shape[:axis] + (len(OCTAVE_BANDS_HZ), 3) + energy.shape[axis + 1 :] return energy.reshape(shape).mean(axis=axis + 1)
[docs] def to_bands( frequencies: Sequence[float], values: Sequence[float], resolution: Resolution = "octave" ) -> tuple[list[float], list[int]]: """Map coefficients given at arbitrary centre frequencies onto the bands at ``resolution``. Values whose centre falls inside a band (third-octave data in an octave band, for example) are averaged. A band with no data takes the value of the nearest band that has some; those bands are returned as the second element so callers can say so. """ freqs = np.asarray(frequencies, dtype=float) vals = np.asarray(values, dtype=float) if freqs.shape != vals.shape or freqs.ndim != 1 or len(freqs) == 0: raise ValueError("frequencies and values must be non-empty and of equal length") centres = band_centres(resolution) if resolution == "octave": low, high = band_limits(resolution) else: edges = crossover_frequencies(resolution) low = np.concatenate([[edges[0] / 2.0 ** (1 / 3)], edges]) high = np.concatenate([edges, [edges[-1] * 2.0 ** (1 / 3)]]) out = np.full(len(centres), np.nan) for k in range(len(centres)): inside = (freqs >= low[k]) & (freqs < high[k]) if inside.any(): out[k] = float(vals[inside].mean()) known = np.flatnonzero(~np.isnan(out)) if len(known) == 0: raise ValueError(f"no data between {low[0]:.0f} Hz and {high[-1] / 1000:.1f} kHz") extrapolated = [centres[k] for k in np.flatnonzero(np.isnan(out))] for k in np.flatnonzero(np.isnan(out)): out[k] = out[known[np.argmin(np.abs(known - k))]] return [float(v) for v in out], extrapolated
[docs] def to_octave_bands( frequencies: Sequence[float], values: Sequence[float] ) -> tuple[list[float], list[int]]: """Map coefficients given at arbitrary centre frequencies onto ``OCTAVE_BANDS_HZ`` (:func:`to_bands` at octave resolution).""" return to_bands(frequencies, values, "octave")
def finer_than_octaves(frequencies: Sequence[float]) -> bool: """Whether data at ``frequencies`` has more than one value in some octave band, so third-octave bands keep detail that octave bands would average away.""" freqs = np.asarray(frequencies, dtype=float) low, high = band_limits("octave") return any( int(((freqs >= lo) & (freqs < hi)).sum()) > 1 for lo, hi in zip(low, high, strict=True) ) __all__ = [ "BANDS_PER_OCTAVE", "OCTAVE_BANDS_HZ", "THIRD_OCTAVE_BANDS_HZ", "Resolution", "band_centres", "band_limits", "convert", "crossover_frequencies", "exact_centres", "exact_limits", "finer_than_octaves", "gain_levels", "octave_of", "power_levels", "resolution_of", "to_bands", "to_octave_bands", "to_octaves", ]