Source code for acoustic_spaces.engine.late

"""Late reverberation: energy per octave band and time slot at each listener.

- ``stochastic_energy``: stochastic ray tracing in the compiled core. Rays reflect as
  the scene's ``simulation.scattering`` says (vector-based scattering by default, with
  the scattering of each surface's size added); how their energy reaches the listeners
  is set by ``reception`` (see :data:`RECEPTION`). Specular paths the early
  stage computes exactly are left out, so the two parts add up without double counting
  or a crossfade. Outdoors in wind or a temperature gradient the rays bend
  (:func:`~acoustic_spaces.engine.refracted.bending`).
- ``stochastic_map_energy``: the same tracer counting energy over a coverage map
  instead of at listeners.
- ``statistical_energy``: the reflected energy of Barron's revised theory, an
  exponential decay from the direct sound on, less the energy of the early paths.
"""

from __future__ import annotations

import math
from collections.abc import Sequence
from dataclasses import dataclass, field, replace

import numpy as np

from acoustic_spaces.directivity import Directivity
from acoustic_spaces.engine import ray_device
from acoustic_spaces.engine.early import EarlyReflections
from acoustic_spaces.engine.model import TraceModel
from acoustic_spaces.engine.refracted import bending, covering
from acoustic_spaces.engine.vegetation import plant_arguments
from acoustic_spaces.spatial.rotation import quaternion_matrix

_DECAY = 6.0 * math.log(10.0)  # 60 dB in nepers of energy

#: Time resolution of the late energy's arrival directions (s).
DIRECTION_STEP = 0.01
#: Time resolution of the late energy as each batch of rays gives it (s), for the
#: standard errors of the parameters (:func:`stochastic_energy`).
BATCH_STEP = 0.01

#: Reception modes: (diffuse rain, specular rain) in the compiled tracer.
#:
#: - ``diffuse_rain`` (default): the scattered part of each reflection radiates to every
#:   listener it can see (Lambert); specular rays count when they cross a detector
#:   sphere. Exact on average; noisier late in rooms with smooth, reflective walls. In
#:   still air the first reflections' scattered sound is also gathered from each
#:   listener (see ``FIRST_GATHER``).
#: - ``secondary_sources``: all reflected energy radiates that way, as in ODEON's late
#:   method. Much smoother, but it spreads specular energy as if the field were
#:   diffuse: in a box with smooth walls EDT came out 20 % shorter than the other modes.
#: - ``detector``: classic ray tracing, every ray counted by the sphere.
RECEPTION = {
    "diffuse_rain": (True, False),
    "secondary_sources": (True, True),
    "detector": (False, False),
}


[docs] @dataclass class LateEnergy: """Energy per listener, band and time slot (time-integrated intensity).""" energy: np.ndarray # (listeners, bands, bins) time_step: float # s escaped_rays: int = 0 rays: int = 0 #: Rays traced, counting those split off (stochastic ray tracing only). traced_rays: int = 0 #: Arrival directions (room coordinates, towards where the energy comes from) and the #: same energy split between them (listeners, directions, bands, slots of #: ``direction_step``); empty without directions. directions: np.ndarray = field(default_factory=lambda: np.zeros((0, 3))) directional: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0, 0))) direction_step: float = DIRECTION_STEP #: With face groups (``stochastic_energy(groups=...)``): per listener, the energy in #: slots of ``moment_step`` times 1, the reflections the rays had off each group n_i, #: and n_i n_j (i <= j) (listeners, terms, bands, slots), for re-weighting the #: response for new absorption (:mod:`acoustic_spaces.engine.reweight`); else empty. moments: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0, 0))) moment_step: float = 0.0 #: Where the rays were traced (stochastic ray tracing only). plan: ray_device.Plan | None = None #: With ``stochastic_energy(batches=...)`` of 2 or more: ``energy`` as each batch of #: rays gives it (listeners, batches, bands, slots of ``batch_step``), each an #: estimate of its own and their mean ``energy``; else without batches. batches: np.ndarray = field(default_factory=lambda: np.zeros((0, 0, 0, 0))) batch_step: float = BATCH_STEP
#: Weight window of the stochastic tracer (see :func:`stochastic_energy`): resolution of #: the expected ray energy (s), how far (as a factor) a ray may stray from it before it #: is split or thinned out, the most copies per split and per original ray, and the #: fewest rays of the first batch. SPLIT_WINDOW_S = 0.05 SPLIT_RATIO = 4.0 MAX_SPLIT = 8 MAX_FAMILY = 256 MIN_FIRST_RAYS = 1000 #: Most groups of faces whose reflections the tracer counts, and the time resolution of #: the moments of those counts (s). MAX_GROUPS = 16 MOMENT_STEP = 0.01 #: Directions from each listener in which :func:`stochastic_energy` gathers the scattered #: sound of the reflections straight from the source, with diffuse rain in still air: a #: Fibonacci lattice turned at random (by the seed). The rays' rain keeps that sound #: where they land more densely than these directions do, near the source, and the #: gather takes it near the listener, where one ray landing would bring a burst. FIRST_GATHER = 16384 #: Smallest and largest automatic detector radius (m). Below about 0.5 m the specular #: part of the tail in rooms with reflective, smooth walls gets noisy at usual ray counts. RADIUS_RANGE = (0.5, 1.0) def receiver_radius( volume_m3: float | np.ndarray | None, rays: int, max_time: float, c: float, clearance: np.ndarray | float | None = None, ) -> np.ndarray | float: """Detector sphere radius: Lehnert's log10(c * t_max) * sqrt(V / (pi * N)), kept within ``RADIUS_RANGE`` and inside the room. ``volume_m3`` is the volume the rays spread over: where partitions or openings divide the model, that of all the rooms. Sized from a side room's own volume, the spheres there catch fewer rays: the same results, with half as much again spread between seeds. It may hold one volume per listener. ``clearance`` is each listener's distance to the nearest surface; a sphere reaching through a wall would read too low, so the radius stays below 90 % of it. """ if volume_m3 is None: r = np.asarray(RADIUS_RANGE[0]) else: volume = np.asarray(volume_m3, dtype=float) r = math.log10(max(c * max_time, 10.0)) * np.sqrt(volume / (math.pi * rays)) r = np.clip(r, *RADIUS_RANGE) if clearance is None: return float(r) if r.ndim == 0 else r return np.maximum(np.minimum(r, 0.9 * np.asarray(clearance, dtype=float)), 1e-3) def _exchange(model: TraceModel) -> tuple[np.ndarray, np.ndarray, np.ndarray]: """Each room's surface area (rooms,), absorption area (bands, rooms) and the area that passes sound from one room to another (bands, rooms, rooms), what passes counted as absorbed on its side. A face counts for the room on each of its sides, and one standing in a room twice.""" rooms = len(model.room_volumes) bands = model.absorption.shape[1] area = model.room.mesh.face_areas() face_room = model.face_room surface = np.zeros(rooms) absorbed = np.zeros((bands, rooms)) for side in (0, 1): ok = face_room[:, side] >= 0 np.add.at(surface, face_room[ok, side], area[ok]) np.add.at(absorbed.T, face_room[ok, side], area[ok, None] * model.absorption[ok]) passing = np.zeros((bands, rooms, rooms)) if model.transmission is not None: between = (face_room >= 0).all(axis=1) share = (area[between, None] * model.transmission[between]).T # (bands, faces) one, two = face_room[between, 0], face_room[between, 1] for b in range(bands): np.add.at(passing[b], (one, two), share[b]) np.add.at(passing[b], (two, one), share[b]) return surface, absorbed, passing def room_levels(model: TraceModel, source_room: int, air: np.ndarray) -> np.ndarray: """The weight window's level of each room relative to the source's room (see :func:`stochastic_energy`): the energy each would hold in the steady state of a diffuse field, the rooms exchanging energy through the faces between them in proportion to their area and transmission. Empty with fewer than two rooms or no transmission.""" rooms = len(model.room_volumes) if model.transmission is None or rooms < 2 or source_room < 0: return np.zeros(0) area = model.room.mesh.face_areas() volume = np.asarray(model.room_volumes, dtype=float) _, absorbed, passing = _exchange(model) energy = np.zeros((model.absorption.shape[1], rooms)) for b in range(len(energy)): # Power balance per room: (c / 4) [A_r w_r - sum over faces of S tau w_q] = P. balance = np.diag(4.0 * np.asarray(air, float)[b] * volume + 1e-12 * area.sum()) balance += np.diag(absorbed[b]) - passing[b] power = np.zeros(rooms) power[source_room] = 1.0 energy[b] = np.maximum(np.linalg.solve(balance, power), 0.0) * volume total = energy.mean(axis=0) # In powers of the window's ratio: rooms that an opening joins hold much the same, # and rays that cross between them should not be split and thinned at every pass. with np.errstate(divide="ignore"): steps = np.round(np.log(total / total[source_room]) / math.log(SPLIT_RATIO)) return np.where(total > 0.0, SPLIT_RATIO**steps, 0.0) def diffuse_decay( model: TraceModel, source: np.ndarray, points: np.ndarray, air: np.ndarray, speed_of_sound: float, ) -> tuple[np.ndarray, np.ndarray] | None: """How the diffuse field decays at ``points`` where the model holds several rooms, for :func:`statistical_energy`: amplitudes (points, bands, rooms) and rates (bands, rooms) such that the energy a unit source sends reaches a point at the sum of amplitude exp(-rate t) per second, t from emission. None with one room. Coupled-room theory: the energy density of each room i follows V_i dw_i/dt = -(c / 4) (A_i + 4 m V_i) w_i + (c / 4) sum_j S_ij tau_ij w_j, with A_i the room's absorption area after Eyring, -S_i ln(1 - a_i) with what passes counted as absorbed, m the air's attenuation and S_ij tau_ij the area that passes sound from room j. The source's sound starts in its own room. With one room it is Barron's (c / V) exp(-13.8 t / T) with Eyring's T.""" volume = np.asarray(model.room_volumes, dtype=float) if len(volume) < 2: return None source_room = int(model.room.room_of(np.asarray(source, float)[None])[0]) where = model.room.room_of(np.atleast_2d(np.asarray(points, float))) surface, absorbed, passing = _exchange(model) mean = np.minimum(absorbed / np.maximum(surface, 1e-300), 1.0 - 1e-9) eyring = -surface * np.log1p(-mean) + 4.0 * np.asarray(air, float)[:, None] * volume bands, rooms = eyring.shape amplitude = np.zeros((len(where), bands, rooms)) rate = np.zeros((bands, rooms)) scale = 1.0 / np.sqrt(volume) inside = where >= 0 for b in range(bands): # V^-1 (S tau - A) is similar to a symmetric matrix, so its modes are real. coupling = (speed_of_sound / 4.0) * scale[:, None] * (passing[b] - np.diag(eyring[b])) values, modes = np.linalg.eigh(coupling * scale[None, :]) rate[b] = np.maximum(-values, 1e-9) if source_room < 0: continue amplitude[inside, b] = ( speed_of_sound * modes[where[inside]] * modes[source_room] * (scale[where[inside], None] * scale[source_room]) ) return amplitude, rate def _split_target(ray_energy: np.ndarray, reflections: np.ndarray) -> np.ndarray: """The expected energy of a ray per window, from a first batch of rays. Never rising, and rounded to quarter octaves: splitting only needs its order of magnitude, and rounding keeps results independent of how threads sum the batch. """ mean = np.divide(ray_energy, reflections, out=np.zeros_like(ray_energy), where=reflections > 0) target = np.zeros_like(mean) level = math.inf for j, value in enumerate(mean): if value > 0: level = min(level, value) target[j] = level if math.isfinite(level) else 0.0 with np.errstate(divide="ignore"): quarter_octaves = np.round(4.0 * np.log2(target)) return np.where(target > 0, np.exp2(quarter_octaves / 4.0), 0.0) def _in_batches( trace, rays: int, splitting: bool, own: np.ndarray | None = None, batches: int = 1, coarse: int = 1, ): """Runs ``trace(count, first, target)``, which returns (arrays, escaped rays, ray_energy, reflections, traced rays), for all ``rays``: at once, or with ``splitting`` in two batches where the second uses the weight window measured by the first. Returns (arrays, escaped rays, traced rays, estimates), each array the mean of the batches weighted by their share of rays. With ``batches`` of 2 or more, each of those is traced in that many runs of about equal size. Each ray has its own random stream, and its run's rays carry their share of the energy, as does their weight window, so the runs trace the rays one run would: only rounding can tip a split or a roulette the other way. ``estimates`` is then the energy (the first array) as each run and its part of the first batch give it, an estimate of its own, in slots of ``coarse`` of the energy's (rows, batches, bands, slots), weighted so that their mean is the energy; else it has no batches. ``own`` says for each row of the arrays (listener or map point) whether it lies in the source's room. The first batch sends few rays to the other rooms (no copies pass into them), so rows elsewhere take the second batch alone.""" first = max(min(rays // 2, MIN_FIRST_RAYS), rays // 10, 1) if splitting else rays parts = max(1, min(batches, first, rays - first if first < rays else rays)) arrays: list[np.ndarray] = [] estimates = np.zeros(0) escaped = traced = 0 def rows(factor: np.ndarray, a: np.ndarray) -> np.ndarray: return factor.reshape(-1, *[1] * (a.ndim - 1)) def summed(energy: np.ndarray) -> np.ndarray: return np.add.reduceat(energy, np.arange(0, energy.shape[-1], coarse), axis=-1) def run(count: int, start: int, target: np.ndarray, scale: np.ndarray | None): """Traces rays ``start`` .. ``start + count - 1`` and adds them to ``arrays`` (and each run to ``estimates``), times ``scale`` per row: the first batch with None, which also returns its ray_energy and reflections.""" nonlocal estimates, escaped, traced ray_energy = reflections = np.zeros(0) edges = [start + count * k // parts for k in range(parts + 1)] for k in range(parts): n = edges[k + 1] - edges[k] found, more_escaped, more_energy, more_reflections, more_traced = trace( n, edges[k], target * (count / n) ) weight = n / count if parts > 1: estimate = summed(found[0]) if scale is None: if k == 0: estimates = np.empty((len(estimate), parts, *estimate.shape[1:])) estimate *= weight * parts estimates[:, k] = estimate else: estimate *= rows(scale * (weight * parts), estimate) estimates[:, k] += estimate if scale is None: if k == 0: for a in found: a *= weight arrays.extend(found) ray_energy, reflections = more_energy * weight, more_reflections else: for a, b in zip(arrays, found, strict=True): b *= weight a += b ray_energy = ray_energy + more_energy * weight reflections = reflections + more_reflections else: # In place, so that the batches take no more memory than one run's arrays # besides the sums. for a, b in zip(arrays, found, strict=True): b *= rows(scale * weight, b) a += b del found escaped += more_escaped traced += more_traced return ray_energy, reflections ray_energy, reflections = run(first, 0, np.zeros(0), None) if first < rays: # Each batch carries the whole source energy; weight them by their share of rays. target = _split_target(ray_energy, reflections) * first / (rays - first) share = np.full(len(arrays[0]), first / rays) if own is not None: share = np.where(own, share, 0.0) for a in [*arrays, estimates] if parts > 1 else arrays: a *= rows(share, a) run(rays - first, first, target, 1.0 - share) if parts == 1: energy = arrays[0] estimates = np.zeros((len(energy), 0, *energy.shape[1:-1], 0)) return arrays, escaped, traced, estimates def _rooms(model: TraceModel, source: np.ndarray, air: np.ndarray, points) -> tuple: """The tracer's transmission arguments for a source: face_room, source_room and room_level, and whether each of ``points`` (listeners or map points) lies in the source's room (None when there is nothing to tell apart).""" if model.transmission is None or len(model.room_volumes) == 0: return np.zeros((0, 2), dtype=np.int64), -1, np.zeros(0), None source_room = int(model.room.room_of(np.asarray(source, float)[None])[0]) level = room_levels(model, source_room, air) own = None if len(level): own = model.room.room_of(points) == source_room return np.ascontiguousarray(model.face_room, dtype=np.int64), source_room, level, own def band_groups(model: TraceModel) -> list[slice]: """The bands each ray carries. Where the bands' scattering coefficients differ (the scattering of a surface's size always makes them differ), every band is traced with rays of its own. One ray for all bands would, with vector-based scattering, turn the treble as much as the bass. With random scattering it goes diffusely with the bands' mean coefficient as probability, and each band's energy is re-weighted by its own coefficient over that mean: right on average, but over many reflections a band's weight drifts towards zero and its energy rides on a few rays. With the same coefficient in every band, one ray carries them all; so it does when the model asks for one ray for all bands (``by_band`` off). Either way each band has the rays asked for, so tracing band by band traces that many rays per band.""" return group_bands( model.absorption, model.scattering, sized=model.surface_size is not None, by_band=model.by_band, ) def group_bands( absorption: np.ndarray, scattering: np.ndarray, *, sized: bool, by_band: bool ) -> list[slice]: """:func:`band_groups` for surfaces of ``absorption`` and ``scattering`` (rows of bands), with the scattering of their size (``sized``) and ``by_band``.""" bands = np.shape(absorption)[1] # Faces that reflect nothing (openings) scatter nothing either. scattering = np.asarray(scattering)[np.any(np.asarray(absorption) < 1.0, axis=1)] uniform = bool(np.all(scattering == scattering[:, :1])) if sized: uniform = uniform and bool(np.all(scattering == 1.0)) # fully diffuse at any size if not by_band or uniform: return [slice(0, bands)] return [slice(b, b + 1) for b in range(bands)] def _by_band(groups: list[slice], rays: int, run) -> tuple[list[np.ndarray], int, int]: """Runs ``run(group, rays)`` (returning arrays with bands on their second last axis, escaped rays and traced rays) for each group of bands, so every band has ``rays`` rays, and joins the arrays along the band axis. Each group's arrays go into the joined ones as soon as it is done, so no more than one group's are held besides.""" if len(groups) == 1: arrays, escaped, traced = run(groups[0], rays) return list(arrays), escaped, traced bands = max(group.stop for group in groups) joined: list[np.ndarray] = [] escaped = traced = 0 for group in groups: arrays, more_escaped, more_traced = run(group, rays) if not joined: joined = [np.empty((*a.shape[:-2], bands, a.shape[-1])) for a in arrays] for whole, part in zip(joined, arrays, strict=True): whole[..., group, :] = part del arrays, part escaped += more_escaped traced += more_traced return joined, escaped, traced def gather_turn(seed: int) -> np.ndarray: """The rotation (3, 3), uniformly at random for ``seed``, that turns the lattice of directions of :func:`stochastic_energy`'s gather: with it every direction is equally likely anywhere, so the gather is unbiased in every time slot, not only in sum.""" rng = np.random.default_rng((int(seed) & 0xFFFFFFFFFFFFFFFF, 0x67617468)) return np.ascontiguousarray(quaternion_matrix(*rng.normal(size=4))) def _directivity_arrays(directivity: Directivity | None, orientation, bands: int): if directivity is None: directivity_a, table = np.zeros(0), np.zeros((0, 0, bands)) else: directivity_a, table = directivity.native() orientation = np.eye(3) if orientation is None else np.asarray(orientation, float) return ( np.ascontiguousarray(directivity_a, dtype=np.float64), np.ascontiguousarray(orientation, dtype=np.float64), np.ascontiguousarray(table, dtype=np.float64), ) #: The tracer's arguments that _band_arguments gives last, in order. _SIZE_ARGUMENTS = ( "surface_size", "band_hz", "vector_scattering", "size_from_order", "transmission", ) def _band_arguments(model: TraceModel, air: np.ndarray, directivity: tuple, band: slice) -> tuple: """For the bands ``band``: the tracer's directivity_a and directivity_table (from ``directivity``, both arrays for all bands), absorption, scattering and air, and the arguments surface_size, band_hz, vector_scattering, size_from_order and transmission.""" first_order, table = directivity if model.surface_size is None: size, hz = np.zeros((0, 2)), np.zeros(0) else: size = np.ascontiguousarray(model.surface_size, dtype=np.float64) hz = np.ascontiguousarray(np.asarray(model.band_hz, dtype=np.float64)[band]) if model.transmission is None: passing = np.zeros((0, 0)) else: passing = np.ascontiguousarray(model.transmission[:, band], dtype=np.float64) return ( np.ascontiguousarray(first_order[band] if len(first_order) else first_order), np.ascontiguousarray(table[..., band]), np.ascontiguousarray(model.absorption[:, band], dtype=np.float64), np.ascontiguousarray(model.scattering[:, band], dtype=np.float64), np.ascontiguousarray(np.asarray(air, dtype=np.float64)[band]), (size, hz, bool(model.vector_scattering), int(model.size_from_order), passing), ) def stochastic_energy( model: TraceModel, source: np.ndarray, listeners: np.ndarray, *, rays: int, max_time: float, time_step: float, speed_of_sound: float, air: np.ndarray, reception: str = "diffuse_rain", covered_order: int = -1, covered_time: np.ndarray | None = None, radius: np.ndarray | float | None = None, directions: np.ndarray | None = None, splitting: bool = True, seed: int = 0, directivity: Directivity | None = None, orientation: np.ndarray | None = None, threads: int = 0, groups: np.ndarray | None = None, moment_step: float = MOMENT_STEP, device: str | ray_device.Plan = "cpu", batches: int = 1, gather: int | None = None, ) -> LateEnergy: """Energy per listener, band and time slot by stochastic ray tracing. Specular-only paths with up to ``covered_order`` reflections reaching listener k no later than ``covered_time[k]`` (s, from emission) are left out; ``None`` puts no time limit on that. Where the atmosphere bends the sound, the order counts as the early stage's there (:func:`~acoustic_spaces.engine.refracted.covering`). With ``directions`` (unit vectors in room coordinates), each arrival is also counted at the nearest of them, every ``DIRECTION_STEP``. With ``splitting``, a first tenth of the rays (at least ``MIN_FIRST_RAYS``, or half of them when there are fewer than twice that) measures how much energy a ray usually carries over time; the rest are split when they carry much more and thinned out by Russian roulette when they carry much less (a weight window). The result is unbiased either way, but late tails in rooms where a few rays escape the absorption for a long time (smooth walls, absorption on the ceiling) no longer break up when those rays run out. ``groups`` (one per face: a group index, or -1) has the tracer count the reflections off each group and sum the moments of those counts in the result's ``moments``, at most ``MAX_GROUPS`` groups. ``device`` says where the rays are traced: cpu, gpu, both or auto (see :mod:`acoustic_spaces.engine.ray_device`), or a ``ray_device.Plan`` to follow; the result's ``plan`` says where they went. With ``batches`` of 2 or more the rays are traced in that many batches, the same rays as at once (only rounding can tip a split or a roulette the other way), and the result's ``batches`` holds the energy as each gives it, in slots of about ``BATCH_STEP``, for the standard errors of what comes from it (:meth:`~acoustic_spaces.engine.response.Response.standard_errors`). With diffuse rain alone (``reception`` diffuse_rain) and rays that go straight, the scattered sound of each reflection straight from the source is shared between the rays' rain and a gather from each listener in ``gather`` directions (None: ``FIRST_GATHER``; 0: the rain keeps it all), as the two would find it most densely (the balance heuristic): the same expected energy, without the burst a ray landing next to a listener brings. The gather runs on the CPU for all bands at once, adding into the traced arrays, its directions dealt out to the batches in turn. """ if reception not in RECEPTION: raise ValueError(f"unknown reception {reception!r}; use one of {', '.join(RECEPTION)}") if reception == "secondary_sources" and covered_order < 0: raise ValueError("secondary_sources reception needs the early stage (covered_order >= 0)") diffuse_rain, specular_rain = RECEPTION[reception] listeners = np.ascontiguousarray(np.atleast_2d(listeners), dtype=np.float64) covered = np.zeros(0) if covered_time is None else np.asarray(covered_time, float) if radius is None: radius = receiver_radius(model.room.volume_m3, rays, max_time, speed_of_sound) radius = np.broadcast_to(np.asarray(radius, dtype=np.float64), (len(listeners),)) directions = np.zeros((0, 3)) if directions is None else np.asarray(directions, float) directivity_a, orientation, table = _directivity_arrays( directivity, orientation, model.absorption.shape[1] ) face_room, source_room, level, own = _rooms(model, source, air, listeners) bent = bending(model) cover = covering(model) coarse = max(1, round(BATCH_STEP / time_step)) if groups is None: face_group, n_groups = np.zeros(0, dtype=np.int64), 0 else: face_group = np.ascontiguousarray(groups, dtype=np.int64) n_groups = int(face_group.max(initial=-1)) + 1 if n_groups > MAX_GROUPS: raise ValueError(f"at most {MAX_GROUPS} groups of faces, not {n_groups}") if gather is None: gather = FIRST_GATHER gathering = ( gather > 0 and diffuse_rain and not specular_rain and not bent and len(listeners) > 0 ) # Every batch, band group and device traces with the same share, so that the rain's # and the gather's add up to one wherever the rays land. ratio = gather / rays if gathering else 0.0 # Where the rays go, chosen at the first batch. plans: list[ray_device.Plan] = [] def run(band: slice, count: int): first_order, band_table, absorption, scattering, band_air, sizes = _band_arguments( model, air, (directivity_a, table), band ) def trace(count: int, first: int, target: np.ndarray): values = { "bvh": model.bvh, "source": np.asarray(source, dtype=np.float64), "directivity_a": first_order, "orientation": orientation, "directivity_table": band_table, "absorption": absorption, "scattering": scattering, "air": band_air, **dict(zip(_SIZE_ARGUMENTS, sizes, strict=True)), "face_room": face_room, "source_room": source_room, "receivers": listeners, "directions": np.ascontiguousarray(directions.reshape(-1, 3)), "rays": int(count), "max_time": float(max_time), "time_step": float(time_step), "dir_time_step": DIRECTION_STEP, "speed_of_sound": float(speed_of_sound), "receiver_radius": np.ascontiguousarray(radius), "diffuse_rain": bool(diffuse_rain), "specular_rain": bool(specular_rain), "covered_order": int(covered_order), "covered_time": np.ascontiguousarray(covered, dtype=np.float64), "seed": int(seed) & 0xFFFFFFFFFFFFFFFF, "threads": int(threads), "window_time_step": SPLIT_WINDOW_S, "first_ray": int(first), "split_target": np.ascontiguousarray(target, dtype=np.float64), "split_ratio": SPLIT_RATIO, "max_split": MAX_SPLIT, "max_family": MAX_FAMILY, "room_level": level, "face_group": face_group, "groups": n_groups, "moment_time_step": float(moment_step), **bent, **plant_arguments(model, band), "gather_ratio": ratio, **cover, } if not plans: plans.append(ray_device.choose(device, values)) found, plans[0] = ray_device.trace(plans[0], values, keep=True) energy, directional, moments, *rest = found return [energy, directional, moments], *rest arrays, escaped, traced, estimates = _in_batches( trace, count, splitting, own, batches, coarse ) return [*arrays, estimates], escaped, traced try: (energy, directional, moments, estimates), escaped, traced = _by_band( band_groups(model), rays, run ) finally: ray_device.release() if gathering: from acoustic_spaces import _native first_order, band_table, absorption, scattering, band_air, sizes = _band_arguments( model, air, (directivity_a, table), slice(None) ) surface_size, band_hz, _, size_from_order, transmission = sizes arguments = { "bvh": model.bvh, "source": np.asarray(source, dtype=np.float64), "directivity_a": first_order, "orientation": orientation, "directivity_table": band_table, "absorption": absorption, "scattering": scattering, "air": band_air, "surface_size": surface_size, "band_hz": band_hz, "size_from_order": size_from_order, "transmission": transmission, "face_room": face_room, "source_room": source_room, "receivers": listeners, "directions": np.ascontiguousarray(directions.reshape(-1, 3)), "max_time": float(max_time), "time_step": float(time_step), "dir_time_step": DIRECTION_STEP, "speed_of_sound": float(speed_of_sound), "receiver_radius": np.ascontiguousarray(radius), "threads": int(threads), "face_group": face_group, "groups": n_groups, "moment_time_step": float(moment_step), "gather_ratio": ratio, "samples": int(gather), "turn": gather_turn(seed), **plant_arguments(model, slice(None)), } # Added into the traced arrays, so that the gather takes no memory of its own. energy, directional, moments = ( np.require(a, np.float64, ("C", "W")) for a in (energy, directional, moments) ) # The lattice's directions are dealt out to the batches in turn, so that each # batch's estimate carries the gather's error as well as its rays': what a call # adds to the energy, times the batches, goes into its batch's estimate. parts = estimates.shape[1] slots = np.arange(0, energy.shape[-1], coarse) def slot_sums(k: int, factor: float) -> None: # A band at a time, so that the sums take next to no memory of their own. for band in range(energy.shape[1]): summed = np.add.reduceat(energy[:, band], slots, axis=-1) summed *= factor estimates[:, k, band] += summed for k in range(max(parts, 1)): if parts: slot_sums(k, -parts) _native.gather_first_scattering( **arguments, energy=energy, directional=directional, moments=moments, first=k, stride=max(parts, 1), ) if parts: slot_sums(k, parts) return LateEnergy( energy=energy, time_step=time_step, escaped_rays=int(escaped), rays=rays, traced_rays=int(traced), directions=directions, directional=directional, moments=moments, moment_step=float(moment_step) if n_groups else 0.0, plan=plans[0] if plans else None, batches=estimates, batch_step=coarse * time_step, ) #: Time bins of coverage maps, counted from each point's direct sound: 1 ms for the #: first 100 ms, then 10 ms. MAP_FINE_STEP = 1e-3 MAP_FINE_BINS = 100 MAP_COARSE_STEP = 1e-2 @dataclass class MapEnergy: """Energy per map point, band and time bin (time-integrated intensity), with bins counted from each point's ``onset``: ``fine_bins`` of ``fine_step``, then ``coarse_step``.""" energy: np.ndarray # (points, bands, bins) onset: np.ndarray # (points,) s from emission fine_step: float = MAP_FINE_STEP fine_bins: int = MAP_FINE_BINS coarse_step: float = MAP_COARSE_STEP rays: int = 0 escaped_rays: int = 0 traced_rays: int = 0 def stochastic_map_energy( model: TraceModel, source: np.ndarray, grid, onset: np.ndarray, *, rays: int, max_time: float, speed_of_sound: float, air: np.ndarray, covered_order: int = -1, covered_time: np.ndarray | None = None, splitting: bool = True, seed: int = 0, directivity: Directivity | None = None, orientation: np.ndarray | None = None, threads: int = 0, ) -> MapEnergy: """Energy over a coverage map (a :class:`~acoustic_spaces.engine.coverage.MapGrid`) by stochastic ray tracing: every leg of every ray counts its track length through each point's slab of air, where the model holds several rooms only that of a ray in the point's room. ``onset`` is the arrival of the direct sound at each point (s); ``covered_order``, ``covered_time`` (per point), ``splitting`` and the rest are as for :func:`stochastic_energy`. Where the model has a ``deciding`` absorption, that one decides for the rays wherever the energy they carry does: how the weight window splits them and thins them out, with the rooms' levels it has, and whether one passes a partition or reflects off it. The run then follows the rays of the run with that absorption, the seed being the same, and counts on them the energy its own absorption leaves: the two differ by what the absorption does and not by their rays.""" from acoustic_spaces import _native n = len(grid.points) onset = np.ascontiguousarray(np.broadcast_to(np.asarray(onset, float), (n,))) if covered_time is None: covered = np.full(n, math.inf) else: covered = np.ascontiguousarray(np.broadcast_to(np.asarray(covered_time, float), (n,))) directivity_a, orientation, table = _directivity_arrays( directivity, orientation, model.absorption.shape[1] ) deciding = model.deciding ruling = model if deciding is None else replace(model, absorption=deciding) face_room, source_room, level, own = _rooms(ruling, source, air, grid.points) if model.transmission is None and len(model.room_volumes) > 1: # Nothing lets sound through: every ray stays in the source's room. source_room = int(model.room.room_of(np.asarray(source, float)[None])[0]) bent = bending(model) cover = covering(model) def run(band: slice, count: int): first_order, band_table, absorption, scattering, band_air, sizes = _band_arguments( model, air, (directivity_a, table), band ) pinned = {} if deciding is not None: pinned["deciding"] = np.ascontiguousarray(deciding[:, band], dtype=np.float64) def trace(count: int, first: int, target: np.ndarray): energy, *rest = _native.trace_map( model.bvh, np.asarray(source, dtype=np.float64), first_order, orientation, band_table, absorption, scattering, band_air, *sizes, face_room, source_room, np.asarray(grid.origin, dtype=np.float64), float(grid.cell), np.ascontiguousarray(grid.index, dtype=np.int64), np.ascontiguousarray(grid.low, dtype=np.float64), np.ascontiguousarray(grid.high, dtype=np.float64), np.ascontiguousarray(grid.volume, dtype=np.float64), np.ascontiguousarray(grid.room, dtype=np.int64), onset, covered, MAP_FINE_STEP, MAP_FINE_BINS, MAP_COARSE_STEP, int(count), float(max_time), float(speed_of_sound), int(covered_order), int(seed) & 0xFFFFFFFFFFFFFFFF, int(threads), SPLIT_WINDOW_S, int(first), np.ascontiguousarray(target, dtype=np.float64), SPLIT_RATIO, MAX_SPLIT, MAX_FAMILY, level, **bent, **plant_arguments(model, band), **cover, **pinned, ) return [energy], *rest arrays, escaped, traced, _ = _in_batches(trace, count, splitting, own) return arrays, escaped, traced (energy,), escaped, traced = _by_band(band_groups(model), rays, run) return MapEnergy( energy=energy, onset=onset, rays=rays, escaped_rays=int(escaped), traced_rays=int(traced), ) def statistical_energy( reverberation_time: np.ndarray, volume_m3: float, direct_times: np.ndarray, early: Sequence[EarlyReflections] = (), *, max_time: float, time_step: float, speed_of_sound: float, decay: tuple[np.ndarray, np.ndarray] | None = None, ) -> LateEnergy: """Energy per listener, band and time slot of a diffuse field, less the early paths. In Barron's revised theory the reflected energy of a unit source arrives from the direct sound (``direct_times``, s from emission) on at (c / V) exp(-13.8 t / T) per second, t from emission and T the ``reverberation_time`` (``simulate`` passes Eyring's, with air absorption). Its total, c T / (13.8 V) exp(-13.8 t_d / T), is 4 / A exp(-13.8 t_d / T) with A = -S ln(1 - a) the absorption area behind Eyring's T: the Sabine form, as Barron has it. It leaves out that the first reflection is already absorbed, as the classical 4 (1 - a) / (a S) does not, so it reads 0.2 dB higher at a mean absorption of 0.1 and 0.8 dB higher at 0.3. ``early`` holds each listener's early paths, part of that energy: the specular share of reflections up to the early stage's order, until its transition. The late part is everything else: the scattered share of each early reflection, the higher orders before the transition and the whole field after it. It is Barron's energy less that of the early paths (the direct sound aside), slot by slot. Where an early path brings more than Barron's decay has delivered by its arrival, the late energy before it makes up the difference: its running sum is the largest that never falls and never rises above Barron's less the early paths'. No slot goes negative and the total stays Barron's, unless the early paths alone carry more. Where partitions or openings divide the model into rooms, ``decay`` (from :func:`diffuse_decay`) gives each listener's field as coupled-room theory has it, in place of ``reverberation_time`` and ``volume_m3``: a room joined to a livelier one decays in two slopes, and one behind a partition holds less. """ t60 = np.asarray(reverberation_time, dtype=float) starts = np.asarray(direct_times, dtype=float) if decay is None: rate = _DECAY / t60[:, None] # (bands, 1) amplitude = np.broadcast_to(speed_of_sound / volume_m3, (len(starts), len(t60), 1)) else: amplitude, rate = decay bins = int(math.ceil(max_time / time_step)) edges = np.arange(bins + 1) * time_step out = np.zeros((len(starts), len(t60), bins)) for i, start in enumerate(starts): # Integral of (c / V) exp(-rate t) (in each room's modes, with several) from the # direct sound to each slot edge, less the early reflections arrived by then. r = rate[:, :, None] arrived = ( amplitude[i][:, :, None] / r * (np.exp(-r * start) - np.exp(-r * np.maximum(edges, start))) ).sum(axis=1) if i < len(early): paths = early[i] slot = np.maximum(paths.delay_s / time_step, 0.0).astype(np.int64) keep = (paths.order > 0) & (slot < bins) per_slot = np.zeros((bins, len(t60))) np.add.at(per_slot, slot[keep], paths.energy[keep]) arrived[:, 1:] -= np.cumsum(per_slot, axis=0).T # The largest non-decreasing curve from zero that stays below it. late = np.maximum(np.minimum.accumulate(arrived[:, ::-1], axis=1)[:, ::-1], 0.0) out[i] = np.diff(late, axis=1) return LateEnergy(energy=out, time_step=time_step)