building.insulation

Field airborne sound insulation (ISO 16283-1:2014) and impact sound insulation (ISO 16283-2), with single-number weighted ratings and spectrum adaptation terms (ISO 717-1 airborne, ISO 717-2 impact).

Field quantities (ISO 16283-1:2014). From the energy-average sound pressure levels in the source and receiving rooms this module forms the level difference D = L1 - L2 (Clause 3.12, Formula (1)), the standardized level difference DnT = D + 10 lg(T/T0) with the reference reverberation time T0 = 0,5 s (Clause 3.13, Formula (2)), and the apparent sound reduction index R' = D + 10 lg(S/A) with the Sabine equivalent absorption area A = 0,16 V / T (Clause 3.14/3.15, Formula (4) and (5)). Source and receiving levels may be supplied already averaged (one value per band) or as several microphone positions, which are then energy-averaged with 10 lg( (1/n) sum 10^(Li/10) ) (Clause 7.8, Formula (9)). All quantities are evaluated per one-third-octave band over the core range 100 Hz to 3150 Hz (Clause 5), the caller having already applied any background-noise correction (Clause 9.2).

Weighted rating (ISO 717-1). The reference-curve method of Clause 4.4 shifts the reference curve of Table 3 in 1 dB steps towards the measured curve until the sum of unfavourable deviations (measured below the shifted reference) is as large as possible but not more than 32,0 dB for the 16 one-third-octave bands (100 Hz to 3150 Hz) or 10,0 dB for the 5 octave bands (125 Hz to 2000 Hz). The weighted rating (Rw, R'w, Dn,w, DnT,w …) is the shifted reference read at 500 Hz. The spectrum adaptation terms are C = XA1 - Xw and Ctr = XA2 - Xw with XAj = -10 lg sum 10^((Lij - Xi)/10) rounded to an integer, using the A-weighted spectra No. 1 (pink noise, C) and No. 2 (urban traffic, Ctr) of Table 4 (Clause 4.5, Formula (1) and (2)). Input levels are reduced to one decimal place before use (Clause 4.4, footnote 1). The reference values, spectra and shifting rule are identical in the 2013 and 2020 editions of ISO 717-1.

Enlarged frequency ranges (ISO 717-1 Annex B; ISO 717-2 A.2.1 NOTE). When measurements cover an enlarged range, additional adaptation terms are stated with the range as a subscript: C50-3150, C50-5000, C100-5000 (and the Ctr counterparts) with the Table B.1 spectra, and CI,50-2500 for impact. weighted_rating_extended and weighted_impact_rating_extended compute them alongside the core rating. Both accept one_decimal=True for the “1/10 dB for the expression of uncertainty” variant of Clauses 4.4/4.5 (reference-curve shift in 0,1 dB steps and one-decimal reductions), which ISO 12999-1:2020 Annex B requires when stating the uncertainty of single-number values.

Field impact quantities (ISO 16283-2). With the tapping machine as the impact source this module forms, from the energy-average impact sound pressure level Li in the receiving room, the standardized impact sound pressure level L'nT = Li - 10 lg(T/T0) with T0 = 0,5 s (Clause 3.13, Formula (1)) and the normalized impact sound pressure level L'n = Li + 10 lg(A/A0) with the Sabine absorption area A = 0,16 V/T and the reference area A0 = 10 m² (Clause 3.14, Formula (2)). Levels may be supplied already averaged or as several microphone positions, then energy-averaged (Clause 7.8, Formula (10)), over the core one-third-octave range 100 Hz to 3150 Hz (Clause 5.1).

Field façade quantities (ISO 16283-3:2016). With an outdoor sound source this module forms, from the level 2 m in front of the façade L1,2m and the receiving-room level L2, the level difference D2m = L1,2m - L2 (Clause 3.14), its standardized form D2m,nT = D2m + 10 lg(T/T0) with T0 = 0,5 s (Clause 3.15) and normalized form D2m,n = D2m - 10 lg(A/A0) with the Sabine absorption area A = 0,16 V/T (Clause 3.17) and reference A0 = 10 m² (Clause 3.16): the global loudspeaker / traffic quantities Dls,2m,* / Dtr,2m,*. When a surface level L1,s (microphone on the test element) with the element area S and volume are given it forms the apparent sound reduction index R'45° = L1,s - L2 + 10 lg(S/A) - 1,5 for the loudspeaker element method (Clause 3.12) or R'tr,s = L1,s - L2 + 10 lg(S/A) - 3 for the road-traffic element method (Clause 3.13). These quantities are defined by unnumbered formulas inline in the Clause 3 terms; positions are energy-averaged with the surface-level formula (Clause 9.5.1, Formula (7)). Quantities are evaluated over the core one-third-octave range 100 Hz to 3150 Hz (Clause 5), optionally extended to 50-5000 Hz. The façade quantity is airborne, so its single-number rating uses the ISO 717-1 airborne reference curve and method (Clause 2, Annex F) via weighted_rating unchanged.

Weighted impact rating (ISO 717-2). The reference-curve method of Clause 4.3 shifts the Table 3 impact reference curve towards the measured curve until the sum of unfavourable deviations (here where the measurement exceeds the reference, the sign opposite to airborne) is as large as possible but not more than 32,0 dB (16 one-third-octave bands) or 10,0 dB (5 octave bands). The rating (Ln,w, L'n,w, L'nT,w) is the shifted reference read at 500 Hz, reduced by a further 5 dB for octave bands (Clause 4.3.2). The spectrum adaptation term CI = Ln,sum - 15 - Ln,w uses the energetic sum Ln,sum over 100 Hz to 2500 Hz (one-third octave) or 125 Hz to 2000 Hz (octave), rounded to an integer (Clause A.2.1, Formulae (A.1) to (A.3)). The Table 3 reference values, the shifting rule and CI are identical in the 2013 and 2020 editions of ISO 717-2 (the 2020 edition only adds Annex D for the rubber-ball heavy/soft impactor, out of scope here).

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

airborne_insulation

airborne_insulation(
    l1: Sequence[float] | np.ndarray,
    l2: Sequence[float] | np.ndarray,
    t2: Sequence[float] | np.ndarray,
    *,
    area: float | None = None,
    volume: float | None = None,
    t0: float = 0.5,
) -> AirborneInsulationResult

Field airborne sound insulation per ISO 16283-1:2014.

Computes, per frequency band, the level difference D = L1 - L2 (Formula (1)), the standardized level difference DnT = D + 10 lg(T/T0) (Formula (2)) and, when the partition area and receiving-room volume are given, the apparent sound reduction index R' = D + 10 lg(S/A) with A = 0,16 V / T (Formula (4) and (5)).

l1 and l2 may be one value per band (already energy-averaged) or a two-dimensional (positions, bands) array, in which case the positions are energy-averaged with Formula (9). The band levels are assumed already corrected for background noise (Clause 9.2).

Parameters

Name	Description
l1	Source-room sound pressure levels, in dB.
l2	Receiving-room sound pressure levels, in dB.
t2	Receiving-room reverberation time per band, in seconds.
area	Area S of the common partition, in m² (optional; required together with volume for R').
volume	Receiving-room volume V, in m³ (optional; required together with area for R').
t0	Reference reverberation time T0, in seconds (default 0,5 s for dwellings, Clause 3.13).

Returns: AirborneInsulationResult with d, dnt and r_prime (the latter None unless area and volume are both given).

Raises

Exception	When
ValueError	If the band counts of l1, l2 and t2 differ, if only one of area/volume is supplied, if t2/t0 are not positive, or if inputs are non-finite.

AirborneInsulationResult

AirborneInsulationResult(
    d: np.ndarray,
    dnt: np.ndarray,
    r_prime: np.ndarray | None,
    l1: np.ndarray | None = None,
    l2: np.ndarray | None = None,
    t2: np.ndarray | None = None,
    t0: float | None = None,
)

Per-band field airborne sound insulation (ISO 16283-1:2014).

Attributes

Name	Description
d	Level difference D = L1 - L2 per band, in dB (Clause 3.12, Formula (1)).
dnt	Standardized level difference DnT per band, in dB (Clause 3.13, Formula (2)).
r_prime	Apparent sound reduction index R' per band, in dB (Clause 3.14, Formula (4)), or None when the partition area and receiving-room volume were not supplied.
l1	Energy-average source-room levels the quantities were formed from, in dB (after any position averaging, Formula (9)). Defaults to None for backward-compatible construction.
l2	Energy-average receiving-room levels, in dB. Defaults to None.
t2	Receiving-room reverberation time per band, in seconds. Defaults to None.
t0	Reference reverberation time T0 used for DnT, in seconds. Defaults to None.

AirborneInsulationResult.plot()

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

Plot the per-band insulation quantities (DnT, D, R').

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

AirborneInsulationResult.report()

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

Render an ISO 16283-1 field airborne sound-insulation report to a PDF.

Writes the one-page field test report of ISO 16283-1:2014 Clause 14 in the layout of the recommended Annex B form: the standard-basis line, an optional metadata header block (client, construction, room volumes, partition area …), the one-third-octave table beside the measured-versus-shifted-reference curve, the boxed field rating DnT,w (C; Ctr) or R'w (C; Ctr) (evaluated per ISO 717-1 over the 16 core bands), the mandatory field-method statement, an optional verdict row and a footer with the identity block and disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
quantity	The reported field quantity: "dnt" (default, the standardized level difference of Annex B Figure B.1) or "r_prime" (the apparent sound reduction index of Figure B.2; requires the result to carry r_prime).
metadata	Optional ReportMetadata; None produces a lightweight fiche (body, rating and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table shows the measurement chain per band (energy-average L1 and L2, reverberation time T and the quantity) instead of the two-column f | value form; it requires the result to carry l1, l2 and t2 (populated by airborne_insulation).
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine or quantity is unknown, the selected quantity is not available, the result does not hold the 16 core one-third-octave bands (100 Hz to 3150 Hz) the ISO 717-1 rating needs, or verbose=True without the per-band chain.
ImportError	If reportlab is not installed (pip install phonometry[report]).

energy_average_level

energy_average_level(
    levels: Sequence[float] | np.ndarray,
    axis: int = -1,
) -> np.ndarray | float

Energy-average sound pressure level (ISO 16283-1:2014, Formula (9)).

Combines sound pressure levels measured at several microphone positions into L = 10 lg( (1/n) sum_i 10^(Li/10) ).

Parameters

Name	Description
levels	Sound pressure levels, in dB, at the n positions to be averaged along axis.
axis	Axis over which to average (default the last axis).

Returns: The energy-average level, in dB; a scalar float when the result is zero-dimensional, otherwise an array.

Raises

Exception	When
ValueError	If levels is empty or contains non-finite values.

ExtendedImpactRatingResult

ExtendedImpactRatingResult(
    rating: float,
    ci: float,
    ci_50_2500: float | None,
    core: ImpactRatingResult,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
)

Weighted impact rating with CI,50-2500 (ISO 717-2:2020 A.2.1 NOTE).

Values are integers unless computed with one_decimal=True.

Attributes

Name	Description
rating	Weighted impact rating (Ln,w, …) from the core 100-3150 Hz bands, in dB.
ci	Core spectrum adaptation term CI (100-2500 Hz), in dB.
ci_50_2500	Enlarged-range term CI,50-2500, in dB, or None when the supplied bands do not cover 50-2500 Hz.
core	The integer-mode ImpactRatingResult of the core bands (independent of one_decimal).
band_centers	Band centre frequencies of the full (enlarged-range) measured curve, in Hz. Defaults to None for backward-compatible construction.
measured	The measured impact levels over the full enlarged range (after the one-decimal reduction of Clause 4.3), in dB. Defaults to None.

ExtendedImpactRatingResult.plot()

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

Plot the enlarged-range curve vs the shifted reference (ISO 717-2).

The measured curve is drawn over the full enlarged range, the ISO 717-2 reference curve (after the final shift) over the 16 core bands 100-3150 Hz, with the unfavourable deviations (measurement above the reference) shaded on the core bands and the bands outside the core range marked as the enlarged range; the title carries the impact rating with CI and, when covered, CI,50-2500. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

ExtendedWeightedRatingResult

ExtendedWeightedRatingResult(
    rating: float,
    c: float,
    ctr: float,
    c_50_3150: float | None,
    c_50_5000: float | None,
    c_100_5000: float | None,
    ctr_50_3150: float | None,
    ctr_50_5000: float | None,
    ctr_100_5000: float | None,
    core: WeightedRatingResult,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
)

Weighted rating with the enlarged-range adaptation terms (ISO 717-1 Annex B).

All values are integers unless the result was computed with one_decimal=True (the “1/10 dB for the expression of uncertainty” variant of Clauses 4.4/4.5), in which case they carry one decimal place. An extended term is None when the supplied bands do not cover its frequency range.

Attributes

Name	Description
rating	Weighted rating (Rw, R'w, …) from the core 100-3150 Hz bands, in dB.
c	Core spectrum adaptation term C (100-3150 Hz), in dB.
ctr	Core spectrum adaptation term Ctr (100-3150 Hz), in dB.
c_50_3150	C50-3150, in dB, or None.
c_50_5000	C50-5000, in dB, or None.
c_100_5000	C100-5000, in dB, or None.
ctr_50_3150	Ctr,50-3150, in dB, or None.
ctr_50_5000	Ctr,50-5000, in dB, or None.
ctr_100_5000	Ctr,100-5000, in dB, or None.
core	The integer-mode WeightedRatingResult of the core bands (independent of one_decimal), for plotting and the unfavourable-deviation sum.
band_centers	Band centre frequencies of the full (enlarged-range) measured curve, in Hz. Defaults to None for backward-compatible construction.
measured	The measured band quantities over the full enlarged range (after the one-decimal reduction of Clause 4.4), in dB. Defaults to None.

ExtendedWeightedRatingResult.plot()

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

Plot the enlarged-range curve vs the shifted reference (Annex B).

The measured curve is drawn over the full enlarged range, the ISO 717-1 reference curve (after the final shift) over the 16 core bands 100-3150 Hz, with the unfavourable deviations shaded on the core bands and the bands outside the core range marked as the enlarged range; the title carries Rw (C; Ctr) and every Annex B adaptation term the input covered. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

facade_insulation

facade_insulation(
    l1_2m: Sequence[float] | np.ndarray,
    l2: Sequence[float] | np.ndarray,
    t2: Sequence[float] | np.ndarray,
    *,
    area: float | None = None,
    volume: float | None = None,
    surface_level: Sequence[float] | np.ndarray | None = None,
    method: str = 'loudspeaker',
    t0: float = 0.5,
    frequencies: Sequence[float] | np.ndarray | None = None,
) -> FacadeInsulationResult

Field façade sound insulation per ISO 16283-3:2016.

Computes, per frequency band, the global-method level difference D2m = L1,2m - L2 (Clause 3.14), its standardized form D2m,nT = D2m + 10 lg(T/T0) (Clause 3.15) and, when the receiving-room volume is given, its normalized form D2m,n = D2m - 10 lg(A/A0) with the Sabine equivalent absorption area A = 0,16 V/T (Clause 3.17) and A0 = 10 m² (Clause 3.16). When a surface level L1,s (microphone on the test element), together with the element area S and the volume, is supplied it also computes the apparent sound reduction index of the element method: R'45° = L1,s - L2 + 10 lg(S/A) - 1,5 for a loudspeaker source (Clause 3.12) or R'tr,s = L1,s - L2 + 10 lg(S/A) - 3 for a road-traffic source (Clause 3.13). The defining formulas are unnumbered inline in the Clause 3 terms.

l1_2m, l2 and surface_level may be one value per band (already energy-averaged) or a two-dimensional (positions, bands) array, in which case the positions are energy-averaged with the surface-level formula (Clause 9.5.1, Formula (7)). Band levels are assumed already corrected for background noise. The single-number rating uses the ISO 717-1 airborne reference curve (Annex F); pass the desired 16-band quantity to weighted_rating.

Parameters

Name	Description
l1_2m	Outdoor sound pressure levels 2 m in front of the façade, in dB.
l2	Receiving-room sound pressure levels, in dB.
t2	Receiving-room reverberation time per band, in seconds.
area	Area S of the test element, in m² (optional; required with volume and surface_level for R').
volume	Receiving-room volume V, in m³ (optional; required for D2m,n and for R').
surface_level	Outdoor surface level L1,s on the test element, in dB (optional; required with area and volume for R').
method	"loudspeaker" (45° incidence, -1,5 dB) or "road_traffic" (all-angle incidence, -3 dB); selects the R' correction (Clause 3.12 / 3.13).
t0	Reference reverberation time T0, in seconds (default 0,5 s for dwellings, Clause 3.15).
frequencies	Optional band centre frequencies, in Hz, carried on the result for plotting.

Returns: FacadeInsulationResult with d_2m, d_2m_nt, d_2m_n (None unless volume is given) and r_prime (None unless surface_level, area and volume are all given).

Raises

Exception	When
ValueError	If band counts differ, if method is unknown, if t2/t0/area/volume are not positive, if area is given without surface_level, if surface_level and area are given without volume, if frequencies is given with a length that differs from the band count, or if inputs are non-finite. Supplying surface_level alone is not an error: r_prime simply stays None.

FacadeInsulationResult

FacadeInsulationResult(
    d_2m: np.ndarray,
    d_2m_nt: np.ndarray,
    d_2m_n: np.ndarray | None,
    r_prime: np.ndarray | None,
    frequencies: np.ndarray | None = None,
    method: str = 'loudspeaker',
)

Per-band field façade sound insulation (ISO 16283-3).

Attributes

Name	Description
d_2m	Level difference D2m = L1,2m - L2 per band, in dB (Clause 3.14; Dls,2m loudspeaker, Dtr,2m traffic).
d_2m_nt	Standardized level difference D2m,nT = D2m + 10 lg(T/T0) per band, in dB (Clause 3.15).
d_2m_n	Normalized level difference D2m,n = D2m - 10 lg(A/A0) per band, in dB (Clause 3.16), or None when the receiving-room volume was not supplied.
r_prime	Apparent sound reduction index R'45° (loudspeaker, Clause 3.12) or R'tr,s (road traffic, Clause 3.13) per band, in dB, or None unless a surface level together with the element area and receiving-room volume were supplied.
frequencies	Band centre frequencies, in Hz, or None.
method	The sound source of the measurement: "loudspeaker" (45° incidence) or "road_traffic". It selects which apparent index r_prime is (R'45 or R'tr,s) and how the report labels it.

FacadeInsulationResult.plot()

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

Plot the per-band façade insulation profile (ISO 16283-3).

Draws the standardized level difference and any other available quantities (D2m, D2m,n, R') against frequency. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

FacadeInsulationResult.report()

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

Render an ISO 16283-3 field facade sound-insulation report to a PDF.

Writes the one-page field facade test report of ISO 16283-3:2016: the standard-basis line, an optional metadata header block, the one-third-octave table beside the measured-versus-shifted-reference curve, the boxed ISO 717-1 field rating of the reported quantity (D2m,nT,w for d_2m_nt, D2m,n,w for d_2m_n or, for r_prime, R'45,w / R'tr,s,w following the result’s method, each with C; Ctr and evaluated over the 16 core bands), the mandatory field-method statement, an optional verdict row and a footer with the identity block and disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
quantity	The reported facade quantity: "d_2m_nt" (default, the standardized facade level difference D2m,nT), "d_2m_n" (the normalized facade level difference D2m,n; requires the result to carry d_2m_n) or "r_prime" (the apparent sound reduction index; requires the result to carry r_prime). The r_prime fiche is labelled R'45 (Clause 3.12, loudspeaker method) or R'tr,s (Clause 3.13, road traffic method) according to the result’s method.
metadata	Optional ReportMetadata; None produces a lightweight fiche (body, rating and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table shows the ISO 717 evaluation per band (the reported quantity, the shifted reference and the unfavourable deviation) instead of the two-column f | value form.
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine or quantity is unknown, the selected quantity is not available, or the result does not hold the 16 core one-third-octave bands (100 Hz to 3150 Hz) the ISO 717-1 rating needs.
ImportError	If reportlab is not installed (pip install phonometry[report]).

impact_improvement_adaptation_term

impact_improvement_adaptation_term(
    delta_l: Sequence[float] | np.ndarray,
) -> int

Spectrum adaptation term CI,Δ of a floor covering (ISO 717-2:2020 A.2.2).

CI,Δ = CI,r,0 − CI,r (Formula (A.4)) with CI,r,0 = −11 dB (the bare Table 4 reference floor) and CI,r the ISO 717-2 spectrum adaptation term of the reference floor with the covering under test, Ln,r = Ln,r,0 − ΔL (Formula (1)). Together with weighted_impact_improvement it yields the single-number reduction for a flat spectrum, ΔLlin = ΔLw + CI,Δ (Formula (A.5)). ISO 16251-1 Clause 8 e) requires this term in the statement of results.

Parameters

Name	Description
delta_l	The reduction of impact sound pressure level ΔL per band, in dB; 16 one-third-octave values from 100 Hz to 3150 Hz.

Returns: The spectrum adaptation term CI,Δ, in dB (integer).

Raises

Exception	When
ValueError	If delta_l is not 16 one-third-octave values, or is non-finite.

impact_insulation

impact_insulation(
    li: Sequence[float] | np.ndarray,
    t2: Sequence[float] | np.ndarray,
    *,
    volume: float | None = None,
    t0: float = 0.5,
) -> ImpactInsulationResult

Field impact sound insulation per ISO 16283-2 (tapping machine).

Computes, per frequency band, the standardized impact sound pressure level L'nT = Li - 10 lg(T/T0) (Formula (1)) and, when the receiving-room volume is given, the normalized impact sound pressure level L'n = Li + 10 lg(A/A0) with the Sabine equivalent absorption area A = 0,16 V / T (Formula (6)) and the reference absorption area A0 = 10 m² (Formula (2)).

li may be one value per band (already energy-averaged) or a two-dimensional (positions, bands) array, in which case the positions are energy-averaged with Formula (10). The band levels are assumed already corrected for background noise (Clause 9).

Parameters

Name	Description
li	Energy-average impact sound pressure levels, in dB.
t2	Receiving-room reverberation time per band, in seconds.
volume	Receiving-room volume V, in m³ (optional; required for L'n).
t0	Reference reverberation time T0, in seconds (default 0,5 s for dwellings, Clause 3.13).

Returns: ImpactInsulationResult with l_n_t and l_n (the latter None unless volume is given).

Raises

Exception	When
ValueError	If the band counts of li and t2 differ, if t2/t0/volume are not positive, or if inputs are non-finite.

ImpactInsulationResult

ImpactInsulationResult(
    l_n_t: np.ndarray,
    l_n: np.ndarray | None,
    li: np.ndarray | None = None,
    t2: np.ndarray | None = None,
    t0: float | None = None,
)

Per-band field impact sound insulation (ISO 16283-2).

Attributes

Name	Description
l_n_t	Standardized impact sound pressure level L'nT = Li - 10 lg(T/T0) per band, in dB (Clause 3.13, Formula (1)).
l_n	Normalized impact sound pressure level L'n = Li + 10 lg(A/A0) per band, in dB (Clause 3.14, Formula (2)), or None when the receiving-room volume was not supplied.
li	Energy-average impact sound pressure levels the quantities were formed from, in dB (after any position averaging, Formula (10)). Defaults to None for backward-compatible construction.
t2	Receiving-room reverberation time per band, in seconds. Defaults to None.
t0	Reference reverberation time T0 used for L'nT, in seconds. Defaults to None.

ImpactInsulationResult.plot()

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

Plot the per-band impact levels (L'nT and, if present, L'n).

Requires matplotlib (pip install phonometry[plot]); returns the Axes.

ImpactInsulationResult.report()

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

Render an ISO 16283-2 field impact sound-insulation report to a PDF.

Writes the one-page field test report of ISO 16283-2:2020 Clause 14 in the layout of the recommended Annex C form: the standard-basis line, an optional metadata header block, the one-third-octave table beside the measured-versus-shifted-reference curve, the boxed field rating L'nT,w (CI) or L'n,w (CI) (evaluated per ISO 717-2 over the 16 core bands), the mandatory field-method statement, an optional verdict row and a footer with the identity block and disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
quantity	The reported field quantity: "l_n_t" (default, the standardized level of Annex C Figure C.1) or "l_n" (the normalized level of Figure C.2; requires the result to carry l_n).
metadata	Optional ReportMetadata; None produces a lightweight fiche (body, rating and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table shows the measurement chain per band (energy-average Li, reverberation time T and the quantity) instead of the two-column f | value form; it requires the result to carry li and t2 (populated by impact_insulation).
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine or quantity is unknown, the selected quantity is not available, the result does not hold the 16 core one-third-octave bands (100 Hz to 3150 Hz) the ISO 717-2 rating needs, or verbose=True without the per-band chain.
ImportError	If reportlab is not installed (pip install phonometry[report]).

ImpactRatingResult

ImpactRatingResult(
    rating: int,
    ci: int,
    unfavourable_sum: float,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
    shifted_reference: np.ndarray | None = None,
    quantity: str = 'impact',
)

Single-number weighted impact rating and CI (ISO 717-2).

Attributes

Name	Description
rating	Weighted impact rating (Ln,w, L'n,w, L'nT,w), the shifted reference read at 500 Hz, in dB (Clause 4.3; octave-band ratings include the -5 dB reduction of Clause 4.3.2). Integer.
ci	Spectrum adaptation term CI (Clause A.2.1), in dB. Integer.
unfavourable_sum	Sum of unfavourable deviations at the final shift, in dB (Clause 4.3); at most 32,0 (16 bands) or 10,0 (5 bands).
band_centers	Band centre frequencies of the measured curve, in Hz. Defaults to None for backward-compatible construction.
measured	The measured impact levels used for the rating (after the one-decimal reduction of Clause 4.3.1), in dB. Defaults to None.
shifted_reference	Table 3 impact reference curve after the final shift, in dB. Defaults to None.
quantity	Always "impact" (ISO 717-2), selecting the impact labels of the ISO 717 Annex C report.

ImpactRatingResult.plot()

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

Plot the measured curve vs the shifted reference (ISO 717-2).

Unfavourable deviations (measurement above the reference, the sign opposite to airborne) are shaded and Ln,w (CI) annotated. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

ImpactRatingResult.report()

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

Render an ISO 717-2 impact-insulation fiche to a PDF.

Writes a one-page accredited-laboratory report for impact sound: the standard-basis line, an optional metadata header block, the band table beside the measured-versus-shifted-reference plot (the result’s own plot), the boxed Ln,w (CI) result, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a prediction fiche (body, result and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table uses the ISO 717 Annex C columns (frequency, measured value, shifted reference, unfavourable deviation) instead of the two-column f | value table.
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).
symbol	The reported single-number quantity, as plain text: "Ln,w" (the default when None), "L'n,w" or "L'nT,w" per ISO 717-2 Table 1, so a field measurement is not mislabelled with the laboratory descriptor.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine is not "reportlab", symbol is not a valid quantity-symbol shape, or the result was built without the per-band data (band_centers, measured, shifted_reference).
ImportError	If reportlab is not installed (pip install phonometry[report]).

ReportMetadata

ReportMetadata(
    specimen: str | None = None,
    client: str | None = None,
    mounted_by: str | None = None,
    manufacturer: str | None = None,
    area: float | None = None,
    mass_per_area: float | None = None,
    source_volume: float | None = None,
    receiving_volume: float | None = None,
    room_volume: float | None = None,
    source_positions: int | None = None,
    receiver_positions: int | None = None,
    temperature: float | None = None,
    relative_humidity: float | None = None,
    source_temperature: float | None = None,
    source_relative_humidity: float | None = None,
    receiving_temperature: float | None = None,
    receiving_relative_humidity: float | None = None,
    pressure: float | None = None,
    tube_diameter: float | None = None,
    mic_spacing: float | None = None,
    thickness: float | None = None,
    test_room: str | None = None,
    instrumentation: str | None = None,
    calibration: str | None = None,
    mounting: str | None = None,
    measurement_standard: str | None = None,
    test_date: str | None = None,
    laboratory: str | None = None,
    operator: str | None = None,
    report_id: str | None = None,
    requirement: float | None = None,
    required_class: int | None = None,
    notes: str | None = None,
    tube_shape: str | None = None,
)

Descriptive metadata for the accredited ISO 717 report fiche.

All fields are optional (default None); the report renders only the fields that are supplied, so a partially populated instance is valid. The numeric fields are validated on construction by physical range: the dimension, mass, volume and pressure fields must be finite and strictly positive; the temperature and requirement fields need only be finite (0 degrees Celsius or below is a valid test condition, and a programme-loudness target in LUFS is negative); and the relative-humidity fields must lie within 0..100 %. A violation raises ValueError.

Attributes

Name	Description
specimen	Specimen description printed in the header (the tested element, e.g. "200 mm concrete wall").
client	Client the test was carried out for.
mounted_by	Who mounted the specimen in the test opening.
manufacturer	Manufacturer of the tested element.
area	Specimen area S, in m^2 (the free test opening area).
mass_per_area	Measured mass per unit area, in kg/m^2.
source_volume	Source-room volume, in m^3.
receiving_volume	Receiving-room volume, in m^3.
room_volume	Volume of the single room under test, in m^3. Room acoustics (ISO 3382-1/-2) characterises one enclosure rather than a source/receiving pair, and ISO 3382-2:2008 Clause 9 requires the room volume to be reported; the room-acoustics fiche prints it in the header. Distinct from the source_volume/receiving_volume pair, which describe a sound-transmission measurement.
source_positions	Number of source (loudspeaker/omnidirectional) positions used in the measurement, an integer (ISO 3382-1:2009 Table 1 and ISO 3382-2:2008 Clause 8 require reporting the number of source positions). Printed by the room-acoustics fiche.
receiver_positions	Number of microphone (receiver) positions used, an integer (ISO 3382-1:2009 Table 1 and ISO 3382-2:2008 Clause 8 require reporting the number of microphone positions). Printed by the room-acoustics fiche.
temperature	Air temperature during the test, in degrees Celsius (a single representative value; use the per-room fields below when the source and receiving rooms are reported separately).
relative_humidity	Relative humidity during the test, in %.
source_temperature	Source-room air temperature, in degrees Celsius.
source_relative_humidity	Source-room relative humidity, in %.
receiving_temperature	Receiving-room air temperature, in degrees Celsius.
receiving_relative_humidity	Receiving-room relative humidity, in %.
pressure	Ambient (static) air pressure during the test, in kPa.
test_room	Test-room / facility identification.
instrumentation	Identification and class of the instrumentation used (manufacturer, model, serial number), as free text. The occupational noise-exposure fiche prints it for ISO 9612:2009 Clause 15 c; when it is not supplied that fiche falls back to the result’s own instrument class.
calibration	Calibration traceability, as free text (calibrator, date and result of the most recent verification, the before/after field checks). Printed by the occupational noise-exposure fiche (ISO 9612:2009 Clause 15 c).
tube_diameter	Impedance-tube inner diameter d (circular tube) or maximum lateral dimension (rectangular tube), in metres. Printed by the impedance-tube fiche (ISO 10534-2), where it fixes the upper plane-wave cut-on frequency.
mic_spacing	Microphone spacing s between the two measurement positions of the impedance tube, in metres. Printed by the impedance-tube fiche (ISO 10534-2), where it bounds the working frequency range.
tube_shape	Cross-section of the impedance tube: "circular", "rectangular" or "square". Printed by the impedance-tube fiche (ISO 10534-2) next to the tube diameter, which it qualifies (inner diameter for a circular tube, maximum lateral dimension otherwise).
thickness	Specimen thickness under the applied static load, in metres. Printed by the dynamic-stiffness fiche (EN 29052-1 / ISO 9052-1), where EN 29052-1:1992 Clause 9 b) requires reporting the thickness of the resilient layer under load; it is shown in millimetres.
mounting	Mounting condition of the specimen (e.g. the ISO 10140-1 mounting code or a short description).
measurement_standard	Measurement standard the spectrum was obtained under (e.g. "ISO 10140-2" or "ISO 16283-1"); it forms the report’s standard-basis line together with the ISO 717 rating part.
test_date	Date of the test, as a free-form string.
laboratory	Testing laboratory / institute name (footer).
operator	Operator who carried out the test (footer signature line).
report_id	Report / test number (footer).
requirement	Target single-number value the verdict row compares the rating against, expressed in the rating’s own unit (e.g. dB, a dimensionless absorption coefficient, sone, or a programme-loudness level in LUFS). It need only be finite (a loudness target in LUFS is negative), so its sign is not constrained. The pass direction is defined by each rating’s report method: quantities where more is better (airborne insulation, absorption) pass at or above the requirement, and quantities where less is better (impact level, loudness, aircraft noise) pass at or below it; the programme-loudness fiche reads it as the target level and passes within a tolerance.
required_class	Target performance-class index for a class-compliance verdict (the IEC 61260-1 filter fiche): 0, 1 or 2, where class 0 is the strictest. When supplied, the fiche’s verdict passes if the achieved overall class is at least as strict as this class (a smaller or equal class index). None (the default) prints no verdict row.
notes	Free-form remarks printed in the footer.

Raises

Exception	When
ValueError	If a supplied dimension/mass/volume/pressure is not finite and strictly positive, a temperature or requirement is not finite, a relative humidity is outside 0..100 %, a required class is not one of 0, 1, 2, a position count is not a finite, positive integer, or a tube shape is not one of "circular", "rectangular", "square".

ReportMetadata.is_empty()

ReportMetadata.is_empty() -> bool

Return True when no field is set (an all-None instance).

weighted_impact_improvement

weighted_impact_improvement(delta_l: Sequence[float] | np.ndarray) -> int

Weighted reduction of impact sound pressure level ΔLw (ISO 717-2:2020 §5).

Relates a measured improvement spectrum ΔL to the heavyweight reference floor of Table 4: the reference level with the covering is Ln,r = Ln,r,0 − ΔL (Formula (1)) and the weighted improvement is ΔLw = Ln,r,0,w − Ln,r,w = 78 − Ln,r,w (Formula (2)), where Ln,r,w is the ISO 717-2 weighted rating of Ln,r from weighted_impact_rating.

Parameters

Name	Description
delta_l	The reduction of impact sound pressure level ΔL per band, in dB; 16 one-third-octave values from 100 Hz to 3150 Hz (e.g. from a floor-covering measurement to ISO 10140-3 or ISO 16251-1).

Returns: The weighted reduction ΔLw, in dB (rounded, per ISO 717-2).

Raises

Exception	When
ValueError	If delta_l is not 16 one-third-octave values, or is non-finite.

weighted_impact_rating

weighted_impact_rating(
    values_by_band: Sequence[float] | np.ndarray,
    bands: str | None = None,
) -> ImpactRatingResult

Single-number weighted impact rating and CI per ISO 717-2.

Applies the reference-curve method of Clause 4.3: the Table 3 impact reference curve is shifted in 1 dB steps towards the measured curve until the sum of unfavourable deviations is as large as possible but not more than 32,0 dB (16 one-third-octave bands, 100 Hz to 3150 Hz) or 10,0 dB (5 octave bands, 125 Hz to 2000 Hz). For impact sound an unfavourable deviation occurs where the measurement exceeds the reference (the sign opposite to ISO 717-1 airborne). The rating is the shifted reference read at 500 Hz; for octave bands it is then reduced by 5 dB (Clause 4.3.2). The spectrum adaptation term CI follows Clause A.2.1. Input values are first reduced to one decimal place (Clause 4.3.1, footnote 1).

The shift search reuses the verified engine of weighted_rating on the negated curves: minimising Σ max(0, measured - (ref + k)) over k equals maximising Σ max(0, (-ref) + (-k) - (-measured)), the airborne problem, so no separate search is duplicated.

Parameters

Name	Description
values_by_band	Measured impact levels (Ln, L'n, L'nT) in dB. 16 values are read as one-third-octave bands, 5 values as octave bands.
bands	"third-octave", "octave" or None to infer the band set from the number of values.

Returns: ImpactRatingResult with rating, ci and unfavourable_sum.

Raises

Exception	When
ValueError	If the number of values does not match the band set, or if any value is non-finite.

weighted_impact_rating_extended

weighted_impact_rating_extended(
    values_by_band: Sequence[float] | np.ndarray,
    frequencies: Sequence[float] | np.ndarray | None = None,
    *,
    one_decimal: bool = False,
) -> ExtendedImpactRatingResult

Weighted impact rating with CI,50-2500 (ISO 717-2:2020 A.2.1).

Computes the weighted impact rating from the core one-third-octave bands 100-3150 Hz (Clause 4.3) and, when the input covers 50-2500 Hz, the enlarged-range spectrum adaptation term CI,50-2500 of the A.2.1 NOTE: the energetic sum runs over 50-2500 Hz instead of 100-2500 Hz in Formula (A.1), CI = Ln,sum − 15 − Ln,w.

With one_decimal=True the reference-curve shift runs in 0,1 dB steps and the sums keep one decimal place (Clauses 4.3.1/4.4; e.g. the reference floor yields Ln,r,0,w = 77,6 dB and CI,r,0 = −10,3 dB as printed in A.2.2).

Parameters

Name	Description
values_by_band	Measured impact levels (Ln, L'n, L'nT) in dB, one-third-octave bands.
frequencies	Band centre frequencies, in Hz (one per value). None assumes exactly the 16 core bands 100-3150 Hz.
one_decimal	Use the 0,1 dB shift and one-decimal reductions.

Returns: An ExtendedImpactRatingResult.

Raises

Exception	When
ValueError	If the input is not one-dimensional and finite, the band counts differ, or the core bands are missing.

weighted_rating

weighted_rating(
    values_by_band: Sequence[float] | np.ndarray,
    bands: str | None = None,
) -> WeightedRatingResult

Single-number weighted rating and C / Ctr per ISO 717-1.

Applies the reference-curve method of Clause 4.4: the Table 3 reference curve is shifted in 1 dB steps towards the measured curve until the sum of unfavourable deviations is as large as possible but not more than 32,0 dB (16 one-third-octave bands, 100 Hz to 3150 Hz) or 10,0 dB (5 octave bands, 125 Hz to 2000 Hz). The rating is the shifted reference read at 500 Hz. The spectrum adaptation terms C and Ctr follow Clause 4.5 with the Table 4 spectra No. 1 and No. 2. Input values are first reduced to one decimal place (Clause 4.4, footnote 1).

Parameters

Name	Description
values_by_band	Measured band quantities (R, R', Dn, DnT …) in dB. 16 values are read as one-third-octave bands, 5 values as octave bands.
bands	"third-octave", "octave" or None to infer the band set from the number of values.

Returns: WeightedRatingResult with rating, c, ctr and unfavourable_sum.

Raises

Exception	When
ValueError	If the number of values does not match the band set, or if any value is non-finite.

weighted_rating_extended

weighted_rating_extended(
    values_by_band: Sequence[float] | np.ndarray,
    frequencies: Sequence[float] | np.ndarray | None = None,
    *,
    one_decimal: bool = False,
) -> ExtendedWeightedRatingResult

Weighted rating with enlarged-range adaptation terms (ISO 717-1 Annex B).

Computes the weighted rating from the core one-third-octave bands 100-3150 Hz (Clause 4.4) and, for every enlarged frequency range covered by the input, the additional spectrum adaptation terms of Annex B (C50-3150, C50-5000, C100-5000 and the Ctr counterparts) with the Table B.1 spectra: Cj = XAj − Xw where XAj sums over the bands of the enlarged range (Clause 4.5 with Annex B).

With one_decimal=True the reference-curve shift runs in 0,1 dB steps and every reduction keeps one decimal place; the variant Clauses 4.4/4.5 prescribe “for the expression of uncertainty” and ISO 12999-1:2020 Annex B requires for the uncertainty of single-number values.

Parameters

Name	Description
values_by_band	Measured band quantities (R, R', Dn, DnT …) in dB, one-third-octave bands.
frequencies	Band centre frequencies, in Hz (one per value). None assumes exactly the 16 core bands 100-3150 Hz. The 16 core bands must always be present; extended terms are formed for each Annex B range whose bands are all present.
one_decimal	Use the 0,1 dB shift and one-decimal reductions.

Returns: An ExtendedWeightedRatingResult.

Raises

Exception	When
ValueError	If the input is not one-dimensional and finite, the band counts differ, or the core bands are missing.

WeightedRatingResult

WeightedRatingResult(
    rating: int,
    c: int,
    ctr: int,
    unfavourable_sum: float,
    band_centers: np.ndarray | None = None,
    measured: np.ndarray | None = None,
    shifted_reference: np.ndarray | None = None,
    quantity: str = 'airborne',
)

Single-number weighted rating and adaptation terms (ISO 717-1).

Attributes

Name	Description
rating	Weighted rating (Rw, R'w, DnT,w …), the shifted reference read at 500 Hz, in dB (Clause 4.4). Integer.
c	Spectrum adaptation term C (spectrum No. 1), in dB (Clause 4.5). Integer.
ctr	Spectrum adaptation term Ctr (spectrum No. 2), in dB (Clause 4.5). Integer.
unfavourable_sum	Sum of unfavourable deviations at the final shift, in dB (Clause 4.4); at most 32,0 (16 bands) or 10,0 (5 bands).
band_centers	Band centre frequencies of the measured curve, in Hz. Defaults to None for backward-compatible construction.
measured	The measured band quantities used for the rating (after the one-decimal reduction of Clause 4.4), in dB. Defaults to None.
shifted_reference	Table 3 reference curve after the final shift, in dB. Defaults to None.
quantity	"airborne" (ISO 717-1, sound reduction index) or "impact" (ISO 717-2), selecting the labels of the ISO 717 Annex C report. Defaults to "airborne".

WeightedRatingResult.plot()

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

Plot the measured curve vs the shifted reference (ISO 717-1).

Unfavourable deviations (reference above measurement) are shaded and Rw (C; Ctr) annotated. Requires matplotlib (pip install phonometry[plot]); returns the Axes.

WeightedRatingResult.report()

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

Render an ISO 717-1 airborne sound-insulation fiche to a PDF.

Writes a one-page accredited-laboratory report: the standard-basis line, an optional metadata header block, the band table beside the measured-versus-shifted-reference plot (the result’s own plot), the boxed Rw (C; Ctr) result, an optional verdict row and a footer with the fixed disclaimer.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a prediction fiche (body, result and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table uses the ISO 717 Annex C columns (frequency, measured value, shifted reference, unfavourable deviation) instead of the two-column f | value table.
language	Fiche language: "en" (default, English) or "es" (Spanish, with a comma decimal separator).
symbol	The reported single-number quantity, as plain text: "Rw" (the default when None), "R'w", "Dn,w", "DnT,w" … per ISO 717-1 Tables 1-2, so a field measurement (e.g. a standardized level difference rated to DnT,w) is not mislabelled with the laboratory descriptor.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If engine is not "reportlab", symbol is not a valid quantity-symbol shape, or the result was built without the per-band data (band_centers, measured, shifted_reference).
ImportError	If reportlab is not installed (pip install phonometry[report]).