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.