Development¶
Repository layout¶
src/acoustic_spaces/ Python package
scene/ scene model and YAML schema
geometry/ CAD and BIM import, triangulation, mesh cleanup and checks, the
rooms a model encloses (cells)
materials/ material database, coefficient files, CATT-Acoustic and ODEON
material libraries
directivity.py source directivity: patterns per band, SOFA and CSV balloons
room.py a scene with its geometry loaded: materials per face, checks
engine/ early reflections, edge diffraction, late reverberation (on the
CPU, or on a GPU through WebGPU), early paths in pressure,
grazing attenuation over the audience, the wave solver (CPU and
GPU) and its wall admittances, re-weighting for new absorption,
sound particles, the leak finder, responses, simulate(),
coverage maps
air.py ISO 9613-1 air absorption and speed of sound
synthesis.py octave filter bank and impulse response synthesis
spatial/ Ambisonics, VBAP loudspeaker layouts, HRTFs, spatial rendering,
sound field rotation, binaural decoding of Ambisonics
parameters.py ISO 3382-1 parameters, octave filters, noise floor detection
products.py matrix and dot products whose sums are added in a fixed order
render.py convolution, resampling, auralisation, real-time playback
headtracking.py head-tracked binaural playback, OSC head trackers
measurement.py sine sweeps, playback and recording, deconvolution
compare.py simulated against measured parameters, in JNDs (ISO 3382-1)
calibration.py absorption fitted to measured parameters (`calibrate`)
walkthrough.py listeners and sources heard as they walk through the room
doppler.py walks with Doppler: each early path through a changing delay
audio.py WAV files
viz.py 3D view, reflection paths, particle animations, response plots
gltf.py export to glTF (.glb) for Blender: room, paths, particle animation
results.py writing a simulation's responses and parameters to a folder
examples.py the example scenes that ship with the package
demos/ what the demos share: steps and options, recordings, mixes, the
tour, stills and video (a new demo describes its steps and options)
gui/ the graphical editor (Qt)
cli.py command-line interface
i18n.py the language of the text shown, and its translation
locale/ the translation catalogs (es.po: Spanish, ca.po: Catalan,
it.po: Italian, de.po: German, nl.po: Dutch)
cpp/include/ header-only C++ core: BVH, ray tracer (specular paths, stochastic
and map tracing), wave solver (FDTD), FFT, partitioned
convolver, sums in a fixed order (no Python, so a plugin or
player can reuse it)
cpp/bindings/ nanobind module exposing the core as acoustic_spaces._native
tools/catalog.py keeps the translation catalogs in step with the code (see Translating)
tests/ pytest suite, run on Linux, macOS and Windows in CI
examples/ example scenes and their scripts, installed with the package
validation/ the longer checks behind the validation report; bras/ has the
measured rooms of the BRAS benchmark
docs/ the Sphinx documentation, the validation report and the pictures
Sums in a fixed order¶
numpy’s @ hands a product’s sums to the linear-algebra library, which splits a large
one among its threads and adds the parts in an order that depends on how many it has
(as many as the computer’s cores, unless OPENBLAS_NUM_THREADS says otherwise). The
last digits of such a sum can change with that number, and with them a run’s results
from one computer to the next. So a product whose operands can grow with the scene (its
paths, frequencies, samples, receivers or faces) is written with
acoustic_spaces.products, whose compiled loops add each sum in the order its
definition fixes:
from acoustic_spaces import products
spectra = products.product(weights.T, phased) # weights.T @ phased
products.add_product(total, weights.T, phased) # total += weights.T @ phased
norm = math.sqrt(products.dot(left, left)) # left @ left
A product of a few fixed values (3-vectors, 3 x 3 frames, a handful of bands) stays an
@: the library works it on one thread. The library’s solvers (eigh, pinv, svd,
inv, least_squares) stay too, and so does live head-tracked playback.
tests/test_code.py counts the products each file leaves to the library and fails
when one is added, with a message that says what to do.