Skip to content

Wave simulation

Most of this library predicts a number; this section computes the wave field itself. A finite-difference time-domain (FDTD) solver integrates the linear acoustic equations on a 2D grid, so reflection, diffraction, interference, modal behaviour and refraction through inhomogeneous media all emerge from first principles, and its elastic companion carries the same scheme into solids. Both solvers are deterministic (on NumPy in float64, identical inputs give bit-identical outputs on the same platform), validated against analytic oracles, and double as a cross-check engine for the closed-form models of the other sections. Both also step on an NVIDIA GPU through CuPy or on PyTorch when asked, from the same code, and every result records where it ran.

The 2D domain is a cross-section, and that has one consequence worth settling before any number leaves the solver: a point in the plane is physically an infinite line source, so amplitudes fall as the inverse square root of distance, about 3 dB per doubling instead of 6. Interference and diffraction patterns, arrival times and modal frequencies are faithful; absolute levels and decay rates belong to that geometry and not to a 3D room. A quantitative 3D claim needs a closed form or a 3D solver behind it.

The section splits along the media it simulates. The acoustic page explains the numerical method (the staggered leapfrog scheme and its Courant stability bound), the building blocks (sources, probes, obstacles and boundary conditions, including the locally reacting real-impedance edge), the near-to-far-field transformation, when a wave-based simulation is worth its cost, what a 2D domain can and cannot say about a 3D problem, and how numerical dispersion sets the cells-per-wavelength resolution rule. The elastic page extends the same staggered grid to solids: shear waves, free surfaces with Rayleigh waves, and fluid-solid coupling with mode conversion, Scholte interface waves and immersed-plate transmission. A third page, common to both, says where a run steps: NumPy, CuPy or torch, chosen per call, per block of code or per process, with what is promised about the numbers on each device. A run can go three ways beyond NumPy on this machine: onto another device, onto a node reached over SSH, and straight into a video. Where heavy work runs maps the devices, the nodes and the encoders in one place.

A good way to read it is alongside the closed-form pages it cross-checks: the in-plane modal frequencies of the mode ladder of the image-sources guide, those of zero order along the dimension the cross-section leaves out, reappear as peaks in a simulated room spectrum, the barrier insertion loss of ground effect and barriers can be re-derived by placing an obstacle in the domain, and the ray bending of atmospheric refraction emerges from a height-dependent sound-speed profile. When a geometry is too irregular for those models (odd-shaped rooms, multiple barriers, mixed impedance ground), the simulation is the fallback, and what it gives holds for its cross-section: interference and diffraction patterns, arrival times and modal frequencies, not 3D levels. When a closed form exists, prefer it, and use the solver to verify the assumptions it rests on.

Those cross-checks are not only arguments: twenty-eight of the animations in this documentation are output from these two solvers, twenty-two from the acoustic one and six from the elastic one, and twenty-four of them are filed on the guides whose physics they settle rather than here. Twenty of the acoustic solver’s twenty-two are on these guides:

Guide What its animations show
Room acoustics room modes growing on and off resonance
Reverberation prediction the same room modes, the hall of columns that turns one wavefront into a mixed field, and the same absorption placed two ways
Outdoor propagation barrier diffraction at two wavelengths, and the ground-effect lobe pattern
Ground effect and barriers barrier diffraction at two wavelengths
Sound reflection of a noise barrier in situ the EN 1793-5 pulse in front of a 4 m and a 2.5 m sample, and the Adrienne window of each closing before the ground reflection and the top edge arrive
Atmospheric refraction downwind and upwind refraction
Airport noise the ground-effect lobe pattern
Impedance tube the virtual impedance tube and the virtual transmission tube
Measuring a silencer the open duct end radiating at two frequencies
Duct-borne noise a duct driven below and above its first cut-on
Diffusers a flat panel beside a QRD
Metadiffusers the metadiffuser beside the QRD it mimics
Metamaterial absorbers the slit absorber
Silencers the expansion chamber and the quarter-wave side branch
Panel sound insulation the wall aperture
Underwater propagation the SOFAR duct, and the critical grazing angle over two seabeds
Underwater acoustics Lloyd’s mirror: a source under a pressure-release surface at 31.5 Hz and at 315 Hz, with its inverted image

Four of the elastic solver’s six are on guides too: the bending packet entering an L-junction, on junction transmission, the coincidence plate, on panel sound insulation, a plate driven below and above coincidence, on sound power from surface vibration, and the hit on a half-space that leaves a Rayleigh train on its surface, on predicting vibration. The first two and the last also appear on the elastic page below, where the solver that produced them is explained.

Several of those guides do more than illustrate. The impedance-tube guide runs a whole standardised measurement inside the domain: the ISO 10534-2 and ASTM E2611 reductions on a simulated tube recover the sample’s analytic absorption and transmission loss, so there the solver stands in for the laboratory and the closed-form comparison is a real test rather than a demonstration. The diffuser guide sends one plane wave onto a flat panel and a meshed Schroeder diffuser and reads the scattered energy on a near-field receiver arc; the metadiffuser guide lets a 2 kHz wavefront hit the meshed metadiffuser and the QRD it mimics; and the acoustic page below transforms the near field of the meshed metadiffuser into a far-field polar response and lays it on the library’s own prediction. The panel-insulation and plate-junction guides launch bending waves into a plate and watch coincidence and junction splitting happen.

Setting up a run is a chain, and each link fixes the next. The highest frequency you need and the slowest sound speed anywhere in the domain fix the cell size, through the cells-per-wavelength rule that numerical dispersion sets. The cell size and the fastest speed then fix the time step, through the Courant stability bound. The domain has to hold the geometry plus clearance for the absorbing layers, which are sized in cells, not in wavelengths: twenty cells is a good floor. The run must last long enough for the field to cross the domain, and for a steady-state answer long enough for the transient to leave before the analysis window opens. The cost is cells times steps, so halving the cell size costs eight times more in 2D: a factor of four in cells and a factor of two in steps. The acoustic page gives the numbers for each link, and the elastic page adds the extra sampling that free surfaces and interface waves demand.

Read the acoustic page first: the elastic page assumes its vocabulary and says so in its own opening.

  • 2D FDTD wave simulation: the staggered-grid pressure-velocity FDTD method following Attenborough & Van Renterghem (2021) chapter 4, its sources, probes, obstacles and boundary conditions, the near-to-far-field chain, the 2D limits and the numerical dispersion rule.
  • Elastic waves and fluid-solid coupling: the P-SV velocity-stress companion solver (Virieux 1986) on the same grid, with stress-imaging free surfaces, Rayleigh waves, mode conversion, Scholte interface waves and immersed-plate transmission, each validated against its exact closed form.
  • Where a simulation runs: NumPy, CuPy and torch: both solvers on NumPy, on an NVIDIA GPU through CuPy or on PyTorch, the Compute request, use() and PHONOMETRY_COMPUTE, the fallback to NumPy, the provenance a result records, the bit-identical CuPy fields and the published torch bounds, and decimated snapshots.
  • Sending a simulation to a remote node: either solver’s run on another machine over SSH, on a Docker node running the image built from the repository’s Dockerfile or in a Python environment, with or without a GPU: the hosts file that names a node, what each side checks, the errors and the fallback to NumPy, progress and timeouts, security in both directions, and when a run there gives the numbers of a run here.
  • Writing animations and FDTD runs to video (in the Files section): either solver’s run written straight to a WebM, an MP4 or a GIF as it is computed, here or on a node, without storing its snapshots.
  • Where heavy work runs: CPU or GPU, here or on a node: the map of where a run steps and where its video is encoded, on this machine or on a node, on a CPU or a GPU, with the page that explains each.
  • Two dimensions, and no way around it. Everything a 2D cross-section cannot say about a 3D room, neither solver says, and the cylindrical spreading above is only the most visible consequence. The open boundary is a quadratic-ramp absorbing layer (the simple precursor of a perfectly matched layer, not a PML), so grazing incidence is absorbed less cleanly than normal incidence, and the elastic solver has no elastic PML at all, which shows most on grazing Rayleigh waves. The medium is non-moving: wind and flow advection are not modelled, so a refraction study here comes from a height-dependent sound-speed profile and not from a flow field. The only impedance boundary is a frequency-independent real one, so a porous absorber has to be meshed rather than declared. On the elastic side the solid is isotropic and purely elastic: no anisotropy, and no viscoelastic damping beyond the bulk decay rate, so a material loss factor cannot be entered.

  • And nothing here is a room-acoustics package. There is no geometry importer, no ray tracer, no auralisation and no 3D solver: obstacles are rasterised onto the grid from shapes you define, a medium is the numbers or maps you give it (the elastic solver also takes one of the materials it ships or a solid’s catalogue row), and the output is a field you analyse yourself.

The fields these solvers produce are read back with the same tools as a measurement: the filtering, weighting and level functions of Signal analysis, with Build a sound level meter running that chain end to end on one runnable page. There is no theory-reference page for the solvers; the derivations, the stability conditions and the analytic oracles stay inside the acoustic and elastic guides above.

If you arrived here from a search and want the shape of the whole library, What do you need to measure? indexes it by the job and All guides lists every page with a line on each.