Skip to content

building.measurement.laboratory_insulation

Laboratory sound insulation of building elements (ISO 10140).

This is the laboratory counterpart of the field ISO 16283 family in phonometry.building.measurement.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, (Clause 3.1, Formula (2)) with the free test opening area S and the Sabine equivalent absorption area (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.building.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 (Clause 3.2, Formula (1)) with and the reference absorption area m². The single-number weighted rating Ln,w and the term CI follow ISO 717-2 (Clause 5.3) through phonometry.building.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 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(
signal_and_background: float | np.floating[Any] | np.integer[Any],
background: float | np.floating[Any] | np.integer[Any],
) -> float
background_correction(
signal_and_background: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
background: NumericArrayLike,
) -> NDArray[np.float64]
background_correction(
signal_and_background: float | np.floating[Any] | np.integer[Any],
background: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
background_correction(
signal_and_background: NumericArrayLike,
background: NumericArrayLike,
) -> float | NDArray[np.float64]

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:

  • dB: the background is negligible and the level is returned unchanged (Clause 4.3, quality requirement).
  • : the level is corrected with Formula (4), .
  • dB: the fixed 1.3 dB correction is applied (); such bands are the limit of measurement and a LaboratoryInsulationWarning is emitted (Clause 4.3). A negative margin (, i.e. background above the measured signal) falls in this branch and is likewise capped at : 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.emission.background_noise_correction (ISO 3744:2010): both apply the same energy subtraction , 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. A float when signal_and_background and background are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If the shapes differ or contain non-finite values.
TypeError if background or signal_and_background holds a text or a value that is not a real number.
laboratory_airborne_insulation(
l1: NumericArrayLike,
l2: NumericArrayLike,
t2: NumericArrayLike,
*,
area: float,
volume: float,
) -> LaboratoryAirborneInsulationResult

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

Computes, per frequency band, the sound reduction index (Clause 3.1, Formula (2)) with the free test opening area S and the Sabine equivalent absorption area (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.building.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: LaboratoryAirborneInsulationResult with r, absorption_area 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.
TypeError if area or volume is not a single number, or t2 holds a text or a value that is not a real number.
laboratory_impact_insulation(
li: NumericArrayLike,
t2: NumericArrayLike,
*,
volume: float,
) -> LaboratoryImpactInsulationResult

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

Computes, per frequency band, the normalized impact sound pressure level (Clause 3.2, Formula (1)) with the Sabine equivalent absorption area (ISO 10140-4:2010, Formula (5)) and the reference absorption area 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.building.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: LaboratoryImpactInsulationResult with l_n, absorption_area 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.
TypeError if volume is not a single number, or t2 holds a text or a value that is not a real number.
LaboratoryAirborneInsulationResult(
r: NDArray[np.float64],
absorption_area: NDArray[np.float64],
rating: WeightedRatingResult | None,
)

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

Attributes

Name Description
r Sound reduction index per band, in dB (Clause 3.1, Formula (2)).
absorption_area Equivalent sound absorption area 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.
LaboratoryAirborneInsulationResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**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 (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".

LaboratoryAirborneInsulationResult.report()

Section titled “LaboratoryAirborneInsulationResult.report()”
LaboratoryAirborneInsulationResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render an ISO 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 (the [report] extra), or matplotlib is missing for the embedded rating figure (the [plot] extra).
LaboratoryImpactInsulationResult(
l_n: NDArray[np.float64],
absorption_area: NDArray[np.float64],
rating: ImpactRatingResult | None,
)

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

Attributes

Name Description
l_n Normalized impact sound pressure level per band, in dB (Clause 3.2, Formula (1)).
absorption_area Equivalent sound absorption area 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.
LaboratoryImpactInsulationResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**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 (the [plot] extra); returns the Axes.

Parameters

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

Render an ISO 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 (the [report] extra), or matplotlib is missing for the embedded rating figure (the [plot] extra).

A laboratory insulation measurement at the limit of what it can show.

Emitted at the limit-of-measurement conditions of ISO 10140-4, and by the ISO 15186-1 element-normalized intensity difference when it counts more than one element unit, where it departs from the printed sign of Formula (8) (see docs/ERRATA.md).