building.measurement.floor_covering_improvement
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
Impact-sound improvement of floor coverings on a small mock-up (ISO 16251-1:2014).
Laboratory method for the improvement of impact sound insulation ΔL of a
soft, locally-reacting floor covering (carpet, PVC, linoleum; ISO 10140-1
Annex H category I) laid on a small concrete mock-up plate and excited by a
standard tapping machine. The two rooms of the ISO 10140 series are removed and
the floor is replaced by a softly-supported concrete plate; instead of the
receiving-room sound pressure level, the structure-borne acceleration level
on the underside of the plate is measured with and without the covering. For
locally-reacting coverings this acceleration-level difference equals the ISO
10140 impact sound reduction (Clause 4).
Acceleration level (Formula (1)). dB, with the reference acceleration m/s², i.e. .
Background correction (Formula (2)). Each measured level L' is
corrected against the background Lb per accelerometer position, by the
margin : unchanged for dB; energy
subtraction for
dB; and the fixed dB limit
for dB. Bands hitting the 1.3 dB limit are flagged as the limit of
measurement (reported as ). This differs from the ISO
10140-4 correction (phonometry.building.background_correction) only at
exactly dB.
Improvement (Formulae (3)/(4)). The per-position difference is (0 = bare plate, 1 = specimen) and the improvement is their arithmetic mean over all tapping-machine (t) and accelerometer (a) positions, .
Octave bands (Formula (5)). dB from the three one-third-octave values in each octave.
Weighted improvement. ΔLw is the ISO 717-2 weighted reduction of impact
sound pressure level (Clause 6.5), computed with the heavyweight reference
floor via phonometry.building.weighted_impact_improvement on the 16
rating bands 100 Hz to 3150 Hz; a wider clause 6.3 spectrum (18 bands 100-5000
Hz, optionally extended to 50 Hz) is rated on that sub-range. The statement of
results (Clause 8 e)) also carries the spectrum adaptation term CI,Δ (ISO
717-2:2020 Formula (A.4)) via
phonometry.building.impact_improvement_adaptation_term.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
acceleration_level
Section titled “acceleration_level”acceleration_level( acceleration: float | np.floating[Any] | np.integer[Any], *, reference: float = ...,) -> float
acceleration_level( acceleration: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, reference: float = ...,) -> NDArray[np.float64]
acceleration_level( acceleration: NumericArrayLike, *, reference: float = ...,) -> float | NDArray[np.float64]Vibratory acceleration level La (ISO 16251-1 Formula (1)).
dB.
Parameters
| Name | Description |
|---|---|
acceleration |
RMS acceleration a_rms per band, in m/s² (> 0). |
reference |
Reference acceleration a0, in m/s² (default 1e-6). |
Returns: The acceleration level La per band, in dB. A float for a number, an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | Non-finite or non-positive acceleration, or a non-positive reference. |
| TypeError | if reference is not a single number, or acceleration holds a text or a value that is not a real number. |
background_corrected_level
Section titled “background_corrected_level”background_corrected_level( signal_and_background: NumericArrayLike, background: NumericArrayLike, *, frequencies: NumericArrayLike | None = None,) -> BackgroundCorrectedLevelCorrect a measured level for background noise (ISO 16251-1 F. (2)).
Parameters
| Name | Description |
|---|---|
signal_and_background |
Measured level L' (with background) per band, in dB; a (positions, bands) array is corrected position by position. |
background |
Background-noise level Lb per band, in dB, of the same shape. |
frequencies |
The band centre frequencies, in Hz, one per band, for the plot to name the bands by; None (the default) numbers them. |
Returns: The correction, as a BackgroundCorrectedLevel: the corrected levels L in its corrected_levels, and in its limited the bands at the 1.3 dB limit of measurement (report as ).
Raises
| Exception | When |
|---|---|
| ValueError | Mismatched shapes, non-finite values, or band frequencies that are not one positive value per band. |
| TypeError | if background, frequencies or signal_and_background holds a text or a value that is not a real number. |
BackgroundCorrectedLevel
Section titled “BackgroundCorrectedLevel”BackgroundCorrectedLevel( signal_and_background: NDArray[np.float64], background: NDArray[np.float64], *, frequencies: NDArray[np.float64] | None = None,)A measured level corrected for background noise (ISO 16251-1 F. (2)).
At a margin of 15 dB or more the level is used unchanged; between 6 dB and 15 dB the background is subtracted in energy; under 6 dB the correction is held at 1.3 dB, the limit of measurement, and the band is reported as . The margins, the corrected levels and the bands at the limit are read from the two readings, so they are not fields: a record cannot be built to claim a band clear of the limit that its readings put on it.
Attributes
| Name | Description |
|---|---|
signal_and_background |
Measured level L' (with background), in dB; one value per band, or a (positions, bands) array. |
background |
Background-noise level Lb, in dB, of the same shape. |
frequencies |
The band centre frequencies, in Hz, one per band (the last axis of the readings), or None where the bands were not named; only the plot reads them. |
BackgroundCorrectedLevel.corrected_levels
Section titled “BackgroundCorrectedLevel.corrected_levels”property
The corrected levels L, in dB, in the shape of the readings.
BackgroundCorrectedLevel.limited
Section titled “BackgroundCorrectedLevel.limited”property
Where the margin is under 6 dB, so the band is at the limit of measurement.
Judged settled: 32.3 - 26.3 dB is 5.999 999 999 999 996 in binary and still the 6 dB it is.
BackgroundCorrectedLevel.margins_db
Section titled “BackgroundCorrectedLevel.margins_db”property
, in dB, in the shape of the readings.
BackgroundCorrectedLevel.plot()
Section titled “BackgroundCorrectedLevel.plot()”BackgroundCorrectedLevel.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the margin of each band against the criterion.
The bands at 15 dB or more are used unchanged, those between 6 dB and 15 dB have the background subtracted in energy, and those under 6 dB are held at the 1.3 dB limit of measurement; the two boundaries are drawn across the bands and the three regimes are told apart. A (positions, bands) record draws one line per position.
Requires matplotlib (the [plot] extra).
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the margin bars, or to the line of each position. |
Returns: The axes.
FloorCoveringImprovementResult
Section titled “FloorCoveringImprovementResult”FloorCoveringImprovementResult( frequencies: NDArray[np.float64], improvement: NDArray[np.float64], delta_lw: int | None, ci_delta: int | None = None, background_margin_db: NDArray[np.float64] | None = None,)Impact-sound improvement of a floor covering (ISO 16251-1).
Attributes
| Name | Description |
|---|---|
frequencies |
One-third-octave band centre frequencies, in Hz. |
improvement |
Improvement of impact sound insulation ΔL per band, in dB. |
delta_lw |
Weighted improvement ΔLw (ISO 717-2), in dB, or None when the spectrum does not contain the 16 one-third-octave rating bands 100-3150 Hz. A wider clause 6.3 spectrum (e.g. the 18 bands 100-5000 Hz, optionally extended down to 50 Hz) is rated on its 100-3150 Hz sub-range. |
ci_delta |
Spectrum adaptation term CI,Δ (ISO 717-2:2020 Formula (A.4); required in the ISO 16251-1 Clause 8 e) statement of results), in dB, or None when delta_lw is None. |
background_margin_db |
Per band, the smallest margin of a measured level over the background, over every position and both floors (Formula (2)), in dB; None when no background correction was applied. limited is read from it and the 6 dB of Formula (2), so it is not a field. |
FloorCoveringImprovementResult.limited
Section titled “FloorCoveringImprovementResult.limited”property
Per band, whether a position reached the 1.3 dB limit of measurement.
True where the smallest margin over the background fell below the
6 dB of Formula (2), so the band is reported as ; all
False when no background correction was applied. The margin is
judged settled, as Formula (2) itself is.
FloorCoveringImprovementResult.octave_bands()
Section titled “FloorCoveringImprovementResult.octave_bands()”FloorCoveringImprovementResult.octave_bands() -> OctaveBandSpectrumΔLoct in octave bands, via Formula (5) (needs whole octave triplets).
FloorCoveringImprovementResult.plot()
Section titled “FloorCoveringImprovementResult.plot()”FloorCoveringImprovementResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the improvement spectrum ΔL (with ΔLw when available).
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
FloorCoveringImprovementResult.report()
Section titled “FloorCoveringImprovementResult.report()”FloorCoveringImprovementResult.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 16251-1 impact-improvement test-report fiche to PDF.
Writes a one-page accredited report (BS EN ISO 16251-1:2014, the
small-mock-up laboratory method for the reduction of transmitted impact
sound by soft floor coverings): the standard-basis line, an optional
metadata header block, a two-panel body with the per-band table
(frequency and the reduction of impact sound pressure level ΔL,
bands at the 1.3 dB limit of measurement prefixed >) beside the
ΔL(f) improvement curve, a boxed single-number weighted improvement
ΔLw (CI,Δ) (ISO 717-2, the Clause 8 e) statement of results; a
characterisation headline replaces it when the spectrum lacks the 16
rating bands 100-3150 Hz), an optional verdict row and a footer.
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 (the floor covering under test), mounting, mass_per_area, test_room, test_date, temperature_c, pressure, measurement_standard, laboratory, operator, report_id and notes. The bare reference floor is the standardised heavyweight floor of ISO 717-2:2020 Table 4, fixed by the standard. When requirement is set the fiche adds a verdict row (a higher weighted improvement is better, so the result passes at or above the requirement). |
engine |
Rendering back end; only "reportlab" is supported. |
verbose |
When True, the per-band table gains the reference-floor-with-covering column (ISO 717-2:2020 Formula (1)), the derivation basis of ΔLw, when the spectrum is exactly the 16 rating bands 100-3150 Hz. |
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 (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra). |
impact_improvement
Section titled “impact_improvement”impact_improvement( bare: NumericArrayLike, with_covering: NumericArrayLike, *, frequencies: NumericArrayLike, background: NumericArrayLike | None = None,) -> FloorCoveringImprovementResultImprovement of impact sound insulation ΔL of a floor covering.
ISO 16251-1. The acceleration levels without (L0) and with (L1)
the specimen may be
given either as one value per band (already averaged over the
tapping-machine
and accelerometer positions) or, for the raw measurement, as a
(positions, bands) array. The standard’s order of operations is
followed:
the background correction (Formula (2)) is applied per position, then
the
level difference (Formula (3)), then
the arithmetic mean
over positions
(Formula (4)), necessary because Formula
(2) is non-linear, so correcting must precede averaging.
Parameters
| Name | Description |
|---|---|
bare |
Bare-plate acceleration level L0, in dB; (bands,) or (positions, bands). |
with_covering |
Level with the specimen L1, in dB; same shape as bare. |
frequencies |
One-third-octave band centre frequencies, in Hz ((bands,)). |
background |
Optional background-noise level Lb, in dB; (bands,) (applied to every position) or (positions, bands). When given, L0 and L1 are background-corrected (Formula (2)) per position before the difference, and bands where any position hits the 1.3 dB limit are flagged. |
Returns: FloorCoveringImprovementResult (ΔL per band).
Raises
| Exception | When |
|---|---|
| ValueError | Mismatched shapes or non-finite values. |
| TypeError | if background, bare, frequencies or with_covering holds a text or a value that is not a real number. |
improvement_octave_bands
Section titled “improvement_octave_bands”improvement_octave_bands( improvement: NumericArrayLike, *, frequencies: NumericArrayLike, quantity: Literal['ΔL', 'ΔR', 'Rs'] = 'ΔL',) -> OctaveBandSpectrumConvert a one-third-octave improvement spectrum to octaves (F. (5)).
dB over the three thirds of each octave.
Parameters
| Name | Description |
|---|---|
improvement |
Improvement ΔL per one-third-octave band, in dB. |
frequencies |
The matching one-third-octave centre frequencies, in Hz; must contain whole octave triplets (centre / centre·2^(±1/3)). |
quantity |
What the values are, for the record and its plot: "ΔL" (Default), "ΔR" or "Rs", the three quantities folded into octaves by this average of transmitted power. The rainfall sound intensity levels, the "LI" and "LI,norm" an OctaveBandSpectrum holds too, are not offered: ISO 10140-1 Formula (K.3) sums their energy, which RainfallSoundResult.octave_bands does. |
Returns: An OctaveBandSpectrum with the octave centres (.frequencies) and the octave values (.values).
Raises
| Exception | When |
|---|---|
| ValueError | The thirds do not group into complete octave triplets, or quantity is not one of the three, "LI" and "LI,norm" among them. |
| TypeError | if quantity is not a text, or frequencies or improvement holds a text or a value that is not a real number. |
OctaveBandSpectrum
Section titled “OctaveBandSpectrum”OctaveBandSpectrum( frequencies: NDArray[np.float64], values: NDArray[np.float64], quantity: Literal['ΔL', 'ΔR', 'Rs', 'LI', 'LI,norm'],)A one-third-octave result folded into octave bands, with what it holds.
What improvement_octave_bands returns, and what the
octave_bands() methods of the floor-covering, laboratory lining,
laboratory floor-covering, joint and rainfall results return: the octave
centres and the octave values side by side, named, so that neither can be
read as the other, and the quantity they are values of.
Attributes
| Name | Description |
|---|---|
frequencies |
The octave centre frequencies, in hertz. |
values |
The octave value of quantity in each band, in dB. |
quantity |
Which quantity the values are: "ΔL" (an impact improvement), "ΔR" (a sound reduction improvement), "Rs" (the sound reduction index of a joint), "LI" or "LI,norm" (the rainfall sound intensity level, raw or normalized). |
OctaveBandSpectrum.plot()
Section titled “OctaveBandSpectrum.plot()”OctaveBandSpectrum.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the octave values against their octave bands.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the octave curve plot call. |