Coverage maps¶
A coverage map gives the parameters on a grid over the audience area, the way CATT and ODEON draw them: strength G and sound pressure level, C50, C80, D50, EDT, T20, T30 and Ts per octave band, and the A-weighted level and speech transmission index; outdoors also the level relative to free field, and the insertion loss of the buildings, barriers or vegetation the map was also run without (see Results outdoors).
acoustic-spaces map examples/lecture_hall/scene.yaml --plot sti.png --parameter sti
acoustic-spaces map examples/concert_hall/scene.yaml --spacing 0.5 --json map.json \
--screenshot c80.png --parameter c80 --band 1000

The map covers the surfaces named in coverage.surfaces (by default those whose names
contain “audience”, else the floor; outdoors, the ground, leaving out the
points inside buildings) with square columns spacing metres wide, with a point at the
listening height above the surface in each (above its top, when a slab’s underside is
in the same group); a balcony over the stalls gets a second level of points. Columns
along a slanted wall keep the part over the surface. A model that holds several rooms is
mapped in every room (with the sound that passes between them), and a column that a wall
between two rooms crosses gets a point on each side that holds at least a fifth of it.
The early part is exact at every point, as at a listener. The late part comes from one
ray tracing run per source in which every ray adds its path length through a slab of air
around each point (a track-length estimate, with a vector reflection’s specular share on
a leg of its own, as at a listener: see Simulation),
counting only the rays in the point’s room and only the part of the slab in its air:
what lies past a wall, in the next room or inside a building is left out. A map of
hundreds of points costs about as much as a few listeners: the concert hall example (480
points, two sources, 50,000 rays per band) takes under two minutes on 4 cores. In the
shoebox example, full simulations at three of the map’s points give G within 0.3 dB of
the map and T30 within 5 % from 125 Hz to 4 kHz (the tests, with one seed); at other
points and seeds T30 strays further now and then, as both carry the late rays’ noise.
With the statistical late method each point gets the late part a listener there would,
and G agrees within 0.01 dB.
Each source radiates its sound power per band (its level_db, spectrum, gain_db
and eq_db; see Sources and directivity), which sets the
sound pressure levels. The STI (IEC 60268-16, with the male weighting, or the female
one for a speech_female source) takes that as the speech level, with auditory masking
and the reception threshold, and noise_db as the background noise. In the map of all
sources together, each source’s sound arrives its delay_ms later (the town_hall_pa
example’s delays.py maps its sound system with and without its delay loudspeakers).
Line and surface sources add up the sound of their points and arrays radiate their
beams, as they do at a listener (the workshop example maps the A-weighted noise of
both). map prints the range of every parameter, --plot saves the top view,
--screenshot the 3D view and --json every value of every point. Settings live in
the scene:
coverage:
surfaces: [audience_floor] # default: names with "audience", else "floor"
height: 1.2 # listening height above the surface, m
spacing: 1.0 # distance between points, m
rays: 50000 # rays per source and band (default: simulation.late.rays)
noise_db: 35 # background noise for the STI, dB SPL (or one per band)
spread: false # also the values' uncertainty (see Uncertainty below)
From Python:
from acoustic_spaces.engine import coverage_map
from acoustic_spaces.viz import plot_map, show_room
result = coverage_map("examples/concert_hall/scene.yaml")
both = result.get() # all sources together; result.get("soloist") for one
c80 = both.value("c80", band=4) # one value per point, 1 kHz
plot_map(both, "c80.png", parameter="c80", room=result.room)
show_room(result.room, coverage=both, parameter="sti")
Maps do not run the wave solver: whatever simulation.wave says, their lowest bands
come from the early paths, in pressure up to simulation.early.coherent_max_band_hz
(see Low frequencies),
and the rays. For a small room’s modes, put listeners where they matter and run them
with the wave solver. Nor do maps give
ISO 3382-3’s quantities for open-plan offices (D2,S, Lp,A,S,4m, the distraction distance
rD and the privacy and comfort distances); listeners on a line from an omnidirectional
source with the standard’s speech spectrum and level give the A-weighted level and the
STI they are read from (see Simulation).
Uncertainty¶
With spread: true in the map’s settings (--spread on the command line, the tick box
under Uncertainty on the coverage map’s page in the editor) the map’s values get the
standard uncertainty that the materials’ absorption uncertainty leads to (see
Materials), an insertion loss and the long-term levels too. A map
keeps no response at its points to re-weight, as a listener’s spread does, so it follows
the law of propagation of uncertainty (GUM, JCGM 100:2008, 5.1.2): for each material
with an uncertainty the map is traced twice more, on the same points and along the rays
of the map itself, with its absorption one standard uncertainty up and down. Half the
difference of the two maps is that material’s part, and the root of the sum of the
parts’ squares the standard uncertainty of each value at each point. A map with M such
materials takes about 2 M + 1 times as long. A value that one of the runs leaves
undefined (a decay too short for a T30, say) has no uncertainty.
map prints the least, the median and the largest standard uncertainty of every
parameter beside its range, and --json writes every point’s with each material’s part
(uncertainty in each map, null where a value has none). --show standard draws the
standard uncertainty in place of the value, --show low or high an end of the 95 %
interval and --show at_least or at_most a one-sided bound (of 95 %, or of
simulation.uncertainty.one_sided, --one-sided on the command line); the editor’s map
panel has them under Show. The interval and the bounds take the result as normal
about the map’s value: the value less and plus 1.96 standard uncertainties, or 1.645 for
a one-sided 95 %, held to what the parameter can be. From Python,
acoustic_spaces.engine.sensitivity.coverage_map(scene, spread=True) gives each map its
spread, and the map’s spread_of(parameter, part, band) the values that --show
draws.
The law is first order, so where a value bends over a material’s uncertainty the standard uncertainty comes out low. In a box of 8 by 6 by 3.5 m, against the Monte Carlo of a listener at one of the map’s points (2 000 draws): with standard uncertainties of 0.02 to 0.03 on its three materials every parameter’s is within 6 %; with a tolerance of 0.1 on each, the A-weighted level’s is 4 % low, the STI’s 3 %, D50’s 5 %, a band’s level’s, G’s, C50’s and C80’s up to 8 %, T30’s up to 13 % from 250 Hz (below that the listener’s draws leave T30 undefined) and T20’s, EDT’s and Ts’s up to a quarter, at 63 Hz.
The rays’ random error is not counted, as it is in a listener’s spread, nor what a listener’s spread leaves out. The uncertainty has that error itself: where a value changes from one seed to the next, so does its uncertainty, and a material’s small part of it more. Between two seeds of the lecture hall example’s map, T30 at 1 kHz differs by 0.12 s (root mean square over its points) and its standard uncertainty, 0.23 s at the median, by 0.05 s; the standard uncertainty of the A-weighted level, the STI, C50 and G differs by 1 to 3 %, and EDT’s by 5 to 12 %. With four times the rays T30’s two figures fall to 0.05 s and 0.03 s, and the others’ to about 1 %, EDT’s to 3 to 10 %.