building.lab_insulation

Laboratory sound insulation of building elements (ISO 10140).

This is the laboratory counterpart of the field ISO 16283 family in phonometry.insulation. In a qualified test facility flanking transmission is suppressed, so the direct airborne sound reduction index R (not the apparent R') is the primary quantity, and the receiving room’s equivalent absorption area A is a property of the known facility.

Airborne sound reduction index (ISO 10140-2:2010). From the energy-average sound pressure levels in the source room L1 and receiving room L2 this module forms, per one-third-octave band, R = L1 - L2 + 10 lg(S/A) (Clause 3.1, Formula (2)) with the free test opening area S and the Sabine equivalent absorption area A = 0,16 V / T (ISO 10140-4:2010, Clause 4.6.3, Formula (5)). The single-number weighted rating Rw and the adaptation terms C / Ctr follow ISO 717-1 (Clause 5.3) through the verified phonometry.weighted_rating engine, reused unchanged.

Impact sound pressure level (ISO 10140-3:2010). With the standard tapping machine exciting the floor under test this module forms, from the energy-average impact sound pressure level Li in the receiving room, the normalized impact sound pressure level Ln = Li + 10 lg(A/A0) (Clause 3.2, Formula (1)) with A = 0,16 V / T and the reference absorption area A0 = 10 m². The single-number weighted rating Ln,w and the term CI follow ISO 717-2 (Clause 5.3) through phonometry.weighted_impact_rating, reused unchanged.

Background-noise correction (ISO 10140-4:2010, Clause 4.3, Formula (4)). The receiving-room levels must be corrected for background noise before the insulation is formed. background_correction implements the correction L = 10 lg(10^(Lsb/10) - 10^(Lb/10)) for a signal-to-background margin between 6 dB and 15 dB, the fixed 1,3 dB correction (limit of measurement) for a margin of 6 dB or less, and no correction for a margin of 15 dB or more. The 6/15 dB criteria are the laboratory analogue of the 6/10 dB criteria of ISO 16283-1 Clause 9.2; both cap the correction at 1,3 dB.

Frequency range (ISO 10140-4:2010, Clause 4.1). Quantities are measured over the mandatory one-third-octave range 100 Hz to 5000 Hz (optionally down to 50 Hz). The single-number rating uses the core 100 Hz to 3150 Hz (16 one-third-octave bands) / 125 Hz to 2000 Hz (5 octave bands) range of ISO 717-1/2, so the automatic rating is formed only when exactly 16 or 5 per-band values are supplied.

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

background_correction

background_correction(
    signal_and_background: Sequence[float] | np.ndarray,
    background: Sequence[float] | np.ndarray,
) -> np.ndarray

Correct receiving-room levels for background noise (ISO 10140-4:2010).

Applies the correction of Clause 4.3 per band from the combined signal-plus-background level Lsb and the background level Lb, using the margin Lsb - Lb:

• margin >= 15 dB: the background is negligible and the level is returned unchanged (Clause 4.3, quality requirement).
• 6 dB < margin < 15 dB: the level is corrected with Formula (4), L = 10 lg(10^(Lsb/10) - 10^(Lb/10)).
• margin <= 6 dB: the fixed 1,3 dB correction is applied (L = Lsb - 1,3); such bands are the limit of measurement and a LabInsulationWarning is emitted (Clause 4.3). A negative margin (Lb > Lsb, i.e. background above the measured signal) falls in this branch and is likewise capped at Lsb - 1,3: the band is simply flagged as the limit of measurement rather than yielding a nonsensical (or NaN) corrected level.

This is the sound-insulation counterpart of phonometry.background_noise_correction (ISO 3744:2010): both apply the same energy subtraction 10 lg(10^(Lsb/10) - 10^(Lb/10)), but that routine returns the correction offset K1 (to subtract from Lsb), whereas this one returns the already-corrected levels L directly.

Parameters

Name	Description
signal_and_background	Combined signal-plus-background levels Lsb per band, in dB.
background	Background-noise levels Lb per band, in dB.

Returns: The background-corrected levels per band, in dB.

Raises

Exception	When
ValueError	If the shapes differ or contain non-finite values.

lab_airborne_insulation

lab_airborne_insulation(
    l1: Sequence[float] | np.ndarray,
    l2: Sequence[float] | np.ndarray,
    t2: Sequence[float] | np.ndarray,
    *,
    area: float,
    volume: float,
) -> LabAirborneInsulationResult

Laboratory airborne sound reduction index per ISO 10140-2:2010.

Computes, per frequency band, the sound reduction index R = L1 - L2 + 10 lg(S/A) (Clause 3.1, Formula (2)) with the free test opening area S and the Sabine equivalent absorption area A = 0,16 V / T (ISO 10140-4:2010, Formula (5)). When exactly 16 one-third-octave (100-3150 Hz) or 5 octave (125-2000 Hz) values are supplied, the single-number weighted rating Rw with C / Ctr is also formed via phonometry.weighted_rating (ISO 717-1).

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 (ISO 10140-4:2010, Formula (2)). The band levels are assumed already corrected for background noise (see background_correction).

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 free test opening, in m².
volume	Receiving-room volume V, in m³.

Returns: LabAirborneInsulationResult with r, absorption and rating.

Raises

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

lab_impact_insulation

lab_impact_insulation(
    li: Sequence[float] | np.ndarray,
    t2: Sequence[float] | np.ndarray,
    *,
    volume: float,
) -> LabImpactInsulationResult

Laboratory impact sound pressure level per ISO 10140-3:2010.

Computes, per frequency band, the normalized impact sound pressure level Ln = Li + 10 lg(A/A0) (Clause 3.2, Formula (1)) with the Sabine equivalent absorption area A = 0,16 V / T (ISO 10140-4:2010, Formula (5)) and the reference absorption area A0 = 10 m². When exactly 16 one-third-octave (100-3150 Hz) or 5 octave (125-2000 Hz) values are supplied, the single-number weighted rating Ln,w with CI is also formed via phonometry.weighted_impact_rating (ISO 717-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 (ISO 10140-4:2010, Formula (2)). The band levels are assumed already corrected for background noise (see background_correction).

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

Returns: LabImpactInsulationResult with l_n, absorption and rating.

Raises

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

LabAirborneInsulationResult

LabAirborneInsulationResult(
    r: np.ndarray,
    absorption: np.ndarray,
    rating: WeightedRatingResult | None,
)

Per-band laboratory airborne sound insulation (ISO 10140-2:2010).

Attributes

Name	Description
r	Sound reduction index R = L1 - L2 + 10 lg(S/A) per band, in dB (Clause 3.1, Formula (2)).
absorption	Equivalent sound absorption area A = 0,16 V / T per band, in m² (ISO 10140-4:2010, Formula (5)).
rating	Single-number weighted rating Rw with C / Ctr (ISO 717-1), or None when the number of bands is neither 16 (one-third octave) nor 5 (octave) and no rating can be formed.

LabAirborneInsulationResult.plot()

LabAirborneInsulationResult.plot(
    ax: Axes | None = None,
    **kwargs: Any,
) -> Axes

Plot R against the shifted ISO 717-1 reference curve.

Delegates to the weighted-rating plot (measured R versus the shifted reference, unfavourable deviations shaded). Requires the automatic rating to be available (16 or 5 bands) and matplotlib (pip install phonometry[plot]); returns the Axes.

LabAirborneInsulationResult.report()

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

Render an ISO 10140-2 laboratory airborne-insulation report to a PDF.

Writes the one-page laboratory test report of ISO 10140-2:2010: the standard-basis line, an optional metadata header block (client, specimen, mounting, room volumes, climatic conditions …), the band table (16 one-third-octave or 5 octave bands) beside the measured-versus-shifted-reference curve, the boxed laboratory rating Rw (C; Ctr) (evaluated per ISO 717-1), the laboratory-method statement, an optional verdict row and a footer with the identity block and disclaimer. The report requires the single-number rating to be present on the result; it is formed automatically only for exactly 16 one-third-octave (100 Hz to 3150 Hz) or 5 octave (125 Hz to 2000 Hz) bands, and a result carrying no rating (any other band count) is rejected.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a lightweight fiche (body, rating, statement and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table annexes the per-band equivalent sound absorption area A beside the reported R.
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 is unknown, language is not one of the supported values, or the result carries no single-number rating (its band count is neither 16 one-third-octave nor 5 octave, so the ISO 717-1 rating the fiche needs was not formed).
ImportError	If reportlab is not installed (pip install phonometry[report]), or matplotlib is missing for the embedded rating figure (pip install phonometry[plot]).

LabImpactInsulationResult

LabImpactInsulationResult(
    l_n: np.ndarray,
    absorption: np.ndarray,
    rating: ImpactRatingResult | None,
)

Per-band laboratory impact sound insulation (ISO 10140-3:2010).

Attributes

Name	Description
l_n	Normalized impact sound pressure level Ln = Li + 10 lg(A/A0) per band, in dB (Clause 3.2, Formula (1)).
absorption	Equivalent sound absorption area A = 0,16 V / T per band, in m² (ISO 10140-4:2010, Formula (5)).
rating	Single-number weighted rating Ln,w with CI (ISO 717-2), or None when the number of bands is neither 16 (one-third octave) nor 5 (octave) and no rating can be formed.

LabImpactInsulationResult.plot()

LabImpactInsulationResult.plot(
    ax: Axes | None = None,
    **kwargs: Any,
) -> Axes

Plot Ln against the shifted ISO 717-2 reference curve.

Delegates to the weighted impact-rating plot. Requires the automatic rating to be available (16 or 5 bands) and matplotlib (pip install phonometry[plot]); returns the Axes.

LabImpactInsulationResult.report()

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

Render an ISO 10140-3 laboratory impact-insulation report to a PDF.

Writes the one-page laboratory test report of ISO 10140-3:2010: the standard-basis line, an optional metadata header block, the band table (16 one-third-octave or 5 octave bands) beside the measured-versus-shifted-reference curve, the boxed laboratory rating Ln,w (CI) (evaluated per ISO 717-2), the laboratory-method statement, an optional verdict row and a footer with the identity block and disclaimer. The report requires the single-number rating to be present on the result; it is formed automatically only for exactly 16 one-third-octave (100 Hz to 3150 Hz) or 5 octave (125 Hz to 2000 Hz) bands, and a result carrying no rating (any other band count) is rejected.

Parameters

Name	Description
path	Destination path of the PDF file.
metadata	Optional ReportMetadata; None produces a lightweight fiche (body, rating, statement and disclaimer only).
engine	Rendering back end; only "reportlab" is supported.
verbose	When True, the table annexes the per-band equivalent sound absorption area A beside the reported Ln.
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 is unknown, language is not one of the supported values, or the result carries no single-number rating (its band count is neither 16 one-third-octave nor 5 octave, so the ISO 717-2 rating the fiche needs was not formed).
ImportError	If reportlab is not installed (pip install phonometry[report]), or matplotlib is missing for the embedded rating figure (pip install phonometry[plot]).

LabInsulationWarning

Warning for laboratory-insulation limit-of-measurement conditions.