Skip to content

materials.diffusers.reverberation_room_scattering

Random-incidence scattering coefficient in a reverberation room.

ISO 17497-1:2004+A1:2014. Four reverberation times (Table 2) taken with and without the test sample, with a static and a rotating turntable, give two Sabine-form absorption coefficients: the random-incidence absorption coefficient alpha_s (Clause 8.1.1, Eq. (1)) and the specular absorption coefficient alpha_spec (Clause 8.1.2, Eq. (4)). Their ratio yields the scattering coefficient (Clause 8.1.3, Eq. (5)). The turntable base plate is qualified through its own scattering coefficient (Clause 8.1.4, Eq. (6)) against the Table 1 limits (Clause 6.2). Air properties come from the speed-of-sound and energy-attenuation relations of Clause 8 (Eqs. (2)/(3), after ISO 9613-1; Eq. (3) is the conversion ISO 354 makes too, so it is power_attenuation_from_alpha, shared with the absorption measurement), and measurement accuracy from Annex A (Eqs. (A.1)-(A.5)).

One subject: everything the reverberation-room method needs, from the four measured decay times to the scattering coefficient and its uncertainty. Part 2 of ISO 17497 is a different measurement in a free field and lives in phonometry.materials.diffusers.scattering_diffusion; the two parts share no formula, and the helpers are named per part so they are never mixed. Neither part contains a numeric worked example.

Auto-generated from the source docstrings by scripts/generate_api_docs.py (make api-docs). Do not edit by hand.

absorption_coefficient_uncertainty(
volume: float,
area: float,
*,
speed_of_sound: NumericArrayLike,
t_a: NumericArrayLike,
u_a: NumericArrayLike,
t_b: NumericArrayLike,
u_b: NumericArrayLike,
) -> float | NDArray[np.float64]

Uncertainty of a Sabine absorption coefficient (ISO 17497-1, A.3/A.4).

With situations (t1, t2) this is u(alpha_s) (Eq. (A.3)); with (t3, t4) it is u(alpha_spec) (Eq. (A.4)). The unsubscripted c of the standard is taken as a single (mean) speed of sound.

Parameters

Name Description
volume Reverberation-room volume V, in cubic metres.
area Test-sample area S, in square metres.
speed_of_sound Speed of sound c, in m/s.
t_a Reverberation time of the first situation, in seconds.
u_a Standard uncertainty of t_a (Eq. (A.1)), in seconds.
t_b Reverberation time of the second situation, in seconds.
u_b Standard uncertainty of t_b (Eq. (A.1)), in seconds.

Returns: Combined standard uncertainty of the absorption coefficient (per band). A float when speed_of_sound, t_a, u_a, t_b and u_b are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for non-positive V, S, c or T.
TypeError if area or volume is not a single number, or speed_of_sound, t_a, t_b, u_a or u_b holds a text or a value that is not a real number.

Constant (tuple).

BASE_PLATE_BANDS_HZ = (100, 125, 160, 200, 250, 315, 400, 500, 630, 800, 1000, 1250, 1600, 2000, 2500, 3150, 4000, 5000)

Constant (mapping).

BASE_PLATE_MAX_SCATTERING = {100: 0.05, 125: 0.05, 160: 0.05, 200: 0.05, 250: 0.05, 315: 0.05, 400: 0.05, 500: 0.05, 630: 0.1, 800: 0.1, 1000: 0.1, 1250: 0.15, 1600: 0.15, 2000: 0.15, 2500: 0.2, 3150: 0.2, 4000: 0.2, 5000: 0.25}
base_plate_scattering(
volume: float,
area: float,
*,
c1: NumericArrayLike,
t1: NumericArrayLike,
c3: NumericArrayLike,
t3: NumericArrayLike,
m1: NumericArrayLike = 0.0,
m3: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Scattering coefficient of the base plate alone (ISO 17497-1, Eq. (6)).

Ideally ; a slightly non-symmetrical base plate shortens t3 and this quality metric captures the resulting spurious scattering, which must not exceed the Table 1 limits (Clause 6.2). See check_base_plate_scattering.

Parameters

Name Description
volume Reverberation-room volume V, in cubic metres.
area Test-sample area S, in square metres.
c1 Speed of sound during t1, in m/s.
t1 Reverberation time with the static base plate, in seconds.
c3 Speed of sound during t3, in m/s.
t3 Reverberation time with the rotating base plate, in seconds.
m1 Energy attenuation coefficient during t1, in 1/m; defaults to 0.
m3 Energy attenuation coefficient during t3, in 1/m; defaults to 0.

Returns: Base-plate scattering coefficient s_base (per band). A float when c1, t1, c3, t3, m1 and m3 are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for non-positive V, S, c or T.
TypeError if area or volume is not a single number, or c1, t1, m1, c3, t3 or m3 holds a text or a value that is not a real number.
BasePlateScatteringCheck(
frequencies: NDArray[np.float64],
scattering: NDArray[np.float64],
)

The scattering of the base plate alone against Table 1 (ISO 17497-1, 6.2).

6.2 has the scattering coefficient of the base plate alone, worked by 8.1.4 (base_plate_scattering), measured to check the quality of the arrangement, and says the values of Table 1 “shall not be exceeded”. The limits are the table’s, so they are read from the bands and are not fields: a check cannot be built against other limits, nor on bands the table does not list.

Attributes

Name Description
frequencies The eighteen one-third-octave bands of Table 1, BASE_PLATE_BANDS_HZ, in hertz (equivalent full scale).
scattering in each band, dimensionless.

BasePlateScatteringCheck.exceeded_frequencies

Section titled “BasePlateScatteringCheck.exceeded_frequencies”

property

The bands over their limit, in hertz, in ascending order.

property

Whether each band is over its limit; at the limit is not over it.

property

The largest Table 1 allows in each band.

property

The limit less the measured coefficient in each band, settled.

Positive or zero inside the limit, negative over it, judged to nine decimals so a coefficient worked out to the printed limit in decimal is not taken past it by the last bits.

property

The verdict: no band exceeds its Table 1 limit.

BasePlateScatteringCheck.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Draw against the stepped limit of Table 1.

Requires matplotlib (the [plot] extra).

Parameters

Name Description
ax Existing axes, or None to create a figure.
language Label language, "en" (default) or "es".
kwargs Forwarded to the measured coefficient curve.

Returns: The axes, with the bands over the limit marked.

check_base_plate_scattering(
scattering: Mapping[Any, float] | Sequence[float] | NumericArrayLike,
) -> BasePlateScatteringCheck

Is the base plate good enough for the measurement? (ISO 17497-1, 6.2).

The scattering coefficient of the base plate alone, from base_plate_scattering, is held to the BASE_PLATE_MAX_SCATTERING limit of each band of Table 1. A single ScatteringDiffusionWarning names the bands over the limit, when there are any.

Parameters

Name Description
scattering Measured base-plate scattering coefficients, either a mapping keyed by one-third-octave centre frequency (Hz) or a sequence of 18 values ordered as BASE_PLATE_BANDS_HZ.

Returns: The verdict, as a BasePlateScatteringCheck; the bands over the limit are its exceeded_frequencies.

Raises

Exception When
ValueError for a mapping missing a band, a sequence of the wrong length, or a coefficient that is not finite (NaN or infinite).
TypeError if scattering holds a text or a value that is not a real number.
random_incidence_absorption(
volume: float,
area: float,
*,
c1: NumericArrayLike,
t1: NumericArrayLike,
c2: NumericArrayLike,
t2: NumericArrayLike,
m1: NumericArrayLike = 0.0,
m2: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Random-incidence absorption coefficient alpha_s (ISO 17497-1, Eq. (1)).

Situation 1 is the empty room with the (static) base plate present; situation 2 adds the test sample, still without turntable rotation (Table 2, rows t1 and t2).

Parameters

Name Description
volume Reverberation-room volume V, in cubic metres.
area Test-sample area S, in square metres.
c1 Speed of sound during t1, in m/s (see speed_of_sound_iso17497).
t1 Reverberation time without sample (base plate only), in seconds.
c2 Speed of sound during t2, in m/s.
t2 Reverberation time with the test sample, in seconds.
m1 Energy attenuation coefficient during t1, in 1/m (see power_attenuation_from_alpha); defaults to 0.
m2 Energy attenuation coefficient during t2, in 1/m; defaults to 0.

Returns: Random-incidence absorption coefficient alpha_s (per band). A float when c1, t1, c2, t2, m1 and m2 are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for non-positive V, S, c or T.
TypeError if area or volume is not a single number, or c1, t1, m1, c2, t2 or m2 holds a text or a value that is not a real number.
reverberation_time_uncertainty(times: NumericArrayLike) -> float

Standard uncertainty of a reverberation time (ISO 17497-1, Eq. (A.1)).

with the mean of the N spatially-averaged measurements (Eq. (A.2)); this is the standard error of the mean.

Parameters

Name Description
times The reverberation-time measurements, in seconds.

Returns: Standard uncertainty u of the mean reverberation time, in seconds, a float: the measurements are one axis, which it reduces.

Raises

Exception When
ValueError if fewer than two measurements are supplied.
TypeError if times holds a text or a value that is not a real number.
scattering_coefficient(
alpha_spec: float | np.floating[Any] | np.integer[Any],
alpha_s: float | np.floating[Any] | np.integer[Any],
*,
truncate_negative: bool = ...,
) -> float
scattering_coefficient(
alpha_spec: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
alpha_s: NumericArrayLike,
*,
truncate_negative: bool = ...,
) -> NDArray[np.float64]
scattering_coefficient(
alpha_spec: float | np.floating[Any] | np.integer[Any],
alpha_s: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
truncate_negative: bool = ...,
) -> NDArray[np.float64]
scattering_coefficient(
alpha_spec: NumericArrayLike,
alpha_s: NumericArrayLike,
*,
truncate_negative: bool = ...,
) -> float | NDArray[np.float64]

Random-incidence scattering coefficient s (ISO 17497-1, Eq. (5)).

Following the presentation rule of Clause 8.3, negative results are truncated to 0 while values greater than 1 (which can occur through edge effects, Clause 6.3.2) are kept and reported. Rounding to 0.01 for a results table is left to the caller.

Parameters

Name Description
alpha_spec Specular absorption coefficient alpha_spec (Eq. (4)).
alpha_s Random-incidence absorption coefficient alpha_s (Eq. (1)).
truncate_negative If True (default), clip negative s to 0 per Clause 8.3; values above 1 are never clipped.

Returns: Scattering coefficient s (per band). A float when alpha_spec and alpha_s are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any alpha_s equals 1 (undefined ratio).
TypeError if alpha_s or alpha_spec holds a text or a value that is not a real number.
scattering_coefficient_spectrum(
specular_absorption: NumericArrayLike,
random_absorption: NumericArrayLike,
*,
frequencies: NumericArrayLike,
truncate_negative: bool = True,
) -> ScatteringResult

Scattering-coefficient spectrum s(f) (ISO 17497-1, Eq. (5)).

Convenience wrapper over scattering_coefficient that pairs the per-band specular alpha_spec (Eq. (4)) and random-incidence alpha_s (Eq. (1)) absorptions with their band centres and returns a plottable ScatteringResult.

Parameters

Name Description
frequencies One-third-octave band centres, in hertz (1-D).
specular_absorption Specular absorption alpha_spec per band.
random_absorption Random-incidence absorption alpha_s per band.
truncate_negative Clip negative s to 0 (Clause 8.3 default).

Returns: A ScatteringResult with .plot().

Raises

Exception When
ValueError if the three inputs differ in shape, the band centres are empty or not 1-D, or any alpha_s equals 1.
TypeError if frequencies, random_absorption or specular_absorption holds a text or a value that is not a real number.
scattering_coefficient_uncertainty(
alpha_spec: NumericArrayLike,
alpha_s: NumericArrayLike,
u_alpha_spec: NumericArrayLike,
u_alpha_s: NumericArrayLike,
) -> ScatteringUncertainty

Uncertainty of the scattering coefficient (ISO 17497-1, Eq. (A.5)).

with the expanded uncertainty (95 % confidence).

Parameters

Name Description
alpha_spec Specular absorption coefficient alpha_spec (Eq. (4)).
alpha_s Random-incidence absorption coefficient alpha_s (Eq. (1)).
u_alpha_spec Standard uncertainty of alpha_spec (Eq. (A.4)).
u_alpha_s Standard uncertainty of alpha_s (Eq. (A.3)).

Returns: A ScatteringUncertainty with u_s and .

Raises

Exception When
ValueError if any alpha_s equals 1 or any alpha_spec equals 1.
TypeError if alpha_s, alpha_spec, u_alpha_s or u_alpha_spec holds a text or a value that is not a real number.

Advisory for out-of-range scattering/diffusion measurement conditions.

ScatteringResult(
frequencies: NDArray[np.float64],
scattering: NDArray[np.float64],
random_incidence: NDArray[np.float64],
specular: NDArray[np.float64],
)

A random-incidence scattering-coefficient spectrum (ISO 17497-1).

Attributes

Name Description
frequencies One-third-octave band centre frequencies, in hertz.
scattering Scattering coefficient s per band (Eq. (5)).
random_incidence Random-incidence absorption alpha_s (Eq. (1)).
specular Specular absorption alpha_spec (Eq. (4)).
ScatteringResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the scattering coefficient s versus frequency.

Requires matplotlib (the [plot] extra); returns the Axes and never calls plt.show.

Parameters

Name Description
language The language of the labels: "en" or "es".
ScatteringResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render an ISO 17497-1 scattering-coefficient test-report fiche to a PDF.

Writes a one-page accredited random-incidence scattering report (ISO 17497-1:2004+A1:2014): the standard-basis line, an optional metadata header block (client, specimen, test room, sample area S, temperature, humidity …), a two-panel body with the per-band table (frequency, the random-incidence absorption alpha_s and the scattering coefficient s) beside the s(f) curve on a categorical band axis, and a footer with the fixed disclaimer. ISO 17497-1 is a characterisation, so there is no pass/fail verdict and no single-number rating.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a body-and-disclaimer fiche whose header shows only the measured frequency range. The applicable descriptive fields are client, manufacturer, specimen, area, room_volume, mounting, test_room, test_date, temperature_c, relative_humidity_percent, pressure, measurement_standard, laboratory, operator, report_id and notes. The requirement field is ignored (ISO 17497-1 has no verdict).
engine Rendering back end; only "reportlab" is supported.
verbose When True, the value table inserts the specular absorption alpha_spec column beside alpha_s and s.
language Fiche language: "en" (default, English, decimal point) or "es" (Spanish, decimal comma).

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab".
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).
ScatteringUncertainty(
u_scattering: NDArray[np.float64],
expanded: NDArray[np.float64],
)

Uncertainty of the scattering coefficient (ISO 17497-1, Annex A).

Attributes

Name Description
u_scattering Combined standard uncertainty u_s of the scattering coefficient (Eq. (A.5)).
expanded Expanded uncertainty at 95 % confidence (Annex A).
specular_absorption_coefficient(
volume: float,
area: float,
*,
c3: NumericArrayLike,
t3: NumericArrayLike,
c4: NumericArrayLike,
t4: NumericArrayLike,
m3: NumericArrayLike = 0.0,
m4: NumericArrayLike = 0.0,
) -> float | NDArray[np.float64]

Specular absorption coefficient alpha_spec (ISO 17497-1, Eq. (4)).

Situation 3 is the rotating base plate without the sample; situation 4 is the sample on the rotating turntable (Table 2, rows t3 and t4). The apparent (specular) absorption includes the energy lost to scattering.

Parameters

Name Description
volume Reverberation-room volume V, in cubic metres.
area Test-sample area S, in square metres.
c3 Speed of sound during t3, in m/s.
t3 Reverberation time, rotating base plate without sample, in seconds.
c4 Speed of sound during t4, in m/s.
t4 Reverberation time, sample on the rotating turntable, in seconds.
m3 Energy attenuation coefficient during t3, in 1/m; defaults to 0.
m4 Energy attenuation coefficient during t4, in 1/m; defaults to 0.

Returns: Specular absorption coefficient alpha_spec (per band). A float when c3, t3, c4, t4, m3 and m4 are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError for non-positive V, S, c or T.
TypeError if area or volume is not a single number, or c3, t3, m3, c4, t4 or m4 holds a text or a value that is not a real number.
speed_of_sound_iso17497(
*,
temperature_c: float | np.floating[Any] | np.integer[Any],
) -> float
speed_of_sound_iso17497(
*,
temperature_c: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
speed_of_sound_iso17497(
*,
temperature_c: NumericArrayLike,
) -> float | NDArray[np.float64]

Speed of sound in air (ISO 17497-1:2004, Clause 8, Eq. (2)).

(m/s).

Parameters

Name Description
temperature_c Air temperature, in degrees Celsius (scalar or per band).

Returns: Speed of sound c, in metres per second. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any temperature is at or below -273.15 degC.
TypeError if temperature_c holds a text or a value that is not a real number.