materials.diffusers.reverberation_room_scattering
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
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
Section titled “absorption_coefficient_uncertainty”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. |
BASE_PLATE_BANDS_HZ
Section titled “BASE_PLATE_BANDS_HZ”Constant (tuple).
BASE_PLATE_BANDS_HZ = (100, 125, 160, 200, 250, 315, 400, 500, 630, 800, 1000, 1250, 1600, 2000, 2500, 3150, 4000, 5000)BASE_PLATE_MAX_SCATTERING
Section titled “BASE_PLATE_MAX_SCATTERING”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
Section titled “base_plate_scattering”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
Section titled “BasePlateScatteringCheck”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.
BasePlateScatteringCheck.exceeds
Section titled “BasePlateScatteringCheck.exceeds”property
Whether each band is over its limit; at the limit is not over it.
BasePlateScatteringCheck.limits
Section titled “BasePlateScatteringCheck.limits”property
The largest Table 1 allows in each band.
BasePlateScatteringCheck.margins
Section titled “BasePlateScatteringCheck.margins”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.
BasePlateScatteringCheck.passes
Section titled “BasePlateScatteringCheck.passes”property
The verdict: no band exceeds its Table 1 limit.
BasePlateScatteringCheck.plot()
Section titled “BasePlateScatteringCheck.plot()”BasePlateScatteringCheck.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesDraw 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
Section titled “check_base_plate_scattering”check_base_plate_scattering( scattering: Mapping[Any, float] | Sequence[float] | NumericArrayLike,) -> BasePlateScatteringCheckIs 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
Section titled “random_incidence_absorption”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
Section titled “reverberation_time_uncertainty”reverberation_time_uncertainty(times: NumericArrayLike) -> floatStandard 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
Section titled “scattering_coefficient”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
Section titled “scattering_coefficient_spectrum”scattering_coefficient_spectrum( specular_absorption: NumericArrayLike, random_absorption: NumericArrayLike, *, frequencies: NumericArrayLike, truncate_negative: bool = True,) -> ScatteringResultScattering-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
Section titled “scattering_coefficient_uncertainty”scattering_coefficient_uncertainty( alpha_spec: NumericArrayLike, alpha_s: NumericArrayLike, u_alpha_spec: NumericArrayLike, u_alpha_s: NumericArrayLike,) -> ScatteringUncertaintyUncertainty 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. |
ScatteringDiffusionWarning
Section titled “ScatteringDiffusionWarning”Advisory for out-of-range scattering/diffusion measurement conditions.
ScatteringResult
Section titled “ScatteringResult”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()
Section titled “ScatteringResult.plot()”ScatteringResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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()
Section titled “ScatteringResult.report()”ScatteringResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender 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
Section titled “ScatteringUncertainty”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
Section titled “specular_absorption_coefficient”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
Section titled “speed_of_sound_iso17497”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. |