Ir al contenido

building.measurement.ratings

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.

Single-number weighted ratings of sound insulation and their spectrum adaptation terms (ISO 717-1 airborne, ISO 717-2 impact).

ISO 717 rates a curve, not a room. Whatever produced the band values (a field measurement to ISO 16283, a laboratory measurement to ISO 10140, a prediction to ISO 12354), both parts of ISO 717 reduce them to a single number by the same reference-curve method: one shift search, one pair of deviation bounds, one rounding rule, run against the airborne reference curve of ISO 717-1 or the impact reference curve of ISO 717-2, whose only structural difference is the sign an unfavourable deviation has. That shared machinery, with the Table 3 reference curves and the Table 4 / Table B.1 spectra it reads, is the subject of this module.

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 and with 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.

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

Improvements rated on a reference element (ISO 717-2:2020 Clauses 5 and 6, ISO 717-1:2020 Annex D). A floor covering and a lining are rated on a standard element rather than on the floor or wall they were measured on, so that the single number describes the product and not the laboratory. The measured improvement is added to (subtracted from) the reference curve of the element, the two curves are rated, and the improvement is the difference of the two ratings: ΔLw on the heavyweight floor and ΔLt,w on the three lightweight floors of Table 4 (IMPACT_REFERENCE_FLOORS), and ΔRw with Δ(Rw + C) and Δ(Rw + Ctr) on the heavy wall, the heavy floor and the lightweight wall of Table E.1 (LINING_REFERENCE_ELEMENTS). Both tables were printed in ISO 10140-5:2010 (Tables C.1 and B.1); its 2021 edition keeps the constructions and refers to ISO 717 for the curves.

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

ExtendedImpactRatingResult(
rating: float,
ci: float,
ci_50_2500: float | None,
core: ImpactRatingResult,
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
)

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).
frequencies Band centre frequencies of the full (enlarged-range) measured curve, in Hz.
measured The measured impact levels over the full enlarged range (after the one-decimal reduction of Clause 4.3), in dB.
ExtendedImpactRatingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
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,
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
)

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.
frequencies Band centre frequencies of the full (enlarged-range) measured curve, in Hz.
measured The measured band quantities over the full enlarged range (after the one-decimal reduction of Clause 4.4), in dB.
ExtendedWeightedRatingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
impact_improvement_adaptation_term(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: Literal[False] = ...,
) -> int
impact_improvement_adaptation_term(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: Literal[True],
) -> float
impact_improvement_adaptation_term(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: bool = ...,
) -> int | float

Adaptation term CI,Δ or CIΔ,t of a floor covering (ISO 717-2:2020).

(Formula (A.4)) on the heavyweight floor, with dB, and (Formula (A.6)) on a lightweight one, with of 0 dB for floors No 1 and No 2 and -3 dB for No 3. CI,r is the ISO 717-2 spectrum adaptation term of the reference floor with the covering under test, (Formula (1)). Together with weighted_impact_improvement it yields the single-number reduction for a flat spectrum, (Formula (A.5), or (A.7) on a lightweight floor). ISO 16251-1 Clause 8 e) and ISO 10140-1:2021 H.5 h) require this term in the statement of results.

With one_decimal=True both terms keep one decimal place, which gives CI,r,0 = -10.3 dB and CI,t,r,0 of 0.0 and -2.8 dB as A.2.2 and A.2.3 print.

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, or a mapping of band centre frequency in hertz to ΔL that holds those 16 bands, other keys not read.
reference_floor "heavyweight" (default), "lightweight_1", "lightweight_2" or "lightweight_3".
one_decimal Use the 0.1 dB shift and one-decimal reductions.

Returns: The spectrum adaptation term, in dB: an integer, or a value to one decimal place when one_decimal is set.

Raises

Exception When
ValueError If delta_l is not 16 finite one-third-octave values, a mapping lacks one of them, or reference_floor is not one of the four floors.
TypeError if reference_floor is not a text, or delta_l holds a text or a value that is not a real number.

Constant (mapping).

IMPACT_REFERENCE_FLOORS = {'heavyweight': {100.0: 67.0, 125.0: 67.5, 160.0: 68.0, 200.0: 68.5, 250.0: 69.0, 315.0: 69.5, 400.0: 70.0, 500.0: 70.5, 630.0: 71.0, 800.0: 71.5, 1000.0: 72.0, 1250.0: 72.0, 1600.0: 72.0, 2000.0: 72.0, 2500.0: 72.0, 3150.0: 72.0}, 'lightweight_1': {100.0: 78.0, 125.0: 78.0, 160.0: 78.0, 200.0: 78.0, 250.0: 78.0, 315.0: 78.0, 400.0: 76.0, 500.0: 74.0, 630.0: 72.0, 800.0: 69.0, 1000.0: 66.0, 1250.0: 63.0, 1600.0: 60.0, 2000.0: 57.0, 2500.0: 54.0, 3150.0: 51.0}, 'lightweight_2': {100.0: 78.0, 125.0: 78.0, 160.0: 78.0, 200.0: 78.0, 250.0: 78.0, 315.0: 78.0, 400.0: 76.0, 500.0: 74.0, 630.0: 72.0, 800.0: 69.0, 1000.0: 66.0, 1250.0: 63.0, 1600.0: 60.0, 2000.0: 57.0, 2500.0: 54.0, 3150.0: 51.0}, 'lightweight_3': {100.0: 69.0, 125.0: 72.0, 160.0: 75.0, 200.0: 78.0, 250.0: 78.0, 315.0: 78.0, 400.0: 78.0, 500.0: 78.0, 630.0: 78.0, 800.0: 76.0, 1000.0: 74.0, 1250.0: 72.0, 1600.0: 69.0, 2000.0: 66.0, 2500.0: 63.0, 3150.0: 60.0}}
ImpactImprovementRatingResult(
delta_lw: int,
ci_delta: int,
ci_r: int,
frequencies: NDArray[np.float64],
improvement: NDArray[np.float64],
)

The weighted reduction of impact level of a covering, with its terms.

ISO 717-2:2020 rates the reduction of impact sound pressure level of a floor covering against the heavyweight reference floor of its Table 4: from Formulae (1) and (2), and the adaptation terms of Clause A.2.2, where (Formula (A.4)) with dB. A data sheet of a covering or a resilient layer prints and one of the two terms, so both are here.

Attributes

Name Description
delta_lw The weighted reduction of impact sound pressure level , in dB, from weighted_impact_improvement. Integer.
ci_delta The spectrum adaptation term , in dB, from impact_improvement_adaptation_term. Integer.
ci_r The spectrum adaptation term of the reference floor with the covering, in dB, which is . Integer.
frequencies The 16 one-third-octave centre frequencies rated, 100 Hz to 3150 Hz.
improvement in those bands, in dB, as given.
ImpactImprovementRatingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the improvement spectrum with its rating (ISO 717-2).

Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
ImpactRatingResult(
rating: int,
ci: int,
unfavorable_sum: float,
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
shifted_reference: NDArray[np.float64],
quantity: Literal['impact'] = '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.
unfavorable_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). Restates measured against shifted_reference, with the impact sign, and is checked against them.
frequencies Band centre frequencies of the measured curve, in Hz.
measured The measured impact levels used for the rating (after the one-decimal reduction of Clause 4.3.1), in dB.
shifted_reference Table 3 impact reference curve after the final shift, in dB.
quantity Always "impact" (ISO 717-2), selecting the impact labels of the ISO 717 Annex C report.
ImpactRatingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
ImpactRatingResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = '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 (frequencies, measured, shifted_reference).
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).

Constant (mapping).

LINING_REFERENCE_ELEMENTS = {'heavy_wall': {50.0: 35.3, 63.0: 37.3, 80.0: 39.4, 100.0: 40.0, 125.0: 40.0, 160.0: 40.0, 200.0: 40.0, 250.0: 41.0, 315.0: 43.5, 400.0: 46.1, 500.0: 48.5, 630.0: 51.0, 800.0: 53.6, 1000.0: 56.0, 1250.0: 58.4, 1600.0: 61.1, 2000.0: 63.6, 2500.0: 65.0, 3150.0: 65.0, 4000.0: 65.0, 5000.0: 65.0}, 'heavy_floor': {50.0: 34.0, 63.0: 36.0, 80.0: 38.1, 100.0: 40.0, 125.0: 40.0, 160.0: 40.0, 200.0: 40.0, 250.0: 40.0, 315.0: 41.8, 400.0: 44.4, 500.0: 46.8, 630.0: 49.3, 800.0: 51.9, 1000.0: 54.4, 1250.0: 56.8, 1600.0: 59.5, 2000.0: 61.9, 2500.0: 64.3, 3150.0: 65.0, 4000.0: 65.0, 5000.0: 65.0}, 'lightweight_wall': {50.0: 21.3, 63.0: 23.3, 80.0: 25.3, 100.0: 27.0, 125.0: 27.0, 160.0: 27.0, 200.0: 27.0, 250.0: 27.0, 315.0: 27.0, 400.0: 27.0, 500.0: 27.0, 630.0: 28.0, 800.0: 30.5, 1000.0: 32.8, 1250.0: 35.1, 1600.0: 37.6, 2000.0: 40.0, 2500.0: 42.3, 3150.0: 44.6, 4000.0: 47.1, 5000.0: 49.4}}
ReductionImprovementRating(
basic_element: Literal['heavy_wall', 'heavy_floor', 'lightweight_wall'],
delta_rw: float,
delta_rw_c: float,
delta_rw_ctr: float,
delta_rw_c_50_3150: float | None,
delta_rw_c_50_5000: float | None,
delta_rw_c_100_5000: float | None,
delta_rw_ctr_50_3150: float | None,
delta_rw_ctr_50_5000: float | None,
delta_rw_ctr_100_5000: float | None,
without_lining: ExtendedWeightedRatingResult,
with_lining: ExtendedWeightedRatingResult,
)

Single-number improvement of the sound reduction index by a lining.

The rating of ISO 717-1:2020 Annex D: the measured ΔR is added to the reference curve of a standard basic element, (Formula (D.3)), both curves are rated, and each improvement is the difference of the two ratings (Formula (D.4)). Every value is an integer unless the rating was computed with one_decimal=True. An enlarged-range term is None when ΔR did not cover its bands.

Attributes

Name Description
basic_element "heavy_wall", "heavy_floor" or "lightweight_wall".
delta_rw ΔRw, in dB.
delta_rw_c Δ(Rw + C), in dB.
delta_rw_ctr Δ(Rw + Ctr), in dB.
delta_rw_c_50_3150 Δ(Rw + C50-3150), in dB, or None.
delta_rw_c_50_5000 Δ(Rw + C50-5000), in dB, or None.
delta_rw_c_100_5000 Δ(Rw + C100-5000), in dB, or None.
delta_rw_ctr_50_3150 Δ(Rw + Ctr,50-3150), in dB, or None.
delta_rw_ctr_50_5000 Δ(Rw + Ctr,50-5000), in dB, or None.
delta_rw_ctr_100_5000 Δ(Rw + Ctr,100-5000), in dB, or None.
without_lining The rating of Rref,without, the bare reference curve over the bands ΔR was given in.
with_lining The rating of Rref,with.

property

The element index of ISO 717-1:2020 D.3: "heavy" or "light".

ReductionImprovementRating.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot Rref,without and Rref,with with the improvement ratings.

Draws the reference curve of the basic element and the same curve raised by the measured ΔR, the two curves Annex D rates; the title carries ΔRw, Δ(Rw + C) and Δ(Rw + Ctr) with the element index. Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
weighted_impact_improvement(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: Literal[False] = ...,
) -> int
weighted_impact_improvement(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: Literal[True],
) -> float
weighted_impact_improvement(
delta_l: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
*,
reference_floor: Literal['heavyweight', 'lightweight_1', 'lightweight_2', 'lightweight_3'] = ...,
one_decimal: bool = ...,
) -> int | float

Weighted reduction of impact level ΔLw or ΔLt,w (ISO 717-2:2020).

Relates a measured improvement spectrum ΔL to a reference floor of Table 4 (IMPACT_REFERENCE_FLOORS): the reference level with the covering is (Formula (1)) and the weighted improvement is (Formula (2)), both weighted ratings taken with weighted_impact_rating. On the heavyweight floor this is the ΔLw of Clause 5, ; on a lightweight floor it is the ΔLt,w of Clause 6, which 6.3 computes “as specified in 5.3, substituting the heavy reference floor by a lightweight reference floor” and 6.2 designates ΔLt,1,w, ΔLt,2,w or ΔLt,3,w by floor type.

one_decimal=True rates both curves with the 0.1 dB shift and keeps one decimal place, the form 5.4 prescribes when the uncertainty of ΔLw is stated (its EXAMPLE, ΔLw = 18.9 ± 1.1); Ln,r,0,w is then 77.6 dB for the heavyweight floor, as A.2.2 prints.

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-1:2021 Annex H or ISO 16251-1), or a mapping of band centre frequency in hertz to ΔL that holds those 16 bands, other keys not read.
reference_floor "heavyweight" (default), "lightweight_1", "lightweight_2" or "lightweight_3".
one_decimal Use the 0.1 dB shift and one-decimal reductions.

Returns: The weighted reduction, in dB: an integer, or a value to one decimal place when one_decimal is set.

Raises

Exception When
ValueError If delta_l is not 16 finite one-third-octave values, a mapping lacks one of them, or reference_floor is not one of the four floors.
TypeError if reference_floor is not a text, or delta_l holds a text or a value that is not a real number.
weighted_impact_rating(
values_by_band: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] | 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 over k equals maximising , 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. A mapping of band centre frequency in hertz to level is read band by band, as weighted_rating reads one, and a rating band it lacks is refused rather than filled.
fraction The band set, 3 for one-third octaves or 1 for octaves, or None to infer it from the number of values or the keys of the mapping. One of 1 or 3.

Returns: ImpactRatingResult with rating, ci and unfavorable_sum.

Raises

Exception When
ValueError If the number of values does not match the band set, if a mapping lacks a band of it, or if any value is non-finite.
TypeError if fraction is not an integer (a word, a flag or a float), or values_by_band holds a text or a value that is not a real number.
weighted_impact_rating_extended(
values_by_band: NumericArrayLike,
*,
frequencies: NumericArrayLike | 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), .

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 dB and 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.
TypeError if frequencies or values_by_band holds a text or a value that is not a real number.
weighted_rating(
values_by_band: Mapping[int, float] | Mapping[float, float] | NumericArrayLike,
fraction: Literal[1, 3] | np.integer[Any] | 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. A mapping of band centre frequency in hertz to value, such as a catalogue row’s spectrum, is read band by band: one that holds any one-third-octave band that is not an octave centre as the 16 one-third octaves, any other as the 5 octaves, and a rating band it lacks is refused rather than filled.
fraction The band set, 3 for one-third octaves or 1 for octaves, or None to infer it from the number of values or the keys of the mapping. One of 1 or 3.

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

Raises

Exception When
ValueError If the number of values does not match the band set, if a mapping lacks a band of it, or if any value is non-finite.
TypeError if fraction is not an integer (a word, a flag or a float), or values_by_band holds a text or a value that is not a real number.
weighted_rating_extended(
values_by_band: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
one_decimal: bool = False,
) -> ExtendedWeightedRatingResult

Weighted rating with enlarged-range adaptation terms (ISO 717-1 An. 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: 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.
TypeError if frequencies or values_by_band holds a text or a value that is not a real number.
weighted_reduction_improvement(
delta_r: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
basic_element: Literal['heavy_wall', 'heavy_floor', 'lightweight_wall'] = 'heavy_wall',
one_decimal: bool = False,
) -> ReductionImprovementRating

Weighted improvement of the sound reduction index by a lining (ISO 717-1).

ISO 717-1:2020 Annex D rates a lining on a standard basic element rather than on the wall it was measured on, so that the number describes the lining and not the laboratory: the measured improvement ΔR is added to the reference curve of the element (LINING_REFERENCE_ELEMENTS), (Formula (D.3)), both curves are rated with weighted_rating_extended, and (Formula (D.4)). Δ(Rw + C) and Δ(Rw + Ctr) are “calculated in an equivalent way”, as differences of the sums, and so is every enlarged-range term of Annex B whose bands ΔR covers. The rating carries the element index of D.3, ΔRw,heavy or ΔRw,light.

For a basic element that is not one of the three standard ones, D.3 takes the ratings “directly from the single-number ratings for that basic element with and without the tested acoustical lining”, the direct difference ΔRw,direct of Formula (D.2); that needs both measured curves and is what laboratory_lining_improvement returns beside this rating.

Parameters

Name Description
delta_r The sound reduction improvement index ΔR per one-third-octave band, in dB (ISO 10140-1:2021 G.1).
frequencies Band centre frequencies of delta_r, in Hz; None assumes exactly the 16 core bands 100 Hz to 3 150 Hz. The 16 core bands must be present, and every band must be one Table E.1 prints (50 Hz to 5 000 Hz).
basic_element "heavy_wall" (default), "heavy_floor" or "lightweight_wall".
one_decimal Rate both curves with the 0.1 dB shift and one-decimal reductions, the form of Clause 4.4 for the expression of uncertainty.

Returns: A ReductionImprovementRating.

Raises

Exception When
ValueError If delta_r is not one-dimensional and finite, the band counts differ, a band is not in Table E.1, the core bands are missing, or basic_element is not a standard element.
TypeError if basic_element is not a text, or delta_r or frequencies holds a text or a value that is not a real number.
WeightedRatingResult(
rating: int,
c: int,
ctr: int,
unfavorable_sum: float,
frequencies: NDArray[np.float64],
measured: NDArray[np.float64],
shifted_reference: NDArray[np.float64],
quantity: Literal['airborne'] = '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.
unfavorable_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). Restates measured against shifted_reference and is checked against them.
frequencies Band centre frequencies of the measured curve, in Hz.
measured The measured band quantities used for the rating (after the one-decimal reduction of Clause 4.4), in dB.
shifted_reference Table 3 reference curve after the final shift, in dB.
quantity Always "airborne": this class carries the ISO 717-1 airborne rating, and the renderers dispatch on this tag when handed the union with ImpactRatingResult, which carries "impact". The field used to admit both values and promise that "impact" would select the impact labels; it never could, since the impact labels read ci off the result and this class does not have one, so the promise ended in the renderer’s AttributeError.
WeightedRatingResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".
WeightedRatingResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = '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 (frequencies, measured, shifted_reference).
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).