# Wave simulation

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/simulation/
Language: en
Alternate: https://docs.jmrp.io/phonometry/es/simulation/index.md
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-17
Updated: 2026-11-16T21:36:13Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Sound field computed by a deterministic 2D FDTD solver and its elastic P-SV companion, with Rayleigh and Scholte waves and fluid-solid coupling.

---

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](https://docs.jmrp.io/phonometry/simulation/where-it-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](https://docs.jmrp.io/phonometry/buildings/rooms/room-image-sources/#3-modes-of-a-rectangular-room)
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](https://docs.jmrp.io/phonometry/environment/propagation/ground-barriers/) can be
re-derived by placing an obstacle in the domain, and the ray bending of
[atmospheric refraction](https://docs.jmrp.io/phonometry/environment/propagation/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](https://docs.jmrp.io/phonometry/buildings/rooms/room-acoustics/) | room modes growing on and off resonance |
| [Reverberation prediction](https://docs.jmrp.io/phonometry/buildings/rooms/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](https://docs.jmrp.io/phonometry/environment/propagation/outdoor-propagation/) | barrier diffraction at two wavelengths, and the ground-effect lobe pattern |
| [Ground effect and barriers](https://docs.jmrp.io/phonometry/environment/propagation/ground-barriers/) | barrier diffraction at two wavelengths |
| [Sound reflection of a noise barrier in situ](https://docs.jmrp.io/phonometry/environment/propagation/barrier-reflection/) | 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](https://docs.jmrp.io/phonometry/environment/propagation/atmospheric-refraction/) | downwind and upwind refraction |
| [Airport noise](https://docs.jmrp.io/phonometry/aircraft/airport-noise/) | the ground-effect lobe pattern |
| [Impedance tube](https://docs.jmrp.io/phonometry/materials/absorbers/impedance-tube/) | the virtual impedance tube and the virtual transmission tube |
| [Measuring a silencer](https://docs.jmrp.io/phonometry/devices/noise-control/silencer-measurement/) | the open duct end radiating at two frequencies |
| [Duct-borne noise](https://docs.jmrp.io/phonometry/devices/noise-control/duct-path/) | a duct driven below and above its first cut-on |
| [Diffusers](https://docs.jmrp.io/phonometry/materials/diffusers/diffusers/) | a flat panel beside a QRD |
| [Metadiffusers](https://docs.jmrp.io/phonometry/materials/diffusers/metadiffusers/) | the metadiffuser beside the QRD it mimics |
| [Metamaterial absorbers](https://docs.jmrp.io/phonometry/materials/absorbers/metamaterial-absorbers/) | the slit absorber |
| [Silencers](https://docs.jmrp.io/phonometry/devices/noise-control/silencers/) | the expansion chamber and the quarter-wave side branch |
| [Panel sound insulation](https://docs.jmrp.io/phonometry/buildings/design/panel-sound-insulation/) | the wall aperture |
| [Underwater propagation](https://docs.jmrp.io/phonometry/underwater/underwater-propagation/) | the SOFAR duct, and the critical grazing angle over two seabeds |
| [Underwater acoustics](https://docs.jmrp.io/phonometry/underwater/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](https://docs.jmrp.io/phonometry/vibration/structural/junction-transmission/),
the coincidence plate, on panel sound insulation, a plate driven below and
above coincidence, on
[sound power from surface vibration](https://docs.jmrp.io/phonometry/devices/emission/vibration-sound-power/),
and the hit on a half-space that leaves a Rayleigh train on its surface, on
[predicting vibration](https://docs.jmrp.io/phonometry/vibration/immission/vibration-prediction/).
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.

## Pages in this section

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

- [2D FDTD wave simulation](https://docs.jmrp.io/phonometry/simulation/fdtd-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](https://docs.jmrp.io/phonometry/simulation/elastic-waves/):
  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](https://docs.jmrp.io/phonometry/simulation/compute/):
  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](https://docs.jmrp.io/phonometry/simulation/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](https://docs.jmrp.io/phonometry/io/videos/)
  (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](https://docs.jmrp.io/phonometry/simulation/where-it-runs/):
  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.

## What this section does not cover

- **Not covered.** **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.

- **Not covered.** 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](https://docs.jmrp.io/phonometry/simulation/elastic-waves/#a-solid-from-a-catalogue)),
  and the output is a field you analyse yourself.

## Before and after these pages

The fields these solvers produce are read back with the same tools as a
measurement: the filtering, weighting and level functions of [Signal
analysis](https://docs.jmrp.io/phonometry/signals/), with [Build a sound level
meter](https://docs.jmrp.io/phonometry/signals/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?](https://docs.jmrp.io/phonometry/start/tasks/) indexes it by the job
and [All guides](https://docs.jmrp.io/phonometry/start/guides/) lists every page with a line on
each.
