# Simulation Each source and listener pair is simulated in two parts that add up without a crossfade. **Early reflections** (`simulation.early`) are exact specular paths up to `max_order` reflections, with delay, arrival direction and energy per band. Candidate image sources come from deterministic specular rays (`method: ray_tracing`, the default; cost grows with `rays`, not with the number of surfaces) or from every sequence of planes (`method: image_sources`; complete, but grows as planes to the power of the order). With edge diffraction the rays' first reflections come with the faces of every diffracting edge that the source stands in front of, in its sight or not: a ray misses a face the source sees nearly edge-on, and a reflection that an obstacle cuts off still fades at the obstacle's edges. Every candidate is then traced back from the listener, so the paths found are exact either way, including paths that reflect exactly on an edge or in a corner: a face reflects as far as its edges, to within a billionth of the model's diagonal. Sound that bends round edges is added to them (see [Edge diffraction](#edge-diffraction)). **Late reverberation** (`simulation.late`) is either: - `stochastic_ray_tracing` (default): `rays` rays per band (50,000 by default) leave the source and reflect off the surfaces as [Scattering](#scattering) says, losing energy to absorption and air. Specular paths the early part already computed are left out (with partitions, those through two at most; the early part keeps no reflected path through more). How energy reaches the listener is set by `reception`: - `diffuse_rain` (default): the scattered part of every reflection radiates to each listener it can see; the rest counts when a ray crosses a detector sphere (`receiver_radius`, 0.5 to 1 m by default and kept clear of walls). Kept clear, the sphere of a listener closer than 5.6 cm to a surface (an opening or an outdoor scene's sky too) is under a tenth of that size and catches a hundredth of the rays or fewer, which the scene's warnings say. With rays that go straight (no wind or temperature gradient), the scattered sound of each reflection straight from the source is also found from the listener's side: 16384 directions from each listener, turned at random by the seed, find the surfaces it sees, and the rays and those directions share that sound by how densely each finds it (the balance heuristic of multiple importance sampling): the rays near the source, the listener's directions near the listener. The expected energy is the same, but a ray that lands next to a listener (above a ground that scatters, an aircraft overhead) brings it no burst of scattered sound. - `secondary_sources`: all reflected energy radiates that way, as in ODEON's late method. Much smoother tails, but it treats specular energy as diffuse: in the example box (smooth walls, absorbing ceiling) EDT comes out about 20 % shorter. - `detector`: classic ray tracing, everything counted by the sphere. In rooms with absorption in one place and smooth walls, most late energy rides on the few rays that keep clear of the absorber, and the tail breaks up where those run out. With `splitting` (on by default), a first tenth of the rays (at least 1,000, or half of them when there are fewer than 2,000) measures how much energy a ray usually carries over time; the rest are split into copies when they carry more than 4 times that and thinned out by Russian roulette when they carry less than a quarter (a weight window). The expected result is unchanged; with random scattering, the example box's late tail (0.5 to 2.5 s) misses a 1-million-ray reference by 0.5 to 2 dB per band instead of 1 to 8 dB at 100k rays (1 to 4 dB instead of 4 to 17 dB at 10k), for about 1.5 times the run time. The rays are traced in `batches` (10 by default), each with the random streams of its share of the rays: the same rays as at once, so the same result but for rounding (which can tip a split or a roulette the other way). From 2 batches on, the parameters get standard errors, one standard deviation of how much each would change between runs with other seeds: a jackknife leaves out each batch in turn and takes the spread of the parameters. `acoustic-spaces simulate` prints the largest in JNDs from 125 Hz to 4 kHz and suggests more rays when it is over half a JND; `parameters.json` holds them all (`standard_errors`), and the editor shows each in the results table's tips, amber over half a JND. The early paths and the wave solver's bands do not depend on the seed and add none. Each batch takes its share of the listeners' gather of the first reflections' scattered sound (every tenth of its directions with 10 batches), so the standard errors hold its error too (over a ground plane, in 10 ms slots, 1.1 to 1.4 times its spread between seeds at the median). The parameters from the directions the late energy arrives from (LF, LFC, LJ, the decay times along the listener's axes) get none. Over 60 seeds in a diffuse box (2,000 rays), the root mean square of the standard errors of EDT, T30, C80 and G came within 0.90 to 1.17 of the spread between the runs from 125 Hz to 4 kHz, and within 0.8 to 1.7 over 20 seeds in the shoebox example at its 50,000 rays. With few rays in a room whose late tail rides on a few rays, one strong arrival (a ray through the listener's sphere long after the rest) comes in some runs and not in others: the standard errors are then right on average over runs but low in most of them (those of T20 and T30 about 0.5 to 0.9 of the spread in the shoebox at 2,000 rays). Batches cost time, as each batch's run sums its threads' copies of the results: 10 made the late part 10 to 16 % slower in the shoebox and concert hall examples on 4 cores, and no slower on one thread; `batches: 1` traces the rays at once, without standard errors. Nearly all of the run time goes into ray queries: which surface a ray meets next, and whether each listener can see a reflection (see [Performance](#performance)). - `statistical`: the reflected energy of Barron's revised theory, an exponential decay at the Eyring reverberation time T from the direct sound on, less what the early paths carry. Early paths end `transition_ms` after the direct sound (by default the mixing time, the square root of the volume of the listener's room in milliseconds), so the late part holds the scattered share of every early reflection, the orders above `max_order` before the transition and everything after it. The total is Barron's, c T / (13.8 V) e^(-13.8 t_d / T) for a unit source whose direct sound arrives at t_d (Barron and Lee's 31200 T / V e^(-0.04 r / T) where the direct sound is 100 / r²): the Sabine form 4 / A with Eyring's absorption area and the same exponential, which reads 0.2 dB above the classical 4 (1 - α) / (α S) at a mean absorption of 0.1 and 0.8 dB above at 0.3. The two parts hand over by reflection order by default. Set `transition_ms` to keep early paths only that long after the direct sound. **Impulse responses** are built per band: early paths become fractional-delay impulses (in the lowest bands with the phase of their reflections, see [Low frequencies: early reflections in pressure](#low-frequencies-early-reflections-in-pressure)), the late energy shapes a Dirac sequence with the density of reflections in the room, and a zero-phase crossover bank sums the bands. From 50 ms after the direct sound the late energy is spread over 10 ms first, so a single strong ray late in the tail does not become a click; none of it moves ahead of those 50 ms (into C50's early part) or past the end. The direct sound at r metres is an impulse of height 1/r, so levels compare between files and the energy of the direct sound at 10 m (0.01) is the reference for strength G. **Parameters** follow ISO 3382-1 per octave band: EDT, T20, T30, C50, C80, D50, Ts and G. `Response.parameters()` computes them from the simulated energies; `acoustic_spaces.parameters.from_impulse_response` does the same for any mono IR (see [Measuring impulse responses](measurements.md#measuring-impulse-responses)). A response that ends before it has decayed is extended by its fitted decay rate; one that ends before it has decayed by 20 dB leaves too much to that estimate, and all its parameters are NaN. Outdoors, where a response may hold no decay at all, G is then that of the energy it holds, and so are the levels and the STI that take it; the other parameters stay NaN (see [Results outdoors](outdoor.md#results-outdoors)). A response that ends in silence holds all its sound: its energies are those it holds, and its decay curve drops to nothing after the last sound. That drop is the end of the data, not a decay, so no decay time is fitted through it: EDT, T20 or T30 is NaN when the curve does not fall through its range before the last sound. Each T20 and T30 comes with the checks of ISO 3382-2 (annex B) on the line it is read from: its non-linearity ξ = 1000 (1 - r²) ‰, r being the correlation of the decay curve with time over the fit range, and the curvature of the decay, C = 100 (T30 / T20 - 1) % (`xi_t20`, `xi_t30` and `curvature`). Past 10 ‰ (`NON_LINEARITY_LIMIT`) the decay is not straight and its decay time is not to be relied on; a curvature of 0 to 5 % is usual, and past 10 % (`CURVATURE_LIMIT`) the decay is curved, likely with two slopes as in coupled rooms, which T20 and T30 each average differently. The editor's results table shows them in amber past those limits, a ξ with the T20 or T30 it puts in doubt. Air absorption follows ISO 9613-1 for the scene's temperature, humidity and pressure. The directions the sound arrives from give more of them: - LF, LFC and LJ (ISO 3382-1, annex A), from a figure of eight with its null on the source: the share of the early energy that arrives from the sides, which widens the source, and the level of the late lateral sound, which envelops the listener. - IACC early and late (annex B), from the binaural response when the scene writes one (through the spherical head or a SOFA file; the first, if it writes several). - Stage support ST early (Gade's ST1) and ST late (annex C), how well musicians hear themselves and each other, for listeners 0.9 to 1.1 m from a source; elsewhere they are empty. The standard measures them 1 m from the source, and the direct sound in their first 10 ms changes them by up to 20 lg r dB at r metres: 0.9 dB at most within that span, 6 dB at 0.5 m. - T30 of figures of eight facing forward, left and up from the listener: where sound keeps running between two hard walls, the decay along that axis is longer. - STI and STIPA (IEC 60268-16) and U50, at the level the source's `level_db` gives and the background noise of `coverage.noise_db`, as the coverage maps take them (NaN, like G, when a band from 125 Hz up is undefined); and the echo criteria of Dietsch and Kraak for speech and music, from the response filtered to the 1 kHz octave for speech and to the two octaves about 1.4 kHz (0.7 to 2.8 kHz) for music. ISO 3382-3's quantities for open-plan offices are not computed (the spatial decay rate D2,S, the speech level at 4 m Lp,A,S,4m, the distraction distance rD and the privacy and comfort distances): listeners on a line from an omnidirectional source given the standard's normal speech spectrum as its `level_db` per band (57.4 dB(A) at 1 m in free field) give the A-weighted level and the STI, with `coverage.noise_db` as the background noise, to read them from. The echogram adds the arrivals in energy, as ODEON and CATT do, except the early reflections in the lowest bands, which add in pressure (see [below](#low-frequencies-early-reflections-in-pressure)). A figure of eight on the centre line of a symmetric room hears the two side walls' reflections arrive together with opposite signs, and they cancel in the rendered Ambisonics response. LF read from that response with `analyze --ambisonic` is then lower than the echogram's; off the centre line the two agree on average, band by band within the interference of reflections close in time. ## Scattering A surface's scattering coefficient (ISO 17497-1) is the share of the reflected energy that leaves it diffusely rather than specularly (that of a ground with an impedance is 0 unless its material gives one, see [Ground impedance](outdoor.md#ground-impedance)). `simulation.scattering` says how rays carry it out: ```yaml simulation: scattering: method: vector # or random from_size: true # small, distant and grazed surfaces scatter more by_band: true # each band follows its own scattering ``` - `vector` (default): every reflection sends the ray in the direction of the sum of its specular direction and a random Lambert direction, weighted by the scattering coefficient, as ODEON and pyroomacoustics do. The ray keeps all the reflected energy: the diffuse rain sends the scattered share to the listeners, and the detector spheres and coverage maps count the rest along the exact specular direction, on a leg of its own up to the next face, as random scattering's specular rays do, so it reaches only where specular paths go. Where the bands' coefficients differ, each band is traced with rays of its own, so a wall that scatters the bass and reflects the treble does both; one direction for all bands (pyroomacoustics takes their mean) made the example box's treble decay twice as fast as it should. For the same rays per band, tracing band by band takes 3 to 5 times as long as one ray for all bands; at the default 50,000 per band a simulation takes 1.5 to 4 times as long as version 2's 100,000 shared rays. `by_band: false` goes back to one ray for all bands, turned by their mean scattering. - `random`: the ray reflects specularly or, with the coefficient as probability, in a Lambert direction. This was the only model up to version 2. With smooth walls a few rays then keep running between them, and the decay comes out longer. Those few rays also make the results noisy. In BRAS's chamber music hall (see [Validation](validation.md#measured-rooms-bras)), at 50,000 rays per band, a few single rays keep long legs across the hall for up to 1.5 s, one of them between its end walls, and hold up to 22,800 times a typical ray's energy. The weight window cannot spread them, as its copies stay on the same path until they scatter. The decay times' standard errors then reach 1 to 2.8 JNDs at two of its ten source and listener pairs; with 1 million rays per band the largest is 0.33 JND. Where the bands' coefficients differ, each band is traced with rays of its own here too; in the example box and the lecture hall a simulation then takes about two thirds of vector's time. `by_band: false` traces one ray for all bands, as random did up to 4.0.1: it goes in a Lambert direction with the bands' mean coefficient as probability, and each band's energy is re-weighted by its own coefficient over that mean. That is right on average, but over many reflections a band's weight drifts towards zero and its energy rides on a few rays. In the BRAS rooms, with the scattering of the surfaces' size, T30's standard errors came out 15 to 180 times vector's, and the coupled rooms' reverberation chamber decayed far too fast (from its first loudspeaker, T20 at 63 Hz 3.1 s against 8.9 s measured). - `from_size` (default on): a surface also scatters for its size, after Christensen and Rindel (2005), as in ODEON. The specular share falls below f_w = c d / (2 (w cos θ)²) and again below f_l = c d / (2 l²), where w and l are the surface's width and length, d the distance the sound came from (from the source or the last reflection, through openings and partitions it passed) and θ its angle of incidence. A large wall reflects specularly down to low frequencies, while a small panel, a distant one or one met at a grazing angle scatters. Each flat surface (the faces of one plane joined at their edges, of any material) counts as the rectangle with its area and perimeter. Early reflections lose that share too and the late part picks it up. Reflections that [edge diffraction](#edge-diffraction) already completes keep their own coefficient: the first two orders with `first_order` diffraction (the default) or `second_order`, the first with `direct`. In the two measured rooms of the [validation report](validation.md), the default model brings the reverberation time of a chamber music hall from 20 to 32 % long down to 7 to 20 %, and keeps a seminar room within 2 % from 500 Hz to 4 kHz. Without the surfaces' sizes, neither model fits both rooms. ## Frequency bands Simulations run in the eight octave bands from 63 Hz to 8 kHz by default, or in the 24 third-octave bands from 50 Hz to 10 kHz: ```yaml simulation: bands: third_octave # or octave (default) ``` - Everything that depends on frequency follows the bands: materials, air absorption, source directivity, the scattering of a surface's size, the rays (`rays` per band) and the filter bank the impulse response is built with. With the wave solver on, it computes the third octaves of the octaves up to `max_band_hz`. - Materials hold 8 or 24 values. An octave value holds for each of its three third octaves, and an octave simulation takes the mean of a third-octave material's three. - Room parameters, the STI, coverage maps, plots and the editor's results stay in octave bands: each octave's energy is the mean of its three thirds'. A response's `energy()` has all 24 bands and `octave_energy()` the octaves. - Third octaves pay where coefficients change within an octave: absorbers narrower than an octave (a Helmholtz resonator, a slot absorber), and the 8 kHz octave, across which the air absorbs about twice as much at 10 kHz as at 6.3 kHz. Its decay is then no single slope, and in the shoebox example its T30 comes out 8 % longer in third octaves. In the measured seminar room of the [validation report](validation.md) they bring the reverberation time at 250 Hz and 8 kHz from 13 and 18 % short to within 4 %. They trace three times the rays and take about three times as long. - `acoustic-spaces simulate --bands third_octave` sets them for one run, and the editor's simulation page has them. A material with third-octave data shows its 24 values in the editor, and `inspect` lists its octave averages. ## Edge diffraction Sound bends round the edges of walls, screens and balconies: a listener round a corner still hears the source, quieter and duller, and the level does not drop off a cliff where a wall cuts a path off. `simulation.early.diffraction` adds this to the early part with the uniform theory of diffraction (UTD, Kouyoumjian and Pathak), averaged over each octave band: - `first_order` (default): the direct sound and the first-order reflections bend round edges, with the reflection before or after the edge. Sound that passes two edges in a row is left out: there is none behind a thick wall; where the source and the listener see each other just over both edges of a flat roof, or along a wall in line with both, the level is too low; and behind the roof with the source above its plane it is up to 6 dB too high (see the [validation report](validation.md#known-issues)). - `second_order`: as `first_order`, and the direct sound bends round two edges in turn: over a thick wall or barrier, round both corners of a doorway's jamb, over two screens in a row. A path over two edges reflects nowhere, so over a thick barrier on a hard ground the reflections off the ground before and after it are missing, and the level comes out 1.7 to 5.7 dB low from 500 Hz up (see the [validation report](validation.md#known-issues)). - `direct`: only the direct sound. - `none`: specular paths only. With `first_order` and `second_order`, `simulation.early.diffraction_reflections` says where a path over one edge may reflect: `one_side` (the default), before or after the edge, off the ground on the way to a barrier or off a façade behind it; or `both_sides`, before and after, which adds the path reflected off the ground on the way to a barrier and again behind it, the fourth of the four paths over a barrier on the ground. Over a hard ground that path carries a quarter of the sound over the barrier, and without it the insertion loss comes out up to 0.8 dB off from 1 kHz up (mostly too high) and a few decibels off in the bands below, where the four paths interfere; with it the engine is within 0.15 dB of the exact solution (see the [validation report](validation.md#outdoor-results-against-exact-solutions)). Over grass and other soft grounds, whose reflections near grazing are weaker, the path should matter less, but that is not checked. `both_sides` pairs every reflection before an edge with every one after it, so it costs more where many faces reflect (in the `street` example about a sixth more diffracted paths and a few tens of milliseconds per listener); `--diffraction-reflections` sets it for one run of `simulate` or `map`, and the editor has it as **Reflections over an edge** under **Early reflections**. Outdoors, where sound passes over barriers and buildings on its way to a listener, paths over one edge and two do not add up to the field. There `simulation.early.rows: solver` (the default) takes the sound in the vertical plane through the source and the listener from a solver for the whole row, in the octave bands up to 500 Hz that add their paths in pressure; `rows: edges` leaves the paths over the edges alone (see [Sound over rows of barriers and buildings](outdoor.md#sound-over-rows-of-barriers-and-buildings)). The edges are found in the model: corners where two faces meet with more than 195° of open air round them (the inside corner of an L-shaped room, the front of a stage or a balcony) and the free edges of thin screens. Each source and listener get the shortest path over each edge they can both see. In the shadow of the edge that path carries the diffracted sound; on the lit side, near the boundary, it changes the energy of the specular path it borders. Across a boundary the level is continuous: the tests cross one in an L-shaped room in millimetre steps, with first-order reflections, and the level changes by less than 0.25 dB where specular paths alone drop by more than 5 dB; where a reflection off one of the corner's walls ends and the direct sound carries on, by less than 0.05 dB. Over a ground with an impedance a term reflects off it as its geometric wave does near its boundary (the whole path's spherical wave, over the grounds round that path's reflection) and as the edge's wave does farther off, so where a barrier's top or end cuts off a reflection off grass the level changes by less than 0.02 dB across it. The diffraction coefficient, its terms added in pressure, matches the exact solutions for a half-plane and for wedges (within 0.25 dB); where the paths add in energy (indoors from 250 Hz up), the level near a shadow boundary is below the exact solution: on the boundary of a right-angled corner by 1.7 dB at 250 Hz and 1 dB at 1 kHz, and more behind blunter edges (2.2 dB at 250 Hz for one open over 225°; see the [validation report](validation.md#edge-diffraction-against-the-exact-solution)). A thin screen comes within 1.5 dB of Maekawa's chart in the tests' geometry (the chart, an empirical one, is itself up to 2.1 dB from the exact solution behind a barrier 40 to 90 m away). A path over the edge of a thin screen takes the part of its Fresnel zone that the edge covers, the Fresnel integral from each end as in BTM's integral over a finite edge, so near a free end its sound fades to half at the end and out past it, over a few widths of the zone, instead of stopping there. Where two such edges meet at a right angle (a screen's top and its side) they share the fade; at a free end, where they meet at another angle, or where a screen's top bends, each of an edge's terms takes its own part of the edge, as BTM's integrand weights it near that term's boundary. An end that stands on the ground, or on a face across the edge, goes on as its image there. Past the corner of a thin screen, square or not, and beside the bend of a screen's top, the level is within 0.2 dB of the exact solution and steps as it does, where it stepped by up to 2.8 dB past a square corner, 3.0 dB past one of 45° and 16 dB beside a bend (see the [validation report](validation.md#edge-diffraction-against-the-exact-solution)). The edges of solid wedges still stop at their ends: near a block's corners, where three meet, the level steps by up to 2.4 dB at 63 Hz and is up to 2.3 dB from the exact solution, and fading them as at a screen's corner put it up to 1.25 dB above it before the corner, where stopping is within 0.36 dB. Paths over two edges (`second_order`) still stop at the ends. Behind a thick wall or barrier, whose two corners share its top, no edge sees both the source and the listener: `first_order` finds nothing there, or only a way round one corner of a doorway. `second_order` follows the shortest path over each pair of edges that see each other. The first edge's wave reaches the second as the UTD has it, with the second edge's distance parameter from the curvature of that wave where it gets there, since near the first edge's boundaries it is still curved like the source's. Where one of the two edges' waves is lit, the path continues a path over the other edge alone and shares its energy with it, so the level is continuous where a path over one edge appears: as the listener rises past the top of a barrier, it changes by at most 0.1 dB from 1 kHz up, and 0.01 dB at 63 Hz, where the waves add in pressure (0.7 dB in energy). Where both are lit, the source and the listener in sight of each other just over both edges, each edge's terms take their part off the direct sound, and the path over both gives back what they take twice: up to 500 Hz the level over a roof 10 m wide is then within 0.06 dB of the exact solution, where `first_order` is 6.4 dB low at 63 Hz half a metre above the roof's plane and 12.6 dB a centimetre above it. Against the exact solution (BTM, in the [validation report](validation.md#edge-diffraction-against-the-exact-solution)), the level over barriers 0.3 to 3 m thick is within 0.3 dB from 500 Hz up, and over two screens in a row within 0.45 dB; at 63 and 125 Hz, in pressure, within 0.6 dB over the barriers and 0.13 dB over the screens (1.7 and 1.9 dB with the waves in energy). ```sh acoustic-spaces simulate examples/gallery/scene.yaml --out gallery acoustic-spaces view examples/gallery/scene.yaml --paths --listener "round the corner" acoustic-spaces simulate examples/gallery/scene.yaml --out plain --diffraction none acoustic-spaces view examples/archway/scene.yaml --paths --listener "behind the wall" acoustic-spaces simulate examples/archway/scene.yaml --out archway --diffraction first_order ``` ![Early level along a walk round the corner of the gallery example, with and without diffraction](images/diffraction.png) The figure walks round the corner of the `gallery` example, away from the guide. Without diffraction (dotted) the direct sound and each reflection stop at the line where the corner hides them; with it, the level falls smoothly, by more at high frequencies. Paths with more reflections than that fade at edges too. Every specular path, found or stopped by one event, takes the UTD's term of its own boundary at each edge near each of its events: where a leg of it passes an edge, and where the point it reflects at nears the edge of its face, which a narrow face reflects only in part at low frequencies. The terms of one event add, each edge on its own side of its boundary (so both edges of a gap count where a path goes through it), and the events of a path multiply, as the path must get past each in turn. A path that is not found is followed where one edge explains each run of the events that stop it, or two edges explain them between them, in at most two runs: a reflection past the end of its face with a corner in the way of a leg next to it, say. An edge explains a reflection only in front of its face, and stands on a plane only where the plane goes on round its end on its open side, so no path reflects off a roof's plane from below beside the building. Reflections off perpendicular planes, such as the floor and a wall, give the same image in either order, and the path over an edge may take another order than the path itself: each path takes the terms of every such order, and each order is tried where the early stage found only one. Each term is a path over its edge, and each product of terms is a path of its own, which arrives later by the detours of all its terms; the terms the edge diffraction adds already are left out (`engine.edge_fade` in the [API reference](api.md#edge-diffraction)). Against the exact solution, past the end of a screen, the corner of a building, a strip 2 m wide and a gap 4 m wide on a hard ground, each path with its copy off the ground, the level is within 0.08 dB in every band (0.19 dB at 8 kHz on the strip, an error of the exact level's average over too few frequencies), where it was up to 7 dB off without it, and steps between listeners 1 cm apart by no more than the exact level does (see the [validation report](validation.md#reflections-that-fade-at-edges-against-the-exact-solution)). Walking round the gallery's corner 1 cm at a time, with reflections up to third order, the level now steps by at most 0.13 dB in any band, where it stepped by up to 3.8 dB without the fade (see the [validation report](validation.md#round-a-corner-indoors), which says what is left). Where the edge diffraction bends every path the early stage follows, as with `max_order: 0` and `direct` or `max_order: 1` and `first_order`, the fade changes the level by less than 0.05 dB. Steps are left where a term still stops at the end of its edge, as the fade's terms of reflections that the edge diffraction has no path for do: driving the `street` example's car past the barrier 1 cm at a time, up to 1.11 dB in one band and 0.55 dB(A). And indoors, where paths add in energy from 250 Hz up, the sound bent round edges is kept as waves (`engine.clusters` in the [API reference](api.md#edge-diffraction)): a term continues its geometric wave as far as it is coherent with it over the band (on the dark side of its boundary, where that wave is gone, near the boundary only), and the rest of it is part of its event's diffracted wave, whose terms add up as one wave, so the two edges of a narrow face nearly cancel as they do in pressure. A wave's energy is that of its pieces added up in pressure and averaged over the band, never below nothing. Behind the `archway`'s wall, where the reflection off the arch's jamb, 40 cm deep, appears, the level steps by at most 0.08 dB from 250 Hz to 1 kHz. The [known issues](validation.md#known-issues-of-the-edge-fade) list these, with what is checked and what is not. The fade comes with any `diffraction` but `none`. The late part is unchanged, since its scattered rays already find their way round corners. `view --paths` and the Blender export draw diffracted paths in their own colour, the response's `early.diffracted` marks them, and `simulate` reports how many there are. The cost grows with the number of edges and of the paths near them, as each term of the fade is a path over its edge: in a hall with 16 edges, the early stage takes 540 ms per source and listener on four cores with `first_order`, 630 ms with `second_order`, which looks at pairs of edges, and 38 ms without diffraction (see the [validation report](validation.md#edge-diffraction-against-the-exact-solution)). Paths that reflect before or after an edge pair every edge with every plane the source or the listener faces, which in a whole city grows with the square of the buildings. Most of those pairs cannot carry a path, because the plane's faces lie nowhere near where a ray from the edge would meet the plane: the engine leaves them out before it traces a ray, on `simulation.performance.threads` threads, and the results are the same bit for bit. A city of 900 buildings simulates in about 13 s on four cores, and 3,600 in about 48 s, of which the fade's terms take about 10 and 24 s (see [Outdoor scenes](outdoor.md#buildings-from-a-map) and the [validation report](validation.md#edge-diffraction-in-whole-cities)). ## Low frequencies: early reflections in pressure At low frequencies reflections that arrive a few milliseconds apart do not add in energy, as an echogram adds them, but in pressure. Next to a hard floor the reflection arrives in phase and doubles the pressure of the direct sound (+6 dB, where energy gives +3 dB); a loudspeaker a metre in front of a wall loses bass where the wall's reflection arrives half a period late. A band's filter rings for longer than such reflections lie apart, so the impulse response shows that interference, and an echogram that adds the paths in energy misses it. Up to `simulation.early.coherent_max_band_hz` the early paths add in pressure: ```yaml simulation: early: coherent_max_band_hz: 125 # 63, 125 (default), 250, 500, or null for energy throughout; # outdoors up to 8000, the default there ``` - Each reflection turns the phase as a locally reacting surface with the material's absorption does: R = (cos θ - Y) / (cos θ + Y) at the angle of incidence θ, with the admittance Y fitted to the material's absorption in every band, as the wave solver fits it but without its grid, so the phase in a band does not depend on how many bands add in pressure. A hard surface reflects in phase at every angle; an absorbing one turns the phase of sound that grazes it, by half a turn at grazing incidence. Not so the sound that runs along a face from one edge to the next (`second_order`, over a roof or a thick wall): that is a point source's wave along the surface, which the plane wave's half turn would cancel; it takes the face as rigid and the ground wave's loss over the way along it, 2 F(w) against a rigid face's 2 (Weyl-van der Pol, see [Ground impedance](outdoor.md#ground-impedance)), in every band: 0.07 dB at 63 Hz to 0.76 dB at 8 kHz over a 10 m roof absorbing 0.02. Above those bands each reflection keeps the phase it has at their top, so the bands join without a step. A path over an edge does too where it arrives alone; where other paths' sound reaches it, a rendered response turns it by a phase of its own, drawn from the path and the response's seed, as far as that sound reaches it. The pieces a diffracted wave is cut into carry energies that already hold their interference, so they render their energy on average over seeds rather than adding in pressure a second time. A surface whose material has an impedance (a ground's) reflects with its spherical wave's factor instead, in every band (see [Ground impedance](outdoor.md#ground-impedance)). - Outdoors the paths are few, and the ground dip spans several bands: the early paths add in pressure up to 8000 Hz by default there. Wind and temperature gradients bend them, and up to 2 kHz a parabolic equation gives the sound over the open ground, a narrow-angle one by default and a wide-angle one with `simulation.early.parabolic_equation: wide_angle` (see [Wind and temperature](outdoor.md#wind-and-temperature)). Above 500 Hz they add pair by pair, each pair's cross term as far as the band leaves the two coherent; a room takes 500 Hz at most, as its paths are many. - Sound bent round an edge carries the whole complex UTD coefficient, whose terms add to the specular paths in pressure, as the theory has them, rather than through the cross terms that stand for that interference in the higher bands. - The echogram reads those bands' early energy from the paths' pressure, through the band filters the analysis of measured responses uses, and so do coverage maps and the material fit. Those filters let in a little of the band above, so there each path over an edge takes the mean of its rendered phases over seeds, which needs no seed. An impulse response and the echogram it came from give the same parameters in those bands: in a 7.3 x 5.1 x 3 m box without edge diffraction, G within 0.01 dB and C50 within 0.05 dB, where adding the paths in energy leaves them up to 2.1 and 1.6 dB apart. With paths over edges they agree on average over seeds, one response scattering about the echogram. - Outdoors in turbulence the echogram takes each two paths' coherence factor, the average over the eddies, and an impulse response is one moment of them, whose levels scatter about the echogram's (see [Turbulence](outdoor.md#turbulence)). - The late part still adds in energy: its rays stand for many paths with random phases. So do the points of a line or surface source, which are uncorrelated. - At a listener, the wave solver's bands take their place when it runs up to the same band or higher. Coverage maps do not run it, and keep the paths in pressure whatever `simulation.wave` says (see [Coverage maps](coverage-maps.md)). ```sh python examples/listening_room/bass.py acoustic-spaces simulate examples/listening_room/scene.yaml --out energy --coherent-band none ``` In the `listening_room` example, the early part at the sofa is 5.7 dB louder at 63 Hz from a loudspeaker against the front wall than from one a metre out, and the whole response 2 dB louder; added in energy, the two are within 0.7 dB. `--coherent-band` sets it for one run of `simulate` or `map`, and the editor's simulation page has it as "In pressure up to". ## Low frequencies: the wave solver Rays treat sound as rays, which holds while a room is large next to the wavelength. At low frequencies it is not: a small room rings at its modes, so the bass booms at one seat and vanishes at the next, and sound bends round everything. With `simulation.wave`, the lowest octave bands come from the sound field itself: ```yaml simulation: wave: enabled: true max_band_hz: 125 # the highest band it computes: 63, 125 (default), 250 or 500 points_per_wavelength: 8 # grid cells per wavelength at the top of that band scheme: auto # the grid's stencil: auto (default), isotropic or standard walls: cell_faces # cell_faces (default), or fitted: where the model has them wind: effective # outdoors: effective (default) speed of sound, or moving air device: cpu # where it steps the grid: cpu, gpu or auto; left out: this # computer's default (cpu unless tune made it auto) ``` - The sound field is computed with finite differences in time on a cubic grid over the room (an explicit leapfrog scheme just inside its stability limit), in the compiled core, on all cores. Up to the 125 Hz band the cells are 20 cm. - Waves on the grid travel a little slower the shorter they are. In closed rooms the grid takes the interpolated isotropic stencil (19 points): 0.67 % slow at 8 cells per wavelength, the same in every direction within 0.03 %. Round open models it takes the standard one (7 points), the only one with the matched layer below: up to 1.7 % slow, along the grid's axes. `scheme` picks one or the other; with fitted walls (below) closed rooms take the standard one too. - Fewer cells per wavelength make the waves slower still, along the grid's axes most: at 5 (the least `points_per_wavelength` takes), 1.85 % with the isotropic stencil and 4.56 % with the standard one. Below the default 8, the scene's warnings (`validate`, `simulate` and the editor's) say how slow they are at the top of the highest band. Each run's details give it as `wave_slow_percent`, for the grid the run took (in wind and temperature, for the slowest sound on it). - With `device: gpu` the grid is stepped on the GPU instead, through WebGPU: Vulkan, Metal or Direct3D 12, so AMD, NVIDIA, Intel and Apple GPUs alike, with the `gpu` extra (wgpu); `auto` takes a hardware GPU when wgpu finds one, and the CPU otherwise. Left out, `device` is this computer's default (see [Tuning the devices for a computer](#tuning-the-devices-for-a-computer)). Once `acoustic-spaces tune` (below) has timed both on the computer, `auto` takes whichever steps the run's grid as many times clearly faster: a GPU costs more to set up and less per step, so it can lose on short responses. The grid is laid out on the CPU either way, and the two agree to within about 1e-5 of the largest pressure (single-precision rounding). `acoustic-spaces info` names the GPU it finds. - Surfaces absorb as their materials do in each band: each material becomes a locally reacting surface whose admittance changes with frequency (a constant and resonant mass-spring-damper branches), fitted so that its random-incidence absorption matches the material's in every wave band. A material with an impedance (a ground's, see [Ground impedance](outdoor.md#ground-impedance)) is fitted to its admittance itself, phase and all, with branches without mass whose corner frequencies spread an octave apart, as a ladder of resistors and capacitors makes a porous ground's admittance, which grows with frequency at a nearly constant phase: over grass the level matches the exact solution within 0.12 dB from 40 to 315 Hz. One run covers all the bands. - Closed rooms, open models and thin screens all work. Round an open model the grid grows by a perfectly matched layer of 8 cells, which takes in the sound leaving it: what comes back is 72 to 74 dB down, against 7 to 14 dB from the grid's edge alone. Sound that runs along the layer it sends back far more, so the grid reaches past the source and the listeners, on each side the model leaves open, by 15 % of the farthest a listener lies from the source along that side (none under an outdoor ground, and none on a side that the model's own surfaces close round them). - A surface that passes through a plane of the grid's cell centres, or within 1e-10 cells of one, acts on every link between cells and every line of sight as if it lay an infinitesimal step further along -x (else -y, else -z): a wall there stays a wall on either stencil. A source or a listener exactly on a surface, an edge or a corner is read a hair off it, on the side that step gives; where the source's air on that side reaches no listener, or a listener's side has no air, on a side that does (a source on a pillar's face, a listener in a room's corner); on an edge or in a corner, into the middle of the air round it, and on a screen's free rim or corner, straight out past it. The points round a listener its gradient is read at move with it. A source whose only listeners lie on the plane of a surface through it, reached from both sides, is refused. Surfaces about 1e-10 cells off the centres can still be placed wrong, from a few links to a closed object read as air: see [Known issues](validation.md#known-issues). - With `walls: fitted` the walls lie where the model has them instead of on the cell faces nearest them: the model's faces are cut exactly through the grid's cells, and each cell they cross is stepped with the volume of its air, the open area of each of its faces and its walls' area for each material (a finite-volume form of the same update). It takes the standard stencil, indoors and in still air only (`scheme: isotropic` and outdoor scenes are refused), on the CPU or the GPU. In a rigid 4.13 x 3.37 x 2.71 m box on the 125 Hz band's grid, its 16 lowest modes come within 0.05 % of the exact ones (the grid's dispersion taken out) with the walls along the grid and within 0.38 % with the box turned by up to 14 degrees, wherever the box lies against the grid; walls on cell faces put them up to 5.2 % and 4.2 % off. The level 1.5 to 6.5 cells in front of a rigid wall is within 0.04 dB of the exact one along the grid and 0.18 dB at 3 to 14 degrees to it, where walls on cell faces are up to 1.8 dB off (8 to 16 cells per wavelength). Its limits, as measured (the figures, and how, under Walls in [Validation](validation.md#wave-based-solver)): - Steeper walls: turned by 22.5 to 45 degrees, the box's modes come out up to 4.3 % high on the 125 Hz band's grid and 1.8 % on the 250 Hz band's (1.9 % elsewhere on that grid in a one-off check), where walls on cell faces put them up to 7.1 % and 3.5 % low; the level in front of a wall at 45 degrees is 0.26 to 0.40 dB off (0.32 to 0.59 dB on cell faces). - A room's concave edge: in an L-shaped room the lowest mode comes out from 1.4 % below to 1.0 % above the exact one on the 125 Hz band's grid (0.5 % below to 0.4 % above on the 250 Hz band's), by where the edge falls within its cell, and jumps by 2.3 % (0.9 %) as the edge crosses a plane of cell centres; on cell faces it is 1.4 % (0.5 %) below wherever the room lies. - Free edges: in the cell that a surface's free edge ends in, the surface is left out, so a free-standing panel comes out up to a cell shorter and an opening in a wall of a single surface up to a cell wider on each side; the scene's warnings name such edges and their length. Behind a thin screen whose edge lies inside a cell the level was up to 1.2 dB too high (rms over 8 to 16 cells per wavelength), 0.15 dB with the edge on a cell face, where walls on cell faces were 0.3 to 0.7 dB off (one-off checks). - Absorbing walls: a wall's reflection still depends on where the wall falls in its cell. The end of a duct whose admittance is 1 reflects up to 0.077 of the wave instead of nothing (0.044 on cell faces), and the end of a resonant material up to 0.025 more or less than the grid's own reflection off a wall there. In the studio turned 17 degrees the 125 Hz band's T20 came out 6 % longer than on a grid twice as fine (3 % with the studio along the grid), where walls on cell faces gave it 9 to 23 % shorter (one-off checks). - A model is refused, with the faces named, where part of its air reaches the source only past an edge that one face alone has (a crack or a T-junction), within a hundredth of a cell of it; where two faces less than 7.2 degrees apart lie within 0.0175 of a cell of each other with air on the sides that face each other (faces laid on one another, or a layer that thin); or where it comes within a cell of the matched layer. A gap narrower than a hundredth of a cell that both of its sides reach anyway is left open. - In one-off checks at 125 Hz, a run took 1.1 to 1.4 times as long as with walls on cell faces and the default stencil in seven of the examples, and up to 2.6 times in a small room holding a sphere of 5,120 faces, where fitting the model took most of the extra time; the fit took 0.03 to 1.1 s on the examples and 13 to 18 s on a grid of 37 million cells, and the set-up's memory peaked at 2.7 to 4.1 times that with walls on cell faces. - Where a face crosses a plane of cell centres, where the fit gives a piece of air that holds no cell centre to one of its neighbours, or where a solid's convex edge meets a face just off the grid's planes, the response can change suddenly as the model moves by a hair (see [Known issues](validation.md#known-issues)). - Outdoors in wind and temperature (an [atmosphere](outdoor.md#wind-and-temperature) in which sound bends), the speed of sound changes from cell to cell: the still air's at the cell's height, plus the wind's component along the horizontal from the source. The grid is then fine enough for the slowest sound and steps in time for the fastest, on the CPU or on the GPU alike (see [How the simulation bends sound](outdoor.md#how-the-simulation-bends-sound)). With `wind: moving` (`simulate --wave-wind moving`) the air moves instead, so that sound a building sends back towards the source goes against the wind, which flows round the model's solids; it takes four to five times as long over open ground, more round buildings, and runs on the CPU. - The listener records the pressure and its gradient, so the low end keeps its direction in Ambisonics, binaural and loudspeaker outputs (to first order). The source and each point a listener samples lie between the grid's cell centres (a cell is 0.2 m on the grid up to the 125 Hz band) and take four cells a side, weighted as a cubic through their centres. Next to a floor, a wall or flat ground along the grid they leave out the cells behind it and read across it from the two cells round the point; next to a surface at an angle to the grid, an edge or an opening, and for a listener's points nearer the source than three cells, they take the eight cells round the point that it sees, weighted trilinearly. From four cells from the source on, the level does not depend on where the two lie within their cells (within 0.04 dB with the 19-point stencil). Nearer the source its sound on the grid is not a point's: the pressure is up to 2.9, 0.7 and 0.32 dB off a point source's one, two and three cells away, and the gradient's ratio to it up to 7.3, 5.4, 1.7 and 0.43 dB off, its direction up to 15, 15, 8 and 3 degrees, one to four cells away (each stencil's figures, and the 7-point one's own gain along the grid's diagonals, under Free field in [Validation](validation.md#wave-based-solver)). - The result replaces the rays from 22 Hz up to the top of the highest wave band (177 Hz for 125), through the same crossovers the impulse response synthesis uses. The parameters of those bands come from it too. - The solver steps 0.2 s further than the responses last (0.4 s with third-octave bands): the bands' filters spread each arrival both ways in time, so they read a response's last 50 ms from the run after it too (The end of a response in [Validation](validation.md#wave-based-solver)). ```sh acoustic-spaces simulate examples/concert_hall/scene.yaml --out hall --wave acoustic-spaces simulate examples/studio/scene.yaml --out studio --wave --wave-band 250 acoustic-spaces simulate examples/church/scene.yaml --out church --wave --wave-device gpu acoustic-spaces simulate examples/room_modes/scene.yaml --out modes # wave solver on acoustic-spaces simulate examples/room_modes/scene.yaml --out rays --no-wave ``` The editor's Simulation page has the same switch, where to run it, and Fitted walls. Each octave higher costs about 16 times as much: on 4 cores, up to the 125 Hz band, the studio takes 0.1 s, the concert hall (9,400 m³, 3.5 s responses) 7 s, and the church (7 s responses) 13 s per source; 6 s and 11 s with `scheme: standard`, at the cost of its dispersion. Grids of more than 40 million cells are refused, and on a GPU so is a grid with a buffer larger than the GPU binds: the field's or, round an open model, the matched layer's, of nine values a cell. `python validation/wave_gpu.py` times your GPU against your CPU; Mesa's lavapipe, a Vulkan driver that runs on the CPU (and what CI tests with on Linux), took 7.5 to 9 times as long as the CPU solver in a whole run with an earlier version of the script (the [validation report](validation.md) has the times). ![Transfer function of a 7 x 5 x 3 m box from the sum of its modes, the wave solver and rays](images/wave.png) In a 7 x 5 x 3 m box with 15 % absorption, the wave solver follows the sum of the box's modes from 22 Hz up; rays give the average level instead. In the 63 and 125 Hz bands, G is within 1 dB of the modes and T20 within 5 %; rays are up to 5.2 dB and 13 % off. What it leaves out: surfaces react locally, so their absorption changes with the angle only as an impedance's does, and absorb at most 95 % at random incidence; next to a much more absorbing band, a band absorbs somewhat more than its material says (the fit reports how much, as `wave_absorption_miss`); near the top of the highest band the grid's walls absorb a little less than their admittance (0.025 less at 500 Hz with 14 cells per wavelength); with walls on cell faces (the default; `walls: fitted`, above, puts them where the model has them) the grid puts every wall on cell faces, a wall along the grid up to half a cell from the model's and one at an angle to it in steps: in a rigid 4.13 x 3.37 x 2.71 m box moved within a cell or turned against the grid (seven placements), that moves the modes of the grid's highest band by up to 11 % on the 63 Hz band's grid, 6.4 % on the 125 Hz band's (the default's) and 2.8 % on the 250 Hz band's (more `points_per_wavelength` moves them less), and from 8 to 16 points per wavelength the level 1.5 to 6.5 cells in front of a wall is 1.5 dB rms off with the wall 0.4 cell off a cell face and up to 1.2 dB rms with it at 3 to 25 degrees to the grid (19-point stencil; [validation report](validation.md#wave-based-solver)); waves on the grid travel slower the shorter they are, at the top of the highest band with 8 points per wavelength by 0.67 % on the isotropic stencil closed rooms take and up to 1.7 % on the standard one, which open models and fitted walls take (along the grid's axes, not at all along its body diagonals; `wave_slow_percent` in the run's details), which nothing corrects, so the modes there come out up to that much low; in single precision the 19-point stencil's rounding lets a closed room's mean pressure creep, far below the bands (see The end of a response in [Validation](validation.md#wave-based-solver)), and with fitted walls a rigid closed room's mean pressure rings, as slowly (once in 100,000 steps or more); sources radiate equally in all directions in the wave bands; and air absorption, negligible there, is left out. ## Performance `simulation.performance` says how a run uses the computer; neither setting changes the results. ```yaml simulation: performance: threads: 0 # CPU worker threads; 0 (default) uses every core ray_tree: sah # sah (default) or median ``` - `threads`: the worker threads of the ray tracer (early candidates, the late part, coverage maps, calibration), of the wave solver on the CPU, of writing the responses' files (`simulate --out`, the editor's Export), and the worker processes of the spread's draws (see [Materials](scenes.md#materials)). Fewer leave the computer free for other work while a long run goes on; more than the computer's cores run as its cores (see [Memory](#memory)). The responses' files are rendered side by side, and the threads the responses leave free render the channels of each side by side too. A channel in progress holds its band signals and their spectra, which the run counts as 67 MiB for 2.5 s at 48 kHz in octave bands and 192 MiB in third-octave bands (more for a response of tens of thousands of early paths), so the channels in progress at once are held to a quarter of the computer's memory (or of its container's limit), shared between the responses rendered at once, one channel for each at least. Results do not depend on it beyond rounding: each thread sums its share of the rays, and the shares add up in another order (in the shoebox example, the late energy moved by 7 × 10⁻¹⁶ of its peak between 1, 2 and 4 threads, and the early paths were the same to the bit); the files are rendered to the same samples on any number of threads. - `ray_tree`: the bounding volume hierarchy that finds the surface a ray meets, and whether a listener can see a reflection, which is nearly all of the run time. `sah` splits it by the surface area heuristic and walks the nearer box first; `median` splits it at the middle face along the longest side, as before, for comparison. Both find the same surfaces at the same distances; where a ray meets two faces at exactly the same point (a shared edge) the other tree may take the other one. In BRAS's chamber music hall (2,309 triangles, five listeners) one band of 50,000 rays takes 6.2 s on four cores with `sah` and 21 s with `median`. `simulate`, `map` and `calibrate` take `--threads N` and `--ray-tree sah|median` to override them, `view`, `export` and `walkthrough` `--threads`; the editor's Simulation page has them under Performance. `acoustic-spaces info` prints how many cores there are. Where the wave solver steps its grid (CPU or GPU) is `simulation.wave.device`, above. ```sh acoustic-spaces simulate validation/bras/CR3/scene.yaml --out cr3 --threads 3 ``` A run's results do not depend on how many threads the linear-algebra library behind numpy is given, which is as many as the computer has cores unless `OPENBLAS_NUM_THREADS` says otherwise: the package adds its long sums itself, each in a fixed order (the early paths' spectra and signals, the IACC's correlations, the decay fits and the like; `acoustic_spaces.products`), and the example scenes give the same results, bit for bit, with one, two and four of those threads (all were run but `bim_office`). What it leaves to the library are the solvers (the eigenvalues behind turbulence's delays, a binaural decoder's pseudo-inverse, the fits of calibration and of a ground's impedance), whose results can round with the number of threads where their matrices are large (the eigenvalues of a 200 by 200 matrix did; nothing in the examples does), and live head-tracked playback. ### Memory Before a simulation or a coverage map starts, the memory of its late part is estimated (`engine.run_size`): the energy at every listener (or map point), band and millisecond of the response, and at a listener, every 10 ms, for each arrival direction (`late.directions`) and as each batch of rays gives it (`late.batches`), for every source until the run ends; and while a source is traced, the tracer's own. The places of a [walk](spatial-audio.md#walkthroughs) between those traced for their late part hold none of it: theirs is mixed from the traced places on either side when it is read, and the estimate counts the traced ones alone. On the CPU the tracer's own is a copy of the results for each thread that sums rays, 256 MiB at most together (one thread at least, however large the copy): a run whose copies would take more runs on fewer threads, and more slowly. The examples' copies take 1.6 MiB a thread at most, as the default vector-based scattering traces one band at a time; with one ray for all eight octave bands, 20 listeners and responses of 10 s would take 90 MiB a thread, so two threads. On a GPU it is the GPU's buffers, which a GPU built into the processor takes from the computer's memory. With `late.device` gpu, both or auto (auto only where there is a hardware GPU), the estimate takes the worst of the CPU, the GPU and the two together. So the memory grows with `simulation.ir_length_s`, the listeners, `late.directions`, `late.batches`, the sources and their points, and the map points (`coverage.spacing`). On the CPU the rays cost time, not memory. The 10 batches of the default add about an eighth to the late part's memory with 64 arrival directions: in the estimate, the late part of `stadium_concert` at 8 s went from 896 to 1,014 MiB and `orchestra`'s at 6 s from 668 to 758 MiB; measured on 4 threads, the whole runs went from 890 to 1,020 MiB and from 724 to 815 MiB. `orchestra`'s grew as estimated, `stadium_concert`'s by 11 MiB more, as the batches' many smaller arrays leave the memory allocator more to hold (with glibc's mmap threshold fixed at 128 KiB, that run grew by 124 MiB against the estimate's 118). A run that would need more memory than the computer has (or than its container may use: on Linux, the lowest limit on the process's control groups and on those above them) is refused before it starts, with a message that gives what a simulation would need with each setting lowered on its own (more `late.batches` need more, not less), and the editor's messages (`Room.warnings()`) note one that would need more than half of it. A map is checked again once its first source point is traced, with the early paths found there at every point, which grow with the points too (`workshop`'s map: 311 MiB of early paths beside 495 MiB of late energy). The editor's note counts a map's late part only. `threads` above the computer's cores run as its cores: more would only take turns on them, each with its copy. The estimate leaves out the model, a simulation's early paths, a GPU driver's own memory and the writing of the responses' files (see `threads` under [Performance](#performance)). The early paths take little beside the late part at a few listeners, but not in a room of many facets with edge diffraction, where the edge fade keeps the pieces of the waves round the edges in single precision: about 17 million at the third listener of BRAS CR3 in third-octave bands. Its run peaks at 10.0 GiB (11.8 GiB in third-octave bands), nearly all of it at one listener: the edge fade hands it back before the next, and in third-octave bands each listener's starts from less than 0.9 GiB. `python validation/late_memory.py` measures the estimate against what runs take (on Linux): on the CPU it came within 2 MiB of the late part's peak in `shoebox` at 1, 4 and 64 threads (4 cores), with responses of 30 to 480 s and both kinds of scattering. Whole runs, counted from the memory the process held before them, came near it or a little above: `stadium_concert` at 8 s (19 sources, 12 listeners) at 1,020 MiB against 1,014, `orchestra` at 6 s at 815 MiB against 758 (890 against 896 and 724 against 668 in one batch). Traced on a software GPU (SwiftShader's Vulkan) at 120 s, the late part peaked 59 to 66 MiB above the GPU's estimate, the driver's own; with both, at 30 and 120 s, 58 to 117 MiB above the estimate, which takes the CPU's part and the GPU's at their peaks at once. ### The late stage on a GPU The late stage's rays can be traced on a GPU, with the `gpu` extra, through WebGPU like the wave solver: Vulkan, Metal or Direct3D 12, so AMD, NVIDIA, Intel and Apple GPUs alike. ```yaml simulation: late: device: cpu # cpu, gpu, both or auto; left out: this computer's default ``` - Left out: this computer's default, `cpu` unless `acoustic-spaces tune --default auto` (or OK in the editor's tune window) made it `auto` (see below). A scene that names a device keeps it on every computer. - `cpu`: the compiled core, on `performance.threads`, as before. - `gpu`: one compute shader traces what the CPU does (detector spheres and rain, both kinds of scattering, the scattering of a surface's size, air absorption, the early stage's paths left out, arrival directions, the weight window, and outdoors the rays bent by [wind and temperature](outdoor.md#wind-and-temperature), those through [vegetation](outdoor.md#vegetation) and the open sky); the listeners' side of the first reflections' scattered sound is found on the CPU. Rays start where the CPU's do, then draw random numbers of their own, in single precision, so the two agree statistically, not ray for ray. Its lengths are coarser than the CPU's: a straight ray meets no face nearer its start than a millionth of the model's size (the CPU's, a billionth), and a reflection starts a hundred-thousandth of it off its face, so the CPU traces the runs with a source or a listener right by a surface (see below). The tests trace main's stored runs on the GPU and check that they land within the spread of the CPU's own results over seeds. The shader is compiled once per session with only what the scene has of the outdoors (bent rays, vegetation), in seconds. On Direct3D 12 (Windows) its compiler (FXC) takes a minute or two over either, without its optimizer, which got the vegetation wrong; it would take more than an hour over both, so the GPU leaves a scene with rays bent by the air and vegetation to the CPU there, which the run says. - `both`: the CPU (on all its threads but one, which keeps the GPU busy) and the GPU share the rays, each taking the next part as soon as it is done with the last, so the faster one traces more (if the GPU declines a part at run time, the CPU traces it and the rest on all its threads). Which rays each traces depends on how fast each goes, so two runs differ within the noise of the ray count. `cpu` gives the same result every time, and so does `gpu` until the weight window fills a family of copies (see below). - `auto`: the fastest of `cpu`, `gpu` and `both` on this computer, for the run's response length (a longer response keeps each ray going longer, which can change which is fastest). It takes the choice `acoustic-spaces tune` kept for that length (below). Without one, a short trial on the scene's own model traces 8,192 rays, for the run's own length, on the CPU and on the GPU, picks the fastest and keeps it for that range of lengths (up to 0.5, 1, 2, 4 s and so on). It keeps the CPU, the safe choice, when wgpu finds no GPU or only a software one, or when neither the GPU nor both together would be at least 20 % faster. `--no-device-trial` (`simulate` and `edit`) skips the trial: `auto` then takes the choice kept for the nearest length, or the CPU when there is none. ### Tuning the devices for a computer `acoustic-spaces tune` times every option and keeps the fastest for `auto`, once per computer (again after changing the GPU or its driver): ```sh acoustic-spaces tune # the concert_hall example acoustic-spaces tune my-hall.yaml --rays 50000 # your own scene, at your ray count acoustic-spaces tune --lengths 1 3 8 # other response lengths (s) acoustic-spaces tune --default auto # time, then make auto this computer's default acoustic-spaces tune --default cpu # back to the CPU, without timing anything acoustic-spaces info # the default, and what auto takes now ``` - The late stage traces the scene's first source to its listeners (but those too near a surface for the GPU, see below) with the scene's settings (or `--rays` per band) on `cpu`, `gpu` and `both`, for responses of 0.5, 1, 2 and 4 s (`--lengths`), and keeps the fastest for each: the CPU unless another is at least 10 % faster. Each length stands for its range (up to 0.5, 1, 2, 4 s and so on). `auto` then takes the choice for the run's range, or for the nearest longer one, else for the longest, with no trial; `both` shares the rays by the speeds timed there. - The wave solver steps the scene's wave grid (as set in its wave settings, whether the scene uses the solver or not) for two short responses on the CPU and on the GPU. The two times give each device's cost per cell to set up and per step, so `auto` can compare them for any run's step count; `--no-wave` leaves it out. - It prints a table of the times and what `auto` will take, and `acoustic-spaces info` shows the choices later. - A software GPU (lavapipe, SwiftShader) is timed too, but `auto` never takes it. - `--default auto` then makes `auto` this computer's default: scenes that leave `simulation.late.device` and `simulation.wave.device` out run on the fastest device found. `--default cpu` switches back. Without `--default`, tune keeps the timings and leaves the default as it is (`cpu` at first). - The choices are kept per computer (the GPU's name and the CPU's thread count) in `acoustic-spaces/devices.json` in the user cache folder (`~/.cache`, `~/Library/Caches` or `%LOCALAPPDATA%`), with the times and the default. Deleting the file forgets them. - In the editor, Simulation > Tune CPU and GPU… times the open scene, shows the table, and asks with a check box whether to make `auto` this computer's default (ticked). OK saves the timings and that choice; Cancel saves nothing, not even the timings. - A scene that names its devices keeps them on every computer, and with `cpu` the seed repeats a run exactly on a computer (`gpu` and `both` may vary a little); between computers the last digits can differ (the linear-algebra library's solvers, for one, differ from one processor to the next). Scenes saved by the editor before 3.1.0 name `cpu`: set **Run on** to *default* (or leave the tune window's second check box ticked for the open scene) to let them follow the default. Sound through partitions and openings (an outdoor scene's sky, which lets sound out into no room, is not one), coverage maps and vegetation of more than 16 media are traced on the CPU whatever the setting, and so are runs whose results the GPU's buffers cannot hold (many listeners and arrival directions over a long response), and runs with a source nearer a surface than 2 millionths of the model's size, a listener so near one that the start of the GPU's reflections would cost it more than 0.1 dB of the surface's scattered sound (with the late stage's own spheres: nearer than about 47 millionths of the model's size, or than 0.6 to 1.2 mm in a model of 2 to 25 m; in a model of more than 12 km it can be less than those 47 millionths), or either nearer both sides of an inner edge than 50 millionths where the two surfaces meet at a right angle (up to 550 at sharper angles, fewer at wider ones and none from about 96 degrees on). `simulate --late-device` overrides the setting; the editor's Simulation page has it as "Run on" under Late reverberation. When it is not `cpu`, the progress messages say where the rays went and why (`talker: late rays traced on the CPU (no hardware GPU)`). With splitting, a ray's copies on the GPU advance together, where the CPU follows each to its end before it takes the next. Where the weight window asks for more copies than a family may have (`max_family`), the GPU so makes them earlier and traces more reflections in the late tail (up to twice as many in the example box): the same expected energies, with a tail that varies less. Which of a family's copies split before it is full then depends on the order the GPU's threads come in, so two `gpu` runs of such a scene differ in the late tail, within the noise of the ray count. `python validation/late_gpu.py` times the late stage on each device in BRAS's two rooms and two example halls, and shows how far T30, EDT and C80 come out from the CPU's next to how far a second CPU run with the next seed does; `python validation/outdoor_gpu.py` does the same for the outdoor examples (the stage in the wind, the tree belt and the hillside), with the late sound's level and centre time per listener and band. The GPU's chords through the atmosphere are tested against the CPU's ray for ray: the same turns, the same curve to the millimetre. `python validation/rays_gpu.py` times the ray searches alone, the face a ray meets next and whether a listener can see a reflection, and checks that the GPU finds the CPU's faces. The GPU works in single precision, so its boxes and triangles are widened slightly to keep rays from slipping between faces that meet; it finds the CPU's face for all but rays that meet two faces at nearly the same point. ## Validation The tests check the simulation against theory on Linux, macOS and Windows: exact image sources in a box, Eyring's reverberation time and Barron's revised theory in a diffusing box, ISO 3382-1 parameters of known decays, spatial encoders against closed forms, the convolvers against direct convolution, and sweep measurements of synthetic rooms. A cross-check against pyroomacoustics in four rooms agrees within 5 % on T30 with the same scattering model, from purely specular to fully diffusing surfaces. Against measurements in four rooms of the BRAS benchmark, a seminar room comes out within 2 % on reverberation time from 500 Hz to 4 kHz and within one JND on clarity, and a chamber music hall and an auditorium within about one JND on clarity and 6 to 10 % and 12 to 21 % long on reverberation time (from 250 and 125 Hz to 4 kHz), which comes within about one JND once their absorption is fitted with this package's own rays. In two-room diffuse theory BRAS's two coupled rooms are joined by about 1 m² more than their model from 250 Hz to 2 kHz, with the door ajar (10 to 16 times the model's slit) and open alike, and IACC_L comes within one JND of binaural responses in 19 to 26 of 30 values per room. Edge diffraction is checked against the exact solutions for a half-plane and for wedges, against Maekawa's chart, and over two edges against the exact BTM solution. The wave solver matches the frequencies of a box's modes within 0.25 % and their decay rates within 2 % with walls whose admittance changes with frequency, the reflection and absorption of walls, and the free-field level within 0.04 dB from four cells from the source on (the 19-point stencil, wherever the source and the listener lie within their cells), and round an open model what comes back from the grid's edge is 72 dB down or more. Sound through a partition reaches the level behind it that diffuse-field theory gives within 0.3 dB, and coupled rooms decay in the two slopes of the two-room model. The [validation report](validation.md) has the details, the numbers and the scripts to reproduce them.