# Scene files A scene is a YAML file that names the geometry, the materials, which surface gets which material, and where the sources and listeners are. See [`examples/shoebox/scene.yaml`](https://github.com/naelolaiz/acoustic-spaces/blob/main/examples/shoebox/scene.yaml) and the schema in [`src/acoustic_spaces/scene/model.py`](https://github.com/naelolaiz/acoustic-spaces/blob/main/src/acoustic_spaces/scene/model.py). Frequency-dependent data uses eight octave bands from 63 Hz to 8 kHz, or 24 third-octave bands from 50 Hz to 10 kHz (see [Frequency bands](simulation.md#frequency-bands)). ## Geometry | Format | Read with | Names used for material assignment | | --- | --- | --- | | OBJ | built-in reader | `usemtl` material, `g` groups, `o` object | | DXF | [ezdxf](https://ezdxf.mozman.de/) (3DFACE, MESH, polyface and polygon meshes, closed 3D polylines, block references) | layer | | glTF / GLB | [trimesh](https://trimesh.org/) | material, node and mesh names | | STL, PLY, OFF | trimesh | file name | | IFC (`.ifc`) | [IfcOpenShell](https://ifcopenshell.org/), the `ifc` extra | element name, type name, materials, IFC class | | Collada (`.dae`) | built-in reader (triangles, polylists, polygons, nodes and instanced nodes) | material, geometry name | | SketchUp (`.skp`), experimental | [openskp](https://github.com/iamahsanmehmood/openskp), the `sketchup` extra | material | Simple rooms need no CAD file: `geometry: {box: [8, 6, 3]}` builds a rectangular room from the origin, and a floor plan is raised to a height (see [`examples/lecture_hall/scene.yaml`](https://github.com/naelolaiz/acoustic-spaces/blob/main/examples/lecture_hall/scene.yaml)): ```yaml geometry: floor_plan: [[0, -4], [0, 4], [14, 8], [14, -8]] # corners, in order, any shape height: 6 assignments: floor: audience ceiling: plaster wall_1: wood # the edge from the first corner to the second walls: concrete # every other wall ``` OBJ is the recommended exchange format: SketchUp, Rhino, Revit and Blender all export it with material names. Set `geometry.units` (`m`, `cm`, `mm`, `in`, `ft`) and, when the file is +y up (Blender's OBJ default, glTF always), `geometry.up_axis: y`. Without `units`, a DXF file is read in the units its header records (`$INSUNITS`), an IFC or Collada file in the units it records, and any other file in metres; a Collada file's up axis is the one it records (X_UP, Y_UP or Z_UP). SketchUp's Collada export (`.dae`) is read as it is (see [`examples/rehearsal_room`](https://github.com/naelolaiz/acoustic-spaces/blob/main/examples/rehearsal_room/scene.yaml)). SketchUp files can also be read as they are, with the `sketchup` extra: openskp reads them without SketchUp, in metres. That reader is young. Faces are matched to materials by colour, so give each material its own colour; a face painted differently on its two sides takes its front's material; and some files do not read at all (the BRAS auditorium, for one). An OBJ export from SketchUp is then the way. Polygons are triangulated, duplicate vertices merged, degenerate faces, copies of a face (the same corners, turning the same way) and the vertices no face uses dropped, and faces that meet along an edge are turned to agree with each other (each part of the model keeps the orientation most of its area has), so a few faces flipped by the exporter do not spoil the volume or the inside checks. Where a face's edge runs past the corners of faces on its other side (a T-junction, which SketchUp stitches with faces of zero area), the edge is split at those corners, so the model stays closed; also where two surfaces and a third face meet along the line it runs past. A stitch whose own corner lies on its edge (within 10 µm) is dropped there, as the split closes the gap. A model with no faces left is refused, as is one with coordinates that are not finite numbers or a face that names a vertex the file does not have. `validate` then reports surfaces without a material, sources or listeners outside the room or on a surface (within 1 µm of it, or within 2e-9 of the model's diagonal where that is more, twice the least distance at which a ray traced on the CPU meets a face; an opening, with air on both sides, does not count) and listeners within 1 cm of a source; it warns about models that are not closed (rays would escape), listeners so close to a surface or an opening that the late part comes out noisy, and assignments that match nothing. Errors exit with status 1, and with `--strict` warnings too. Normals may point either way: the room is the space the faces close off, found from the faces themselves (see [Walls, doors and openings](#walls-doors-and-openings)), and a panel standing in the room, with air on both sides, reflects and absorbs on both. ### Outdoors `geometry.ground` makes a scene outdoors: a flat ground under an open sky, with `buildings` (footprints raised to a height), `barriers` (thin screens along a path), `vegetation` (belts of trees, hedges and lone trees, which sound passes through) and the objects of a model file standing on it. See [Outdoor scenes](outdoor.md). ```yaml geometry: ground: margin: 30 zones: # parts of the ground with materials of their own - {name: road, polygon: [[-40, -4], [60, -4], [60, 4], [-40, 4]]} buildings: - {name: hall, footprint: [[0, 10], [20, 10], [20, 22], [0, 22]], height: 9} barriers: - {path: [[30, 6], [30, 20]], height: 3} vegetation: - {name: hedge, path: [[30, 24], [50, 24]], width: 1.5, height: 2} ``` The ground can be a terrain, its heights on a grid from a file or given in the scene (`ground.terrain`), and the buildings can come from a GeoJSON map (`geometry.buildings_file`); see [Terrain](outdoor.md#terrain) and [Buildings from a map](outdoor.md#buildings-from-a-map): ```yaml geometry: ground: terrain: {file: hills.asc} # or {heights: [[...], ...], spacing: 10} map_origin: [552000, 5806000] # subtracted from the map files' coordinates buildings_file: {file: town.geojson, height: height, default_height: 9} ``` Outdoors, `atmosphere` sets the wind and the temperature over the ground, which bend sound down or up, into shadow zones (see [Wind and temperature](outdoor.md#wind-and-temperature)), their eddies, which blur the ground dip, scatter sound into shadows and make it flicker (see [Turbulence](outdoor.md#turbulence)), and `zones`, parts of the scene with weather of their own (see [Weather zones](outdoor.md#weather-zones)): ```yaml atmosphere: preset: windy # neutral, windy, sunny_day or clear_night wind: {speed_m_s: 8, direction_deg: 90} # 8 m/s 10 m up, blowing towards +y turbulence: moderate # weak, moderate or strong, or its structure parameters; # {preset: moderate, height_m: 2}: weaker with height zones: # polygons in the plan; what they leave out is the scene's - {name: lee, polygon: [[120, -60], [300, -60], [300, 60], [120, 60]], wind: {speed_m_s: 1}} ``` `long_term` runs an outdoor scene in several weather classes, each holding for a share of the day, the evening and the night, for the level over a long term and L_den (see [Levels over a long term](outdoor.md#levels-over-a-long-term)): ```yaml long_term: classes: # a class takes the scene's weather where it says nothing - {name: downwind, share: {day: 0.4, evening: 0.3, night: 0.2}} - {name: upwind, wind: {direction_deg: 180}, share: {day: 0.3, evening: 0.2, night: 0.1}} - {name: inversion, preset: clear_night, share: {day: 0, evening: 0.3, night: 0.6}} - {name: still, preset: neutral, share: {day: 0.3, evening: 0.2, night: 0.1}} # periods: [{name: day, hours: 12}, {name: evening, hours: 4, penalty_db: 5}, # {name: night, hours: 8, penalty_db: 10}] # the default, L_den ``` ### BIM models (IFC) IFC files from Revit, ArchiCAD, Vectorworks or any other BIM program are read with the `ifc` extra (IfcOpenShell). There are two ways, and [`examples/bim_office`](https://github.com/naelolaiz/acoustic-spaces/blob/main/examples/bim_office/scene.yaml) shows both: ```yaml geometry: file: office.ifc space: Office # one room, from its space boundaries; leave out for every element assignments: Plaster on brick: plaster # an IFC material IfcWindow: glass # every element of a class Door: wood # one element, by name ``` - With `space`, only that room (an IfcSpace, by name, long name or GlobalId) is read: the faces of the room that each element bounds, as BIM programs export them as space boundaries (Revit: export with space boundaries, first or second level). Each face is named after its element; one with no element behind it, an opening to another room, is a `virtual boundary`. This gives a closed room with one face per surface, which is what the simulation wants. A file without space boundaries gives the space's own solid, cut into triangles of at most 50 cm, each named after the element behind its middle: windows and doors then have ragged edges, so export boundaries where you can. - Without `space`, every building element is read as IfcOpenShell builds it: walls, slabs, roofs, windows, doors, stairs and furniture, with their openings cut. Openings, virtual elements and building services (ducts, pipes, lights) are left out. Walls then have both sides and their thickness, and solids that only touch do not share edges, so the model reads as not closed even when no ray escapes (the leak finder tells); the volume and the inside checks are skipped. Each face's names, for assignments, are its element's name, its type's name, its materials (a layer set's name, then each layer's material) and its IFC class (`IfcWallStandardCase` also as `IfcWall`); the first that an assignment names gives its material. ### Finding leaks A model that is not closed lets rays escape, and its reverberation comes out too short. The warning counts its open edges; the leak finder shows where the holes are: ```sh acoustic-spaces validate examples/leaky_classroom/scene.yaml --leaks acoustic-spaces view examples/leaky_classroom/scene.yaml --leaks ``` ```text leaks: 5000 rays, up to 100 reflections each: 4084 escaped (81.7 %) 1. 3813 rays (76.3 %) through a gap of about 3.6 m2 (3.00 x 1.20 m) by east_wall at (9.00, 3.51, 1.59) m 2. 271 rays (5.4 %) through a gap of about 0.27 m2 (9.00 x 0.03 m) by ceiling, north_wall, west_wall at (4.08, 6.99, 3.00) m ``` It traces rays from the sources (5,000 by default, `--rays` sets how many), reflecting them diffusely off every surface whatever its material, so that they reach every corner, for up to 100 reflections each. Each ray that finds no surface ahead has escaped, and is put down to the gap it went through: the open edges round a hole, with open edges that come within 2 % of the model's size of each other counted as one gap (a ceiling that stops short of a wall leaves open edges on both). For each gap the report gives the rays that escaped through it, its area and size (from its open edges, which run round it), where the rays crossed it and the surfaces next to it, those with the longest open edges first. In the example the window glass is missing from the east wall and the ceiling stops 3 cm short of the north wall. `view --leaks` draws the open edges in red, the escaping rays from their last reflection to past the hole, and a numbered marker on each gap; in the editor, **View > Show leaks** does the same and writes the report to the messages. Rays that leave through a surface letting sound through (an opening to the outside, see [Walls, doors and openings](#walls-doors-and-openings)) are listed as such, not as a leak. A closed model keeps every ray; one that loses some all the same has faces that meet without closing, and the report names them. From Python, `acoustic_spaces.engine.leaks.find_leaks(room)` gives the same as a `Leaks` object, and `acoustic_spaces.viz.plot_leaks` draws it. ## Materials Each entry in `materials` takes coefficients from one of: - `preset: `: the built-in database (`acoustic-spaces materials` lists it); - `file: `: a table of rising centre frequencies in Hz, absorption and optionally scattering, one row each, at any band resolution (the layout the [BRAS](https://doi.org/10.14279/depositonce-6726.3) benchmark uses); - `file: ` with `entry: `: a material of a CATT-Acoustic or ODEON material library (see below); - `absorption: [...]` with eight octave values or 24 third-octave values, which also overrides a preset or file; - `impedance:` a porous ground's impedance (`grass`, `snow`, `asphalt`... or a flow resistivity; `reaction: extended` for one whose impedance changes with the angle), which gives the absorption and reflects as a ground does (see [Ground impedance](outdoor.md#ground-impedance)). `scattering` is a number, eight or 24 values, or the id of a built-in scattering entry (`acoustic-spaces materials --kind scattering` lists them; `theatre_audience`, measured over rows of seated people, rises from 0.3 at 125 Hz to 0.7 from 1 kHz up, and stands for the rows of an audience area modelled as one raked plane, as CATT-Acoustic and ODEON models do). Without it a material scatters 0.1 in every band, and a ground with an `impedance` nothing (see [Ground impedance](outdoor.md#ground-impedance)). File data with more than one value in some octave (third-octave tables) stays in third-octave bands; other data is averaged onto octaves. Bands with no data (63 Hz in most tables) take the nearest band's value and the material's `source` says which. Coefficients run from 0 to 1: values written in the scene must lie in that range, and a file's values outside it (absorption measured in a reverberation room can exceed 1) are taken as 0 or 1, with a warning that names the material, the file and the bands. Surfaces get a material through `assignments` (any geometry name to a material), by having the same name as a material, or through `default_material`. Names match whatever their case (`brick_rough` names SketchUp's `Brick_Rough`), though a name written the same way wins over one in another case. `uncertainty` (**Absorption uncertainty** on the material's form in the editor) says how far a material's absorption may be off: a standard uncertainty (`distribution: normal`, the default) or a tolerance of plus or minus the value (`distribution: uniform`), in absorption coefficient units, one value or one per octave band, with an optional `source`. A material's bands are taken as moving together, and the materials as independent of one another. ```yaml materials: plaster: absorption: [0.02, 0.02, 0.02, 0.03, 0.04, 0.05, 0.05, 0.05] uncertainty: {absorption: 0.02, source: lab report} ``` A built-in material (`preset`, with no absorption values of its own) that gives no uncertainty takes `simulation.uncertainty.presets`, as the built-in database does not say where its values come from (**Built-in materials** in the editor's simulation settings): ```yaml simulation: uncertainty: presets: tolerance # tolerance (default), iso_12999_2 or none ``` `tolerance` is plus or minus 0.1 in every band; `iso_12999_2` is twice the reproducibility standard deviation that ISO 12999-2:2020 gives for absorption measured to ISO 354, sigma_R = m alpha + n, as a standard uncertainty: from 250 Hz to 4 kHz the standard's octave bands' (Table 2, for the practical absorption coefficient of ISO 11654), elsewhere the mean of its third octaves' (Table 1; the 63 Hz octave from the 63 and 80 Hz rows, the 8 kHz octave, past the table, the 5 kHz row's); `none` gives them none. The standard's data come from absorbers, and below 100 Hz from outside ISO 354's range, so for hard surfaces and the 63 Hz octave it is taken beyond them. Plus or minus 0.1 is much for a hard surface: the shoebox example's painted concrete, 0.01 to 0.02, is drawn anywhere from 0 to 0.12, so that example's traced T30 at 1 kHz, 1.28 s, lies near the top of its 95 % interval, 0.74 to 1.49 s. For an absorber ISO 12999-2's reproducibility is largest at low frequencies (for alpha = 1, 0.41 at 63 Hz, 0.20 at 125 Hz and 0.040 at 1 kHz), so twice it spreads the lowest bands far. From 500 Hz to 4 kHz it is the same for every absorption (0.040, and 0.050 at 4 kHz), and a hard surface gets the least in the lowest bands (for alpha = 0.02, 0.023 at 63 Hz and 0.019 at 125 Hz). The spread names the materials that took the default (`assumed`). `acoustic_spaces.engine.uncertainty.material_spread` gives the uncertainty this leads to in each listener's ISO 3382-1 parameters: the mean, combined standard uncertainty and 95 % coverage interval of many draws, a Monte Carlo propagation as GUM Supplement 1 (JCGM 101:2008) describes. Each draw takes the absorption from its distribution and re-weights the traced run instead of tracing again, so the run must be simulated with the materials' face groups (`acoustic_spaces.engine.reweight.groups_of`, then `simulate(..., groups=...)`), in octave bands, with stochastic ray tracing for the late part, without the wave solver and with at most 16 materials on its surfaces. A band in which a material absorbs everything (an absorption of 1, as some absorbers have in some bands) is not drawn, as no energy is left in it to re-weight; the spread names these (`held`). A draw does not go below what the material lets through, which counts as absorbed. An absorption uncertainty beside a ground's impedance is left out, with a warning: the impedance gives the ground's reflection, which does not follow the absorption as other surfaces' do. On a ground with zones, a reflection near a zone's edge mixes the grounds on both sides, and a draw takes it as off the ground it meets alone. To each draw it adds the rays' random error: the standard error of the late rays' batches (`simulation.late.batches`, 4 or more) times a deviate of Student's t with one degree of freedom fewer than the batches, as GUM Supplement 1 takes a quantity known from that many observations. The budget gives each input's standard uncertainty alone (`absorption`, `rays`), and the combined one is the root of the sum of their squares: the rays' error is added to each draw on its own, so its variance adds exactly, where the standard deviation of draws that hold it would be unsteady with few batches. An end of the interval, or a one-sided bound, past what the parameter can be (a decay time below 0, a D50 above 1) is held at that limit, as the Analytical Methods Committee recommends near a natural limit (AMC Technical Brief 26A). The parameters from the late sound's directions (LF and the like) have no standard error and take the absorption's alone. Not counted: the scattering and the method, and a parameter that some draw leaves undefined (a decay too slow for the response's length, say) gets none in that band. Of the method's errors, those over edges are listed where a response has paths over edges (`not_counted`), each with the largest difference of the level from the exact solution that [Validation](validation.md#edge-diffraction-against-the-exact-solution) finds in each band, as the band adds its paths in pressure or in energy: over one edge, over two (`second_order`), a path reflected on both sides of an edge left out (`one_side`), and where a path reaches an edge's end (a solid block's corners; a thin screen's edges fade out past their ends). Where the [solver for whole rows](outdoor.md#sound-over-rows-of-barriers-and-buildings) carries a row's sound, its own largest difference from the [wave calculation](validation.md#rows-of-roofs-and-barriers-against-a-wave-calculation) is listed in those bands (`whole rows`) and the edges' in the others. That sound stays as it was traced in every draw, though it depends on the absorption of a ground without an impedance. The method's errors are not drawn, as they are measured for whole levels in a few geometries, not for each path. In the lowest bands, where the early paths add in pressure, a reflection's phase follows its face's admittance, which is fitted to the absorption; the draws take it between fits at nine absorptions of each material over their range rather than a fit of their own: in the shoebox example G within 0.17 dB and C80 within 0.20 dB of a fit for each draw at 63 Hz, where a fit of its own moves them by as much for a change of 0.001 in the absorption (0.18 and 0.23 dB in one of the draws furthest off). `acoustic-spaces simulate` does this itself when a material on the surfaces has an uncertainty, its own or a built-in material's: it prints the largest combined standard uncertainty in JNDs from 125 Hz to 4 kHz, with its budget, 95 % interval, one-sided bounds and the errors over edges, and `parameters.json` holds them all (`uncertainty`). With settings that cannot re-weight (third-octave bands, say) it leaves the spread out and says what the spread needs, as a warning when a material gives an uncertainty of its own; so does the editor, in its messages. The editor shows each run's results at once, draws the spread after them and gives it in the results table's tips. The draws add to a run: in the concert hall example (five built-in materials, six responses) 400 draws take 21 s in four worker processes (below; 72 s in the run's own process) after a 12 s run on four cores, about half of their work the lowest bands' paths added in pressure for each draw; `presets: none` leaves the built-in materials out. `acoustic-spaces simulate` and the editor work the draws out in worker processes, as many as the run has threads (`simulation.performance.threads`, `--threads`) and the cores it may use, with the same results as in the run's own process and the same messages. Each process takes a run of one response's draws at a time and holds that response, as traced and as a draw re-weights it, what the run's draws share (up to 128 MiB of the coherent bands' delay phases and band grids) and its own interpreter, some 80 MiB; the processes take at most half of the computer's memory (or of its container's limit) together, so fewer of them for large responses. There is one process for each 100 draws of all the responses together at most, so a spread of fewer than 200 draws in all stays in the run's own process, as does every spread with `--threads 1`. The admittances the draws take in the lowest bands are fitted before the draws, each once. The processes inherit the run's environment and the cores it may use and set nothing of the linear algebra's threads: a draw's products are added in a fixed order, and the library's solvers (the admittances' fits) run in them as in the run's own process. The results come out the same to the last bit, except on an Intel Mac, where Apple's Accelerate rounds a sum by where its numbers lie in memory and the admittances' fits may differ in their last digits as they may from one fit to the next in one process. In Python, `material_spread` and `with_spread` take `workers` (1, the default, for none; 0 for every core). The draws stay in the calling process in a daemonic process (a `multiprocessing.Pool`'s). The processes are started by spawning, which imports the main module again in each, so a script that gives `workers` must do so under `if __name__ == "__main__":`, or the call ends with an error. `simulation.uncertainty.draws` is the number of draws: 400 unless the scene says otherwise, 0 for no spread (`--spread-draws` on the command line, **Draws** in the editor's simulation settings). For a normal spread, 400 draws leave the standard uncertainty good to about 7 % and each end of the 95 % interval to about a quarter of the standard uncertainty (twice their own standard deviation). With `draws: adaptive` the draws go on as the adaptive procedure of GUM Supplement 1 has them (JCGM 101:2008, 7.9): batch after batch until, for every result in every band of every response, twice the standard deviation of the mean, of the standard uncertainty and of each end of the interval (and of each one-sided bound, below) is within the numerical tolerance of the standard uncertainty, half a unit of its first digit. A batch is 100 draws, not the Supplement's 10 000 (a number it calls arbitrary), as each draw re-weights the whole run; the test is first made after ten batches, as two this small can pass by chance; and the draws stop at 20 000, the Supplement's own first test. `stable` in `parameters.json` says whether the test was met (null for a number of draws given beforehand, which is not tested). The test asks for many more draws than the default: from 9 000 to 14 500 in runs of the shoebox example. For a limit on one side, the spread gives each result's one-sided bounds from the same draws (`at_least` and `at_most` in `parameters.json`): the value the result is at least with a probability of 95 %, and the one it is at most with that probability; for a normal spread, the mean less and plus 1.645 standard uncertainties, where the 95 % interval's ends lie 1.96 away and leave 2.5 % out on each side. `simulation.uncertainty.one_sided` gives another probability between 0.5 and 1, 0.9 say (`--one-sided` on the command line, **One-sided bounds** in the editor's simulation settings). The same draws give the spread of each listener's levels and speech results (`uncertainty.levels` in `parameters.json`, with the same parts): the sound pressure level per octave band and A-weighted, the STI, the STIPA, U50 and, outdoors, the level relative to free field. Each draw finds them for the source's sound power and the scene's background noise, and their rays' error comes from the same batches. A band's level is its G and the source's power, so its spread is G's; in a band whose G some draw leaves undefined, the level is that of the energy the response holds and has a spread of its own. `simulate` prints the A-weighted level's with the level it is at most and the STI's with the STI it is at least, and the editor's tips give the level's in each band. A coverage map gets the uncertainty of its values by tracing it again for each material (see [Coverage maps](coverage-maps.md#uncertainty)); a listener's insertion loss and long-term levels have no spread. ### Material libraries of CATT-Acoustic and ODEON Materials kept for CATT-Acoustic or ODEON can be used as they are. `file` names the library and `entry` the material in it: its name (in any case), or for ODEON its number or description. ```yaml materials: carpet: file: catt_materials.geo # CATT-Acoustic: ABS lines, in a geometry or library file entry: carpet ceiling_tiles: file: odeon_materials.li8 # ODEON: Material.Li8 or a library of the same layout entry: 1001 scattering: 0.1 ``` - CATT-Acoustic writes `ABS name = L {r g b}`: absorption and scattering in percent from 125 Hz to 4 kHz, 8 and 16 kHz optional (``), `;` before a comment; `ABS1` gives them as fractions from 0 to 1. `ABS name = other` gives a material another's values. Any file with such lines will do (a `.geo` file with its geometry, or a library). Scattering that CATT estimates itself (`L `) is not read, so give `scattering`. - ODEON's library has each material on two lines, its number and description, then eight absorption coefficients from 63 Hz to 8 kHz (six, from 125 Hz to 4 kHz, in older libraries). Where the description has ODEON's `{Product name*=...}` and `{Category=...}` fields, as in its own `Material.Li8`, the product name is the material's name, and `materials --file` lists the materials by category. Materials made with ODEON's Material calculator are read by their octave values, which ODEON simulates with; their third-octave values are not read. ODEON gives scattering to surfaces, so give it with `scattering` (0.1 otherwise). The 63 Hz band takes the 125 Hz value where a library has none, 8 kHz the 4 kHz value, and 16 kHz is left out. `acoustic-spaces materials --file ` lists a library's materials, with words to search for as in the built-in database, and in the editor **Edit > Add material from a library** picks one. The `material_libraries` example takes its carpet and walls from a CATT file and its ceiling from an ODEON one. Four rooms of the BRAS benchmark, converted from its SketchUp models, are in [`validation/bras`](https://github.com/naelolaiz/acoustic-spaces/blob/main/validation/bras) as scenes with their surface data and measurements (the coupled rooms twice, with the door between them at two angles). ## Walls, doors and openings A model can hold several rooms. Sound passes between them through surfaces whose material lets some through: `transmission`, the share that passes (1 for an opening), or `transmission_loss`, the sound reduction index R in dB (the share is 10^(-R/10)), one value or one per band. ```yaml materials: partition: # 12 cm of brick absorption: [0.02, 0.02, 0.03, 0.04, 0.05, 0.07, 0.07, 0.07] transmission_loss: [30, 35, 40, 46, 52, 57, 60, 60] door: absorption: [0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1] transmission_loss: 25 doorway: {transmission: 1} # an opening: all of it passes assignments: wall_between: partition door_leaf: door door_hole: doorway ``` - What passes through counts as absorbed on the side it comes from, so the absorption must be at least the transmission in every band. A material without absorption values, preset or file absorbs what it lets through: an opening absorbs 1. What a surface lets out of the rooms goes into no room and does not come back in through another: the late part's rays and the rain of their reflections stop there. - The rooms are found from the faces: every space the faces close off on all sides is one, whichever way the normals point. The space inside a thick wall or a column, with rooms all round it, is solid, as is the inside of a closed shell standing on the floor or in a corner, its faces lying on the room's. Such a solid holds air when a source or listener stands in it and a surface that lets sound through joins it to a room (a booth with glass walls), and so does any space it opens into that way; a source or listener inside any other solid is reported as inside a closed solid, and `simulate` refuses to run. When none stands in the model's rooms (walls drawn as a closed shell inside another), the spaces they stand in are the rooms. A material with `transmission: 0` lets nothing through. The faces between two rooms have a room on both sides and reflect and absorb in both. `inspect` lists the rooms ("closed, 2 rooms of 48.00, 72.00 m3"), the editor too, and the volume is theirs together. When the sources and listeners stand in air that the model's rooms do not include (walls drawn as a closed shell inside another), `inspect` also gives that "air volume", the one its reverberation times use. - Early reflections pass through those surfaces, keeping the share that passes at each; through openings they pass unchanged. A reflected path through more than two partitions is left to the late part, which with the stochastic method counts it (the statistical method takes what the early paths carry out of its own energy, so there the early part keeps any it finds). The rays of the late part that hit a partition go on as two: the reflection, and a copy behind it with the share that passes, so even a 60 dB wall has rays behind it. Each room's rays are thinned and split for the level that room is expected to reach (from the rooms' power balance in a diffuse field), so a quiet room behind a wall is traced as finely as the loud one. The detector spheres are sized for the volume of all the rooms, which the rays spread over: sized from the volume of a side room behind a 10 or 40 dB wall, they gave the same G, C80 and T30 there with half as much again spread between seeds. Sound goes straight through, in the direction it came. - Coverage maps cover the audience areas of every room and find at each point what a listener there would. The statistical late method follows coupled-room theory: each room's diffuse field decays as the energy the rooms exchange through the faces between them has it, with Eyring's absorption in each, so a room behind a partition holds less and a dry room opening into a live one decays in two slopes; the early paths end at the mixing time of the listener's room. The statistical reverberation times of `inspect` count each face between two rooms on both its sides, as for one room. - For diffraction an opening is a hole: the edges of a doorway are the free edges of the wall round it, and sound bends round them into the next room. Diffraction through a wall is left out, as it is far weaker than what passes straight through. - The wave solver lets its air flow through openings; it does not model walls that let part of the sound through, and says so. Particles in animations pass through openings, and through partitions as often as the sound does. - A listener in a room that no surface joins to the source's room is warned about. - In the editor, a material's **Lets through** chooses nothing, part of the sound (the sound reduction index per band in the table) or everything (an opening). The tests check the level behind a 30 and a 50 dB partition between two rooms against diffuse-field theory (within 0.3 dB), two rooms joined by an opening the size of the wall against one room of both their sizes, and the double-sloped decay of a dry room opening into a live one against the two-room model (within 1 dB down to -40 dB). The statistical method follows that model in both rooms, and maps over both rooms match listeners at their points. In four rooms in a row, the fourth room's response is the same whether the early part follows reflections to order 3 or not at all, and ray tracing finds the same early paths as image sources in every room. The `apartment` example has a wall and a door, closed or open, between the living room and the bedroom of a flat. ## Audience seating Sound that reaches a listener low over rows of seats loses much more than the seats' absorption says, as it passes heads and seat backs on the way. Mark the seating's material with `audience: true` (in the editor, **Audience seating**): ```yaml materials: seats: {preset: audience_wooden_chairs_1_m2, scattering: theatre_audience, audience: true} ``` - The attenuation is the fit of Jurkiewicz, Rummler, Green, Wulfrank and Kahle (["Impact of grazing incidence attenuation on early reflection design"](https://www.ioa.org.uk/system/files/publications/Y.%20Jurkiewicz%2C%20N.%20Rummler%20%2C%20E.%20Green%20%2C%20T.%20Wulfrank%20and%20E.%20Kahle%20IMPACT%20OF%20GRAZING%20INCIDENCE%20ATTENUATION%20ON%20EARLY%20REFLECTION%20DESIGN.pdf), Proc. IOA 47 Pt. 1, 2025) to scale-model measurements over a seated audience: sound arriving at an elevation φ above the audience, having run d metres over it, keeps min(1, (3.40 sin²φ + 2.17 sin φ + 0.02)^((d - 1)/10)) of its energy. That is 17 dB less at grazing incidence after 11 m, 0.6 dB per metre at 5°, and nothing lost from 17.8° up. - It applies to the last leg of every early path (the direct sound, reflections and diffracted sound) to listeners and map points up to 2 m above audience surfaces: φ is the leg's elevation above the surface under the listener, and d how far the leg runs over audience surfaces no more than 2 m higher than the listener's ears are above theirs, so the stalls do not shade a balcony seat. - Only in the 500 Hz to 2 kHz octaves (third octaves from 400 Hz to 2.5 kHz), the bands of the fit, where it hardly changed with frequency. The seat dip lower down depends on the seats themselves, and the fit has no data higher up. The late part is left as it is, and the statistical method does not make up what the seats take from the early paths. Leaving out the leg from the source to the first reflection, as the fit does, errs on the side of too little attenuation. - In a flat lecture hall with the talker at 1.6 m, it takes 10 dB off the direct sound at the back row in those bands and 1.3 dB off C50 there. The `town_hall_pa` example marks its seats as audience. ## Sources and directivity A source has a position, an orientation (`yaw`, `pitch` and `roll` in degrees; all zero faces +x with +z up), a sound power level (`level_db`, dB re 1 pW) and a `directivity`: ```yaml sources: - name: talker position: [2.0, 3.0, 1.5] orientation: {yaw: 30} directivity: cardioid # or omni, subcardioid, supercardioid, hypercardioid, figure8 - name: monitor position: [0.7, 1.3, 1.2] directivity: # a pattern, or the a of a + (1 - a) cos(theta), per octave band pattern: [omni, omni, omni, subcardioid, subcardioid, cardioid, cardioid, 0.3] - name: loudspeaker position: [0.7, 3.3, 1.2] directivity: {file: speaker.sofa} # measured data: SOFA or CSV ``` - A directivity says where the sound power goes, not how much: its weights average 1 over the sphere in every band. It shapes the direct sound, each early path (by the direction it leaves the source in), the rays of the late part and the particles of `animate`. - **SOFA** files follow the AES69 `FreeFieldDirectivityTF` convention (spectra measured by microphones around the source, as published for loudspeakers and instruments), or hold impulse responses in `Data.IR`. Directions are the microphones' positions as the source sees them (`SourceView` and `SourceUp`). `measurement: 3` picks one measurement, for example one note of an instrument; by default all are averaged. Reading SOFA files needs the `sofa` extra (h5py). - A **CSV** table has the header `azimuth, elevation` followed by frequencies in Hz, then one row per direction with levels in dB (any reference; only differences matter). Azimuth turns from the front towards the source's left and elevation is positive upwards, in degrees. Any set of directions works. Bands are averaged into octaves, and octaves with no data copy the nearest one; in third-octave runs each octave's pattern holds for its thirds. From Python, `acoustic_spaces.directivity.write_directivity_csv(path, balloon)` writes a directivity (a `Balloon`) as such a table, its octave bands on its grid. - The directions of a SOFA or CSV file are interpolated onto a 5 degree grid, each of its points from the four directions nearest to it, or from all of them where the file has fewer. Where several are equally near and not all of them are among the four, the point takes the nearer ones alone, or all of them if none is nearer. A direction given more than once (a table's -180 and 180 degrees of azimuth, its rows straight up and down) counts once, with the mean of its energies. - CLF (Common Loudspeaker Format) files are not read: their specification is not public. Convert them to SOFA or CSV. `acoustic-spaces directivity speaker.sofa --plot polar.png` prints the directivity index and front-to-back ratio per octave band and draws the polar patterns; `acoustic-spaces inspect` lists every source's directivity index. A coherent array, such as a column loudspeaker or a line array, is a source whose directivity is the sum of its elements' sound with its phase: ```yaml sources: - name: column position: [0.5, 3.0, 2.0] directivity: array: element: cardioid # each element's pattern, along its aim (default omni) count: 8 # a straight column along the up axis, centred... spacing_m: 0.15 # ...and this far apart steer_deg: -8 # delays that tilt the beam 8 degrees down - name: flown position: [6.0, 3.0, 6.0] directivity: {file: line_array.yaml} # the same fields in a YAML file ``` ```yaml # line_array.yaml: elements one by one, in the source's frame (x forward, y left, z up) element: {file: cabinet.sofa} # or a pattern, as for a source elements: - {position: [0, 0, 0.0], orientation: {pitch: 0}} - {position: [0, 0, -0.35], orientation: {pitch: -3}, gain_db: -1, delay_ms: 0.05} - {position: [-0.02, 0, -0.70], orientation: {pitch: -7}, gain_db: -2} - {position: [0, 0, -1.05], invert: true} # polarity inverted ``` - The elements' pressures add up with their path differences, their feeds' gains, delays and polarities, the steering, and each element's pattern along its aim (first-order patterns with their sign, measured ones by magnitude). The energy is the exact mean over each third-octave band, on a grid of 1 to 5 degrees fine enough for the beam, and with the room's speed of sound. A column of 8 takes about a second. - The result is the array's **far-field** pattern, a balloon like a measured one, so the source stays one point: right beyond about the array's length squared over the wavelength, L² f / c (16 m for a 2 m array at 1.4 kHz). Closer to a long array, its sound spreads as a line's and its beam has not formed yet. The room's warnings name every listener nearer to an array than that distance at 1 kHz: `validate`, `inspect`, `simulate` and `map` print them, and the editor lists them under **Properties** when the scene itself is selected. Higher up the far field starts farther still: | array length | far field from, at 1 kHz | at 4 kHz | |---|---|---| | 0.5 m | 0.7 m | 2.9 m | | 1 m | 2.9 m | 11.7 m | | 2 m | 11.7 m | 46.6 m | - `near_field: true` (next to `array` or `file`) adds up the elements' sound one by one instead, each from where it is, with its own distance, direction, feed and pattern, wherever an early path leaves the array: the direct sound and the reflections (from the image of the listener the path unfolds to), the ground's reflection and refracted rays outdoors, and the sound that reaches an edge or a crest before it bends round it. It is exact over each band as the pattern is, becomes the pattern far away, and the warnings leave the array out. The late reverberation keeps the pattern, which carries the same power. In the editor it is "Add up the array's elements one by one" under the source's directivity. ```yaml directivity: {file: line_array.yaml, near_field: true} ``` A 3.75 m column loses about 3 dB per doubling of the distance on axis within its far field's start, as a line does, and 6 dB beyond it, as a point does. - As for any source, `level_db` is the array's sound power in all; the pattern only says where it goes. A single element's array has the element's own pattern. - The tests check a column against the analytic sums of a line array (the directivity index within 0.05 dB in every band, the vertical pattern within 0.3 dB), steering against delays given element by element, a dipole made of two elements in opposite polarity, and splayed cardioids against their exact sum. - In the editor, pick the YAML file with "Measured data or an array from a file…"; `acoustic-spaces directivity line_array.yaml --plot polar.png` shows its pattern. How loud a source is, and how it is fed: ```yaml sources: - name: talker position: [2.0, 3.0, 1.5] level_db: 78 # sound power in all, dB re 1 pW spectrum: speech_male # or flat (default) or speech_female - name: delay-speaker position: [12.0, 3.0, 2.5] level_db: [95, 98, 100, 100, 100, 99, 97, 92] # or per band (8 or 24 values) gain_db: -6 # gain of the feed eq_db: [0, 0, -3, 0, 0, 0, 2, 4] # equalizer per band, dB delay_ms: 18.5 # plays this long after emission starts signal: sounds/announcement.wav # what it plays in a demo of the scene channel: mono # of it: left, right or mono (both mixed down) ``` The scene's `recording` is what its sources with a `channel` and no `signal` play, so a stage's loudspeakers play the two channels of a band's stereo master: ```yaml recording: spicy_funk_cake # a free song, downloaded the first time; or a file sources: - {name: house_left, position: [0, 6, 6], channel: left} # on the audience's left - {name: house_right, position: [0, -6, 6], channel: right} - {name: subs, position: [0, 0, 0.5], channel: mono} ``` - `level_db` is the sound power level, in all or per band. A level in all is spread by `spectrum`: evenly over the octave bands (`flat`), or as the long-term spectrum of male or female speech (IEC 60268-16), for which the STI then takes the male or female weighting. The standard's normal voice, 60 dB(A) at 1 m, is about 78 dB of sound power with either speech spectrum and an omnidirectional source. It gives no level at 63 Hz, nor at 125 Hz for female speech; those bands are taken 12 dB below the next one up, an assumption that does not reach the STI. - `gain_db` and `eq_db` are the gain and equalizer of the source's feed. Both act on the sound power and on the impulse responses, so a mix made with `auralize` hears them. G stays the room's: it is measured against the same source, fed the same way, in free field. The impulse responses are per unit of sound power, and `auralize` scales each source's signal by its `level_db` against the loudest source's, so a mix keeps the balance between sources of different power too. - `delay_ms` delays everything the source sends. Its impulse responses start that much later, and in the coverage map of all sources together its sound arrives that much later, as when delay loudspeakers are aligned with a stage. - `signal` is the file the source plays in a demo of the scene (`acoustic-spaces demo`, see [a demo of any scene](demos.md#a-demo-of-any-scene)): a dry recording, relative to the scene's folder, played at the source's sound power. A WAV file is read as it is; another format (FLAC, MP3, M4A...) needs ffmpeg on the PATH. `channel` picks what of it the source plays: `left`, `right`, or `mono`, both mixed down; without a channel it is mixed down to mono. - The scene's `recording` is the file a source with a `channel` and no `signal` plays: a file relative to the scene's folder, or the name of one of the free recordings (`spicy_funk_cake`, `great_british_summer`, `potassium`, `speech_male`, `speech_female`; see [a demo of any scene](demos.md#a-demo-of-any-scene)), which the demo downloads the first time and keeps for every scene. A name without a suffix must be a free recording's or a file that is there, so a mistyped free name is refused. Left and right are the recording's, so the loudspeaker on the audience's left plays `left`. A source with neither a signal nor a channel is silent in the demo. The simulation reads neither. - `simulate` reports the sound pressure level per octave band and A-weighted (`spl_db` and `spl_a_db` in `parameters.json`), the editor's results show it per band, and `inspect` lists each source's sound power. In a band whose G is undefined, the level is that of the energy the response holds, as for the [pass-by levels](spatial-audio.md#moving-sources-and-doppler), and null where no sound arrives. In free field, the level 4 m from a source comes out as its sound power less 10 log10(4 π r²) = 23 dB and the air's absorption over the 4 m, to within 0.01 dB. The `town_hall_pa` example feeds two delay loudspeakers with their own gain, equalizer and delay, behind two columns that are coherent arrays. Line and surface sources, such as a road, a row of loudspeakers fed alike, a choir or a vibrating wall: ```yaml sources: - name: traffic position: [0.0, 20.0, 0.5] orientation: {yaw: 90} # the line runs along the source's left axis: here -x line_m: 40 - name: panel position: [6.0, 0.05, 1.5] orientation: {yaw: 90} # facing +y, into the room surface_m: [2.0, 1.2] # width along the left axis, height along the up axis spacing_m: 0.25 # at most this far apart (default 0.5 m) directivity: lambert # a vibrating surface's: in proportion to the cosine ``` - A line or surface is made of uncorrelated point sources, at most `spacing_m` apart, each in the middle of an equal share of it. They share the source's sound power and its rays equally, each with a seed of its own, and keep its directivity, orientation and feed. A source is made of at most 400 of them; their sound adds up in energy, as for incoherent sources such as traffic or a crowd. Close to a long line, the level falls about 3 dB per doubling of distance rather than a point source's 6 dB (3.3 dB between 2 and 4 m from a 40 m line in the tests). - `lambert` radiates as a vibrating surface, in proportion to the cosine of the angle to the forward axis and nothing behind (a directivity index of 6 dB). - All of a line or surface must be inside the room; `inspect` lists its length or size and its number of points. The wave solver takes point sources only. The editor draws lines and surfaces in the 3D view and the plan, and the Blender export has them too. The `workshop` example maps the noise of a conveyor (a line), a machine's casing (a surface) and a compressor (a point). ![Polar patterns of the per-band directivity above, from omni in the bass to a narrow pattern at 8 kHz](images/directivity.png) ### Groups, and sources left out Sources and listeners can sit in groups, and can be left out of a run without being removed: ```yaml sources: - name: main_left group: PA/Mains # the group Mains in the group PA position: [-40, 19, 14] - name: vocal_wedges group: Monitors enabled: false # left out of simulations, maps and checks position: [-43.3, 0, 2.25] listeners: - name: singer group: Stage position: [-44.8, 0, 3.7] ``` - `group` sorts the scene tree of the editor; groups nest with `/`, and a source and a listener may share a group's name. It changes no result. - `enabled: false` leaves a source or listener out of `simulate`, `map`, `walk` (the sources that do not walk) and the scene's checks, as if it were not there, but keeps it in the scene; the others get the same responses as in a run of all, since seeds follow the scene's order. Named on the command line (`--source`), it is simulated all the same, and checked. `inspect` marks it "left out". With every source, or every listener, left out, `validate`, `pack`, `simulate` and the editor refuse the scene, as there is nothing to run (a map needs no listener). - In the editor's scene tree each source, listener and group has a tick (in simulations or left out, saved as `enabled: false`) and an eye that shows or hides it in the 3D view and the plan. Hiding is how the editor shows the scene, not part of it: it is not saved and changes no result. Sources and listeners left out start hidden, and an eye follows its tick when that changes; shown by their eye, they are drawn faded. ## Walks A listener or a point source can walk through the room, for [walkthroughs](spatial-audio.md#walkthroughs): ```yaml listeners: - name: visitor position: [17.0, 4.0, 1.6] # where the walk starts walk: to: [[4.0, 4.0, 1.6], [4.0, 16.0, 1.6]] # the corners it goes through speed_m_s: 1.2 # walking pace (default 1.2 m/s) face_forward: true # turn to face the way it goes (default); false keeps its yaw turn_deg_s: 90 # how fast it turns through a corner (default 90 degrees/s) doppler: false # pitch shifts as it goes: cars, trains (default false) ``` - A walk goes in straight lines from the position through each point of `to`, at an even pace, and stops at the last one. Facing forward sets the yaw along each leg and keeps the pitch and roll; on a leg straight up or down the yaw stays as it was. At a corner the walker turns the shorter way round at `turn_deg_s`, half of the turn before the corner and half after it (no further than half-way along either leg), so a sound to one side moves round the head instead of jumping. - `doppler: true` plays the early sound through delays that change as the walker goes, so that its pitch shifts: for vehicles and aircraft, which go faster than anyone walks (see [Moving sources and Doppler](spatial-audio.md#moving-sources-and-doppler)). It needs a speed below the speed of sound and no wave solver. - Everything else (`simulate`, `map`, the editor) sees the walker standing where its walk starts; `inspect` lists how far each walk goes and for how long. Lines and surfaces do not walk. A walk may instead be timed, through `keyframes`: ```yaml sources: - name: speaker position: [2.0, 3.0, 1.7] # where it is at 0 s orientation: {yaw: 0} # and how it faces then walk: keyframes: - {time_s: 4.0, position: [6.0, 3.0, 1.7]} # 1 m/s, facing as before - {time_s: 6.0, position: [6.0, 3.0, 1.7], orientation: {yaw: 90}} # turns on the spot - {time_s: 10.0, position: [6.0, 7.0, 1.7]} # on, facing +y enabled: true # false keeps the walk but leaves it standing (default true) ``` - Each keyframe says where the walker is at `time_s` (seconds from the start, in order, each later than the last) and, if given, how it faces there. Between two keyframes it moves and turns evenly, so each leg's speed is its distance over its time: it can wait, turn on the spot, or go at any pace. A keyframe without an `orientation` keeps the facing of the one before (at first, the walker's own); the keyframes say how it faces, so `face_forward` and `turn_deg_s` do not apply. A turn goes the shorter way round. - `enabled: false` keeps a walk, of either kind, but leaves its walker standing still: `walkthrough --all` and the editor's movement leave it out, and `walkthrough` picks the one walk that is enabled. Giving it by name (`--walker`) is refused. - Several listeners and sources may each have a walk; `walkthrough --all` plays them all together on one clock (see [Walkthroughs](spatial-audio.md#walkthroughs)). The editor's Movement panel edits keyframes in a table and along a timeline (see [Graphical editor](editor.md)). ## Air, response length and seed ```yaml air: temperature_c: 20 # default 20 °C humidity_percent: 50 # default 50 % pressure_kpa: 101.325 # default 101.325 kPa simulation: ir_length_s: 2.0 # length of the impulse responses (s), default 2 sample_rate: 48000 # of the impulse responses (Hz), default 48000 seed: 1 # random seed, 0 or more; unset, every run draws its own insertion_loss_of: [noise_barrier] # outdoors: run again without these parts ``` - `air` sets the speed of sound and the air absorption per band (ISO 9613-1), for the rays, the wave solver and the statistical reverberation times alike. ISO 9613-1:1993 states the absorption's accuracy (±10 % to ±50 %, as the humidity goes) for any humidity and temperature a scene takes, but only for frequency over pressure from 0.0004 to 10 Hz/Pa: a pressure outside 0.794 to 157.7 kPa in octave bands (1 to 125.3 kPa in third-octave bands) is warned about. Outdoors, `temperature_c` is the temperature at the ground, and an `atmosphere` changes it with height (see [Wind and temperature](outdoor.md#wind-and-temperature)). - Outdoors, `ir_length_s` counts from the latest direct sound of the run, as sources and listeners can stand far apart (see [Outdoor scenes](outdoor.md#what-the-simulation-does-outdoors)). - A response that ends before the room has decayed is extended by its fitted decay rate when the parameters are computed (see [Simulation](simulation.md)); a longer `ir_length_s` makes longer files, and more time steps for the wave solver. `--sample-rate` on the command line overrides `sample_rate` for one run. - With a `seed`, the late rays, the scattering and the coverage maps draw the same random numbers every run, so a scene's results repeat from run to run (`--seed` sets it for one run). A GPU draws random numbers of its own, and its results can vary slightly from run to run, as do those of the CPU and a GPU sharing the rays (see [The late stage on a GPU](simulation.md#the-late-stage-on-a-gpu)). The editor's **Simulation** entry has these under **Response**, and the scene's own entry the air. - Outdoors, `insertion_loss_of` names buildings, barriers or vegetation to run the scene again without, for their insertion loss (see [Results outdoors](outdoor.md#results-outdoors)); `--without` on the command line overrides it for one run, and the editor's **Simulation** entry lists the parts to tick.