Source code for acoustic_spaces.engine.particles

"""Sound particles: where the energy leaving a source is at each moment, for animations.

Particles leave the source evenly in all directions, weighted by its directivity, and
travel at the speed of sound. At each wall they lose the absorbed share of their
energy in the chosen octave band (and some to the air on the way) and reflect as in
the stochastic tracer: by default between the specular direction and a random Lambert
direction, weighted by the wall's scattering coefficient in that band (with the
scattering of the wall's size added), or, with the scene's random scattering,
specularly or with the scattering coefficient as probability in a Lambert direction.
At a surface that lets sound through, a particle passes straight on with the share of
the surviving energy that passes and reflects otherwise, keeping all that survives, so
openings let every particle through. Particles that find a gap in an open model fly on
out of it.

Outdoors in wind or a temperature gradient, particles follow the bent rays of the late
stage (:func:`~acoustic_spaces.engine.refracted.bending`): chord by chord along their
arcs, at the speed along each, and once out of the model (through the open sky) they
fly on along their last chord.
"""

from __future__ import annotations

from dataclasses import dataclass

import numpy as np

from acoustic_spaces.engine.model import TraceModel, size_scattering, source_weights
from acoustic_spaces.engine.refracted import bending
from acoustic_spaces.room import Room
from acoustic_spaces.spatial.directions import fibonacci_sphere

#: Particles stop at this many reflections even if time remains.
MAX_REFLECTIONS = 200
#: Steps (a chord each) bent particles take at most.
MAX_CHORDS = 5000


[docs] @dataclass class Particles: """Positions of sound particles at a series of times.""" times: np.ndarray # (frames,) s after emission positions: np.ndarray # (frames, particles, 3) m #: Energy relative to a particle's share at emission (frames, particles). energy: np.ndarray #: Reflections so far (frames, particles). order: np.ndarray band_hz: int #: Name of the source the particles left. source: str = ""
def _lambert(normals: np.ndarray, rng: np.random.Generator) -> np.ndarray: """Cosine-weighted directions around each unit normal.""" u, v = rng.random(len(normals)), rng.random(len(normals)) r, phi = np.sqrt(u), 2.0 * np.pi * v local = np.column_stack([r * np.cos(phi), r * np.sin(phi), np.sqrt(1.0 - u)]) helper = np.where(np.abs(normals[:, :1]) < 0.9, [[1.0, 0.0, 0.0]], [[0.0, 1.0, 0.0]]) t1 = np.cross(normals, helper) t1 /= np.linalg.norm(t1, axis=1, keepdims=True) t2 = np.cross(normals, t1) return local[:, :1] * t1 + local[:, 1:2] * t2 + local[:, 2:] * normals def _reflection(model: TraceModel, face, d, dist, alive, order, band: int, c: float, rng): """Where particles arriving along ``d`` (unit) at ``face`` (-1: none), ``dist`` metres from the source or their last reflection (through the faces they passed), with ``order`` reflections then, go next: their directions, the share of their energy that survives the face (before the air), which of them passed through it, and the face's normal on their side.""" count = len(face) normal = model.plane_normal[model.face_plane[np.maximum(face, 0)]] # Point the normal back at the arriving particle, whichever way the face faces. normal = np.where((np.einsum("ij,ij->i", normal, d) > 0)[:, None], -normal, normal) specular = d - 2.0 * np.einsum("ij,ij->i", d, normal)[:, None] * normal s = model.scattering[np.maximum(face, 0), band] sized = np.asarray(order) >= model.size_from_order if model.surface_size is not None and np.any(sized): hit_face = np.maximum(face, 0) width, length = model.surface_size[hit_face].T cosine = np.abs(np.einsum("ij,ij->i", normal, d)) leg = np.maximum(dist, 1e-9) bigger = size_scattering(width, length, leg, cosine, c, model.scattering[hit_face])[:, band] s = np.where(sized, bigger, s) if model.vector_scattering: mixed = s[:, None] * _lambert(normal, rng) + (1.0 - s[:, None]) * specular new_d = mixed / np.linalg.norm(mixed, axis=1, keepdims=True) else: new_d = np.where((rng.random(count) < s)[:, None], _lambert(normal, rng), specular) kept = 1.0 - model.absorption[np.maximum(face, 0), band] passed = np.zeros(count, dtype=bool) if model.transmission is not None: through = model.transmission[np.maximum(face, 0), band] survives = kept + through share = through / np.where(survives > 0.0, survives, 1.0) passed = alive & (rng.random(count) < share) new_d = np.where(passed[:, None], d, new_d) kept = survives return new_d, kept, passed, normal
[docs] def trace_particles( room: Room, source: str | None = None, *, count: int = 4000, duration: float = 0.1, frames: int = 100, band: int = 4, seed: int = 0, ) -> Particles: """Trace ``count`` particles from ``source`` (default: the first) for ``duration`` seconds and sample them at ``frames`` evenly spaced times from 0 to ``duration``. ``band`` picks the octave band whose absorption and scattering apply (4 = 1 kHz). """ from acoustic_spaces.materials import OCTAVE_BANDS_HZ scene = room.scene sources = {s.name: s for s in scene.sources} if source is None: source = next((s.name for s in scene.sources if s.in_use), scene.sources[0].name) if source not in sources: raise ValueError(f"no source {source!r}; the scene has {', '.join(sources)}") if count < 1 or frames < 1 or duration <= 0: raise ValueError("count and frames must be positive, and so must duration") if not 0 <= band < len(OCTAVE_BANDS_HZ): raise ValueError(f"band must be 0 to {len(OCTAVE_BANDS_HZ) - 1}") spec = sources[source] # In octave bands, whatever bands the scene simulates in. model = TraceModel.from_room(room, scene.simulation.model_copy(update={"bands": "octave"})) rng = np.random.default_rng(seed) c = room.speed_of_sound() air = float(room.air_attenuation()[band]) # energy, per metre # A line or surface source's points take turns: each sends every n-th particle. elements = spec.elements() origins = elements[np.arange(count) % len(elements)] directions = fibonacci_sphere(count) rotation = np.asarray(spec.orientation.rotation(), dtype=float) energy = source_weights(room.directivity(source), rotation, directions)[:, band] # Segments: particle k leaves start[s, k] at time t0[s, k] along direction[s, k]. t0 = [np.zeros(count)] start = [origins] direction = [directions] energies = [energy] reflections = [np.zeros(count, dtype=np.int64)] alive = np.ones(count, dtype=bool) face = np.full(count, -1, dtype=np.int64) bent = bending(model) if bent: return _bent_particles( model, bent, (origins, directions, energy), rng, duration, frames, band, c, air, source, ) leg = np.zeros(count) # metres since the last reflection for _ in range(MAX_REFLECTIONS): p, d, t = start[-1], direction[-1], t0[-1] reach = np.where(alive, np.inf, 0.0) dist, hit = model.intersect(p, d, reach, face) alive &= hit >= 0 dist = np.where(alive, dist, 0.0) face = np.where(alive, hit, -1) leg = leg + dist new_d, kept, passed, _ = _reflection( model, face, d, leg, alive, reflections[-1] + 1, band, c, rng ) leg = np.where(passed, leg, 0.0) kept = kept * np.exp(-air * dist) # A particle that escaped keeps flying along its last segment (no next one). t_next = np.where(alive, t + dist / c, np.inf) t0.append(t_next) start.append(np.where(alive[:, None], p + dist[:, None] * d, p)) direction.append(np.where(alive[:, None], new_d, d)) energies.append(np.where(alive, energies[-1] * kept, energies[-1])) reflections.append(reflections[-1] + (alive & ~passed)) if not np.any(alive & (t_next <= duration)): break alive &= t_next <= duration # Particles still in flight after MAX_REFLECTIONS stop where the last one left them. t0.append(np.where(alive, t0[-1], np.inf)) start.append(start[-1]) direction.append(np.where(alive[:, None], 0.0, direction[-1])) energies.append(energies[-1]) reflections.append(reflections[-1]) t0_all, start_all = np.array(t0), np.array(start) direction_all, energy_all = np.array(direction), np.array(energies) reflections_all = np.array(reflections) times = np.linspace(0.0, duration, frames) positions = np.zeros((frames, count, 3)) energy_out = np.zeros((frames, count)) order_out = np.zeros((frames, count), dtype=np.int64) columns = np.arange(count) for f, time in enumerate(times): s = np.sum(t0_all <= time, axis=0) - 1 # the latest segment begun elapsed = time - t0_all[s, columns] positions[f] = start_all[s, columns] + c * elapsed[:, None] * direction_all[s, columns] energy_out[f] = energy_all[s, columns] * np.exp(-air * c * elapsed) order_out[f] = reflections_all[s, columns] return Particles(times, positions, energy_out, order_out, OCTAVE_BANDS_HZ[band], source)
def _bent_particles(model, bent, start, rng, duration, frames, band, c, air, source): """Particles leaving at ``start`` (origins, directions, energies) along the rays of an atmosphere (``bent``, from :func:`~acoustic_spaces.engine.refracted.bending`), chord by chord.""" from acoustic_spaces import _native from acoustic_spaces.materials import OCTAVE_BANDS_HZ pos, d, e = (np.array(a, dtype=float) for a in start) count = len(pos) rows = bent["atmosphere"] # Faster than any sound in it: a chord this long per second left reaches the end. fastest = float(np.max(rows[:, 1] + np.abs(rows[:, 2]))) vertices = model.room.mesh.vertices pad = 1e-6 * float(np.ptp(vertices, axis=0).max()) low, high = vertices.min(axis=0) - pad, vertices.max(axis=0) + pad t = np.zeros(count) reflections = np.zeros(count, dtype=np.int64) face = np.full(count, -1, dtype=np.int64) away = np.zeros((count, 3)) # the face a particle left (zero: none), while it leaves it leg = np.zeros(count) # metres since the last reflection flying = np.ones(count, dtype=bool) # in the model, before the end stopped = np.zeros(count, dtype=bool) # at MAX_REFLECTIONS # Segments: particle k leaves start[s, k] at time t0[s, k] along direction[s, k] at # speed[s, k] (m/s along the chord), its path growing at pace[s, k] (m/s). t0, starts, directions, speeds, paces, energies, orders = [], [], [], [], [], [], [] for _ in range(MAX_CHORDS): moving = flying & ~stopped & (t < duration) if not moving.any(): break budget = np.where(moving, (duration - t) * fastest + 1e-9, 0.0) end, tangent, arc, time, turned = _native.bent_chords(pos, d, budget, away, **bent) span = end - pos length = np.linalg.norm(span, axis=1) chord = length > 0.0 along = np.where(chord[:, None], span / np.where(chord, length, 1.0)[:, None], d) dist, hit = model.intersect(pos, along, np.where(moving & chord, length, 0.0), face) met = moving & chord & (hit >= 0) share = np.where(met, np.where(met, dist, 0.0) / np.where(chord, length, 1.0), 1.0) timed = time > 0.0 t0.append(np.where(moving, t, np.where(stopped, t, np.inf))) starts.append(pos.copy()) directions.append(along) speeds.append(np.where(moving & timed, length / np.where(timed, time, 1.0), 0.0)) paces.append(np.where(moving & timed, arc / np.where(timed, time, 1.0), 0.0)) energies.append(e.copy()) orders.append(reflections.copy()) travelled = arc * share t = t + time * share e = e * np.exp(-air * travelled) leg = leg + travelled pos = np.where(met[:, None], pos + along * np.where(met, dist, 0.0)[:, None], end) arriving = tangent if met.any(): pick = np.flatnonzero(met) # The ray's own direction where it meets the face. _, there, *_ = _native.bent_chords( starts[-1][pick], d[pick], travelled[pick], away[pick], **bent ) arriving = tangent.copy() arriving[pick] = there new_d, kept, passed, normal = _reflection( model, np.where(met, hit, -1), arriving, leg, met, reflections + 1, band, c, rng ) e = np.where(met, e * kept, e) d = np.where(met[:, None], new_d, arriving) leaving = np.where(passed[:, None], -normal, normal) away = np.where(met[:, None], leaving, np.where(turned[:, None] > 0, 0.0, away)) face = np.where(met, hit, np.where(turned > 0, -1, face)) reflected = met & ~passed reflections = reflections + reflected leg = np.where(reflected, 0.0, leg) stopped |= reflections >= MAX_REFLECTIONS # Out of the model, through the open sky: it flies on along its last chord. flying &= np.all((pos >= low) & (pos <= high), axis=1) # Where each stops, for those that stopped. t0.append(np.where(stopped, t, np.inf)) starts.append(pos) directions.append(d) speeds.append(np.zeros(count)) paces.append(np.zeros(count)) energies.append(e) orders.append(reflections) t0_all, start_all, direction_all = np.array(t0), np.array(starts), np.array(directions) speed_all, pace_all = np.array(speeds), np.array(paces) energy_all, order_all = np.array(energies), np.array(orders) times = np.linspace(0.0, duration, frames) positions = np.zeros((frames, count, 3)) energy_out = np.zeros((frames, count)) order_out = np.zeros((frames, count), dtype=np.int64) columns = np.arange(count) for f, when in enumerate(times): s = np.maximum(np.sum(t0_all <= when, axis=0) - 1, 0) # the latest segment begun elapsed = np.maximum(when - t0_all[s, columns], 0.0) moved = speed_all[s, columns] * elapsed positions[f] = start_all[s, columns] + moved[:, None] * direction_all[s, columns] energy_out[f] = energy_all[s, columns] * np.exp(-air * pace_all[s, columns] * elapsed) order_out[f] = order_all[s, columns] return Particles(times, positions, energy_out, order_out, OCTAVE_BANDS_HZ[band], source) __all__ = ["MAX_REFLECTIONS", "Particles", "trace_particles"]