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
Section titled “background_correction”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
LaboratoryInsulationWarningis 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 (orNaN) 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
Section titled “laboratory_airborne_insulation”laboratory_airborne_insulation( l1: NumericArrayLike, l2: NumericArrayLike, t2: NumericArrayLike, *, area: float, volume: float,) -> LaboratoryAirborneInsulationResultLaboratory 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
Section titled “laboratory_impact_insulation”laboratory_impact_insulation( li: NumericArrayLike, t2: NumericArrayLike, *, volume: float,) -> LaboratoryImpactInsulationResultLaboratory 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
Section titled “LaboratoryAirborneInsulationResult”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()
Section titled “LaboratoryAirborneInsulationResult.plot()”LaboratoryAirborneInsulationResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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',) -> strRender 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
Section titled “LaboratoryImpactInsulationResult”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()
Section titled “LaboratoryImpactInsulationResult.plot()”LaboratoryImpactInsulationResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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()
Section titled “LaboratoryImpactInsulationResult.report()”LaboratoryImpactInsulationResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender an ISO 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). |
LaboratoryInsulationWarning
Section titled “LaboratoryInsulationWarning”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).