materials.scattering_diffusion

Random-incidence scattering and directional diffusion coefficients.

Two complementary free-field / reverberation-room surface descriptors are implemented, each faithful to its own standard:

• ISO 17497-1:2004+A1:2014 - random-incidence scattering coefficient in a reverberation room. 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 s = (alpha_spec - alpha_s) / (1 - alpha_s) (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), and measurement accuracy from Annex A (Eqs. (A.1)-(A.5)).

• ISO 17497-2:2012 - directional diffusion coefficient in a free field. From the set of reflected sound-pressure levels L_i on a semicircle or hemisphere the autocorrelation diffusion coefficient d_theta is formed for equal-area receivers (Clause 8.1, Formula (5)) or with per-receiver area weights N_i (Formula (6)); the area weights follow from the solid-angle factors of Clause 8.3 (Formula (8)). Finite-panel effects are removed by normalising to the reference flat surface (Clause 8.2, Formula (7)), and the random-incidence coefficient is the (weighted) average of the directional coefficients over the source positions (Clause 8.4).

Neither part of ISO 17497 contains a numeric worked example; the two methods are distinct measurements and the helpers are named per part so they are never mixed.

The Part 2 diffusion coefficient is the design target of subwavelength diffuser panels such as the metadiffusers of Jiménez, Cox, Romero-García & Groby (2017, Scientific Reports 7, 5389, doi:10.1038/s41598-017-05710-5), whose slow-sound resonant slots reach the diffusion of a Schroeder or quadratic-residue diffuser in a fraction of the depth.

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

absorption_coefficient_uncertainty

absorption_coefficient_uncertainty(
    volume: float,
    area: float,
    *,
    c: ArrayLike,
    T_a: ArrayLike,
    u_a: ArrayLike,
    T_b: ArrayLike,
    u_b: ArrayLike,
) -> Real

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

u_alpha = (55,3 V) / (c S) * sqrt((u_b / T_b^2)^2 + (u_a / T_a^2)^2).

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.
c	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).

Raises

Exception	When
ValueError	for non-positive V, S, c or T.

air_attenuation_coefficient

air_attenuation_coefficient(
    pressure_attenuation_db_per_m: ArrayLike,
) -> Real

Energy attenuation coefficient m (ISO 17497-1:2004, Clause 8, Eq. (3)).

m = alpha / (10 * lg(e)) approx. alpha / 4,343 (1/m), where alpha is the sound-pressure attenuation coefficient in dB/m obtained from ISO 9613-1 using the measured temperature and relative humidity.

Parameters

Name	Description
pressure_attenuation_db_per_m	Pressure attenuation coefficient alpha from ISO 9613-1, in decibels per metre (scalar or per band).

Returns: Energy (power) attenuation coefficient m, in reciprocal metres.

Raises

Exception	When
ValueError	if any value is negative or non-finite.

area_factors

area_factors(
    elevations: ArrayLike,
    *,
    delta_theta: float,
    delta_phi: float | None = None,
) -> Real

Per-receiver area weights N_i (ISO 17497-2, Clause 8.3, Formula (8)).

For a hemispherical measurement the solid-angle area sampled by a receiver at elevation theta (with angular spacings delta_theta, delta_phi) is:

A_i = (4 pi / delta_phi) * sin^2(delta_theta / 4)   for theta = 0 deg
A_i = 2 sin(theta) sin(delta_theta / 2)             for theta != 0, 90 deg
A_i = sin(delta_theta / 2)                          for |theta| = 90 deg

and N_i = A_i / A_min (Formula (8)), with A_min the smallest A_i. All angles are handled internally in radians; the theta = 0 form in particular requires delta_phi in radians to be dimensionally consistent with the 4 pi factor.

Parameters

Name	Description
elevations	Receiver elevation angles theta from the reference normal, in degrees (1-D), over the measurement domain 0 <= theta <= 90 (Figure 7). Formula (8) assumes a single receiver at theta = 0 (the zenith); duplicate zenith entries would each take the full zenith area.
delta_theta	Elevation spacing between adjacent receivers, in degrees (typically 5).
delta_phi	Azimuth spacing between adjacent receivers, in degrees; defaults to delta_theta. Required (implicitly) for the theta = 0 receiver.

Returns: Per-receiver area weights N_i (dimensionless, min value 1).

Raises

Exception	When
ValueError	for a non-1-D input or non-positive spacings.

BASE_PLATE_BANDS

Constant (tuple).

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

BASE_PLATE_MAX_SCATTERING

Constant (dict).

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

base_plate_scattering(
    volume: float,
    area: float,
    *,
    c1: ArrayLike,
    T1: ArrayLike,
    c3: ArrayLike,
    T3: ArrayLike,
    m1: ArrayLike = 0.0,
    m3: ArrayLike = 0.0,
) -> Real

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

s_base = 55,3 * (V / S) * (1 / (c3 T3) - 1 / (c1 T1)) - (4 V / S) * (m3 - m1).

Ideally T1 == T3; 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).

Raises

Exception	When
ValueError	for non-positive V, S, c or T.

check_base_plate_scattering

check_base_plate_scattering(
    scattering: Mapping[Any, float] | Sequence[float] | ArrayLike,
) -> tuple[int, ...]

Verify base-plate scattering against Table 1 (ISO 17497-1, Clause 6.2).

Every band whose measured base-plate scattering coefficient exceeds the BASE_PLATE_MAX_SCATTERING limit is collected and a single ScatteringDiffusionWarning is issued when any band is over the limit.

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.

Returns: Tuple of the centre frequencies (Hz) that exceed the limit, in ascending order (empty if the base plate is compliant).

Raises

Exception	When
ValueError	for a mapping missing a band or a sequence of the wrong length.

diffusion_spectrum

diffusion_spectrum(
    frequencies: ArrayLike,
    diffusion: ArrayLike,
    *,
    normalized: ArrayLike | None = None,
) -> DiffusionSpectrum

Diffusion-coefficient spectrum d(f) (ISO 17497-2, Clause 8.5).

Pairs the per-band diffusion coefficients d with their band centres and returns a plottable, reportable DiffusionSpectrum. The coefficient is the directional coefficient d_theta (Formula (5)/(6)) when it comes from a single source position, or the random-incidence coefficient d when it is the per-band average of the directional coefficients over the source positions (Clause 8.4, e.g. via random_incidence_diffusion band by band). The optional normalised coefficients d_n (Formula (7)) are carried through when supplied.

Parameters

Name	Description
frequencies	One-third-octave band centres, in hertz (1-D).
diffusion	Diffusion coefficient d per band.
normalized	Optional normalised diffusion coefficient d_n per band; None when the reference flat surface was not measured.

Returns: A DiffusionSpectrum with .plot() and .report().

Raises

Exception	When
ValueError	if the inputs differ in length, are empty or not 1-D.

DiffusionResult

DiffusionResult(angles: Real, levels: Real, coefficient: float)

A measured polar response and its diffusion coefficient (ISO 17497-2).

Attributes

Name	Description
angles	Receiver angles of the polar response, in degrees.
levels	Reflected sound-pressure level at each angle, in decibels.
coefficient	Autocorrelation diffusion coefficient d (Formula (5)).

DiffusionResult.plot()

DiffusionResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the polar response with the diffusion coefficient annotated.

Requires matplotlib (pip install phonometry[plot]); returns the polar Axes and never calls plt.show.

DiffusionResult.report()

DiffusionResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render an ISO 17497-2 polar-response test-report fiche to a PDF.

Writes a one-page accredited free-field diffusion report for a single source position (ISO 17497-2:2012, Clause 8.5): the standard-basis line, an optional metadata header block, a two-panel body with the corrected polar-response table (receiver angle and reflected sound-pressure level L, rounded to 0,1 dB) beside the semicircular polar plot, a boxed directional diffusion coefficient d_theta (Formula (5)/(6)) and a footer with the fixed disclaimer. ISO 17497-2 is a characterisation, so there is no pass/fail verdict.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a body-and-disclaimer fiche. The applicable descriptive fields are client, manufacturer, specimen, mounting, test_room, test_date, temperature, relative_humidity, pressure, measurement_standard, laboratory, operator, report_id and notes. The requirement field is ignored (ISO 17497-2 has no verdict).
engine	Rendering back end; only "reportlab" is supported.
verbose	Accepted for signature parity; the polar-response fiche has no extended table, so it renders the same body.
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 (pip install phonometry[report]).

DiffusionSpectrum

DiffusionSpectrum(
    frequencies: Real,
    diffusion: Real,
    normalized: Real | None = None,
)

A diffusion-coefficient spectrum d(f) (ISO 17497-2, Clause 8.5).

Where DiffusionResult holds the polar response of a single one-third-octave band, this holds the diffusion coefficient across the measured bands, so it can be tabulated and plotted against frequency as Clause 8.5 requires. The per-band coefficient is a directional diffusion coefficient d_theta (Formula (5)/(6)) when it comes from one source position, or a random-incidence diffusion coefficient d when it is the per-band average of the directional coefficients over the source positions (Clause 8.4); the standard defines both as frequency-dependent quantities, so this carries a spectrum rather than a single number.

Attributes

Name	Description
frequencies	One-third-octave band centre frequencies, in hertz.
diffusion	Diffusion coefficient d per band (directional per source, or random-incidence when averaged over source positions).
normalized	Optional normalised diffusion coefficient d_n per band (Formula (7)), or None when the reference flat surface was not measured.

DiffusionSpectrum.plot()

DiffusionSpectrum.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the diffusion coefficient d versus frequency.

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

DiffusionSpectrum.report()

DiffusionSpectrum.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render an ISO 17497-2 diffusion-coefficient test-report fiche to a PDF.

Writes a one-page accredited free-field diffusion report (ISO 17497-2:2012, Clause 8.5): the standard-basis line, an optional metadata header block, a two-panel body with the per-band table (frequency, the diffusion coefficient d and, when present, the normalised d_n) beside the d(f) curve on a categorical band axis, a boxed characterisation headline over the tested frequency range, and a footer with the fixed disclaimer. ISO 17497-2 is a characterisation, so there is no pass/fail verdict.

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, mounting, test_room, test_date, temperature, relative_humidity, pressure, measurement_standard, laboratory, operator, report_id and notes. The requirement field is ignored (ISO 17497-2 has no verdict).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True and a normalised spectrum is present, the value table adds the normalised d_n column.
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 (pip install phonometry[report]).

directional_diffusion

directional_diffusion(
    angles: ArrayLike,
    levels: ArrayLike,
    *,
    weights: ArrayLike | None = None,
) -> DiffusionResult

Diffusion coefficient of a polar response (ISO 17497-2, Formula (5)/(6)).

Convenience wrapper over directional_diffusion_coefficient that keeps the receiver angles alongside the levels and returns a plottable DiffusionResult.

Parameters

Name	Description
angles	Receiver angles of the polar response, in degrees (1-D).
levels	Reflected sound-pressure level at each angle, in decibels.
weights	Optional area weights N_i (Formula (8)); None uses the equal-area Formula (5).

Returns: A DiffusionResult with .plot().

Raises

Exception	When
ValueError	if angles and levels differ in length or are shorter than two receivers.

directional_diffusion_coefficient

directional_diffusion_coefficient(
    levels: ArrayLike,
    *,
    area_weights: ArrayLike | None = None,
) -> float

Directional diffusion coefficient d_theta (ISO 17497-2, Formulas (5)/(6)).

For a fixed source position and one-third-octave band, from the n reflected sound-pressure levels L_i (dB). With equal-area receivers (area_weights is None, Formula (5)):

d_theta = ((sum p_i)^2 - sum p_i^2) / ((n - 1) * sum p_i^2)

where p_i = 10^(L_i / 10). When each receiver samples a different area (Formula (6)) the per-receiver weights N_i (from area_factors) enter:

d_theta = ((sum p_i N_i)^2 - sum N_i p_i^2)
          / ((sum N_i - 1) * sum N_i p_i^2)

which reduces to Formula (5) for uniform weights. The coefficient is 0 when only one receiver has non-zero scattered energy and 1 when all receivers are equal.

Parameters

Name	Description
levels	The n >= 2 reflected sound-pressure levels L_i, in decibels (a level of -inf denotes a receiver with zero energy).
area_weights	Optional per-receiver area weights N_i (Formula (8)); None selects the equal-area Formula (5).

Returns: Directional diffusion coefficient d_theta (a scalar).

Raises

Exception	When
ValueError	for fewer than two receivers, a non-1-D input, a length mismatch, or non-positive total weight.

normalized_diffusion_coefficient

normalized_diffusion_coefficient(
    d_theta: ArrayLike,
    d_theta_reference: ArrayLike,
) -> Real

Normalised directional diffusion coefficient (ISO 17497-2, Formula (7)).

d_theta_n = (d_theta - d_theta_r) / (1 - d_theta_r), removing the finite-panel diffusion of the reference flat surface d_theta_r (same projected footprint as the test surface). It maps d_theta = d_theta_r to 0 and d_theta = 1 to 1.

Parameters

Name	Description
d_theta	Directional diffusion coefficient of the test surface.
d_theta_reference	Directional diffusion coefficient of the reference flat surface d_theta_r.

Returns: Normalised directional diffusion coefficient d_theta_n.

Raises

Exception	When
ValueError	if any reference coefficient equals 1 (undefined ratio).

random_incidence_absorption

random_incidence_absorption(
    volume: float,
    area: float,
    *,
    c1: ArrayLike,
    T1: ArrayLike,
    c2: ArrayLike,
    T2: ArrayLike,
    m1: ArrayLike = 0.0,
    m2: ArrayLike = 0.0,
) -> Real

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

alpha_s = 55,3 * (V / S) * (1 / (c2 T2) - 1 / (c1 T1)) - (4 V / S) * (m2 - m1).

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).
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 air_attenuation_coefficient); defaults to 0.
m2	Energy attenuation coefficient during T2, in 1/m; defaults to 0.

Returns: Random-incidence absorption coefficient alpha_s (per band).

Raises

Exception	When
ValueError	for non-positive V, S, c or T.

random_incidence_diffusion

random_incidence_diffusion(
    directional_coefficients: ArrayLike,
    *,
    weights: ArrayLike | None = None,
) -> float

Random-incidence diffusion coefficient d (ISO 17497-2, Clause 8.4).

The (normalised or non-normalised) directional coefficients are averaged over the source positions. Hemispherical measurements use equal weightings (weights is None); two-dimensional (single-plane) measurements use the source weighting of Clause 8.4 - weight 1 for the 0 deg source and weight 3 for each of the four +/-30 deg, +/-60 deg sources (see TWO_DIMENSIONAL_SOURCE_WEIGHTS).

Parameters

Name	Description
directional_coefficients	Directional diffusion coefficients d_theta (or d_theta_n), one per source position (1-D).
weights	Optional source-position weights; None averages with equal weight.

Returns: Random-incidence diffusion coefficient d (a scalar).

Raises

Exception	When
ValueError	for an empty or non-1-D input, a length mismatch, or non-positive total weight.

reverberation_time_uncertainty

reverberation_time_uncertainty(times: ArrayLike) -> Real

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

u = sqrt( sum_i (T_i - Tbar)^2 / (N (N - 1)) ) with Tbar the mean of the N spatially-averaged measurements (Eq. (A.2)); this is the standard error of the mean.

Parameters

Name	Description
times	The N >= 2 reverberation-time measurements, in seconds.

Returns: Standard uncertainty u of the mean reverberation time (0-d).

Raises

Exception	When
ValueError	if fewer than two measurements are supplied.

scattering_coefficient

scattering_coefficient(
    alpha_spec: ArrayLike,
    alpha_s: ArrayLike,
    *,
    truncate_negative: bool = True,
) -> Real

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

s = 1 - (1 - alpha_spec) / (1 - alpha_s) = (alpha_spec - alpha_s) / (1 - alpha_s).

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).

Raises

Exception	When
ValueError	if any alpha_s equals 1 (undefined ratio).

scattering_coefficient_spectrum

scattering_coefficient_spectrum(
    frequencies: ArrayLike,
    specular_absorption: ArrayLike,
    random_absorption: ArrayLike,
    *,
    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 length, are empty, or any alpha_s equals 1.

scattering_coefficient_uncertainty

scattering_coefficient_uncertainty(
    alpha_spec: ArrayLike,
    alpha_s: ArrayLike,
    u_alpha_spec: ArrayLike,
    u_alpha_s: ArrayLike,
) -> ScatteringUncertainty

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

`u_s = |(alpha_spec - 1) / (1 - alpha_s)|

• sqrt((u_alpha_spec / (alpha_spec - 1))^2 + (u_alpha_s / (1 - alpha_s))^2)`,

with the expanded uncertainty U = 2 u_s (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 U = 2 u_s.

Raises

Exception	When
ValueError	if any alpha_s equals 1 or any alpha_spec equals 1.

ScatteringDiffusionWarning

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

ScatteringResult

ScatteringResult(
    frequencies: Real,
    scattering: Real,
    random_incidence: Real,
    specular: Real,
)

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()

ScatteringResult.plot(
    ax: Axes | None = None,
    *,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Plot the scattering coefficient s versus frequency.

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

ScatteringResult.report()

ScatteringResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = '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, relative_humidity, 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 (pip install phonometry[report]).

ScatteringUncertainty

ScatteringUncertainty(u_scattering: Real, expanded: Real)

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 U = 2 u_s at 95 % confidence (Annex A).

specular_absorption_coefficient

specular_absorption_coefficient(
    volume: float,
    area: float,
    *,
    c3: ArrayLike,
    T3: ArrayLike,
    c4: ArrayLike,
    T4: ArrayLike,
    m3: ArrayLike = 0.0,
    m4: ArrayLike = 0.0,
) -> Real

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

alpha_spec = 55,3 * (V / S) * (1 / (c4 T4) - 1 / (c3 T3)) - (4 V / S) * (m4 - m3).

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).

Raises

Exception	When
ValueError	for non-positive V, S, c or T.

speed_of_sound

speed_of_sound(temperature: ArrayLike) -> Real

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

c = 343,2 * sqrt((273,15 + t) / 293,15) (m/s).

Parameters

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

Returns: Speed of sound c, in metres per second.

Raises

Exception	When
ValueError	if any temperature is at or below -273,15 degC.

TWO_DIMENSIONAL_SOURCE_WEIGHTS

Constant (tuple).

TWO_DIMENSIONAL_SOURCE_WEIGHTS = (1, 3, 3, 3, 3)