building.measurement.intensity_insulation

Sound insulation measured with sound intensity (ISO 15186).

This is the sound-intensity counterpart of the sound-pressure methods in phonometry.building.measurement.lab_insulation (ISO 10140) and phonometry.building.measurement.insulation (ISO 16283). Instead of an equivalent absorption area in the receiving room, the transmitted sound power is measured directly by scanning an intensity probe over a measurement surface enclosing the specimen. The main use is when the traditional pressure method fails because of high flanking transmission (ISO 15186-1:2000, Clause 1): the intensity method only captures the power radiated by the element itself.

Intensity sound reduction index (ISO 15186-1:2000, Clause 3.8, Formula (7)). From the average source-room sound pressure level Lp1 and the average normal sound intensity level LIn over the measurement surface, in dB,

with the measurement-surface area Sm and the specimen area S. The constant 6 dB is the diffuse-field relationship between the sound pressure level and the sound intensity level incident on the specimen. The same formula yields the apparent index R'I in the field (ISO 15186-2), the only difference being the measurement condition (flanking is not suppressed), not the arithmetic.

Modified intensity sound reduction index (Clause 3.10, Formula (9)). $R_{\mathrm{I},\mathrm{M}}=R_{\mathrm{I}}+K_{\mathrm{c}}$ corrects RI so that it reproduces the ISO 140-3 (now ISO 10140-2) pressure result, which slightly overestimates R because the power radiated into the receiving room is underestimated. The adaptation term Kc (Annex B) is $10{\log }_{10}(1+S_{\mathrm{b}2}\lambda /(8V_2))$ (Formula (B.1)) for a well-defined receiving room of boundary area Sb2 and volume V2, or the room-independent approximation $10{\log }_{10}(1+61.4/f)$ (Formula (B.2)); both use the speed of sound $c=340$ m/s so that (B.1) with the reference room $S_{\mathrm{b}2}=117$ m², $V_2=81$ m³ reduces to (B.2).

Intensity element normalized level difference (Clause 3.9, Formula (8)). For small building elements, in dB,

with the reference absorption area $A_0=10$ m² and the number N of element units in the measurement surface. The printed Formula (8) subtracts its $10{\log }_{10}N$ term instead of adding it, which is physically inconsistent with ISO 10140-2:2010 Formula (6) and ISO 15186-2:2010 Formula (12); the corrected per-unit form is implemented (see docs/ERRATA.md).

Surface pressure-intensity indicator (Clause 3.6 / 6.4.2, Formula (10)). $F_{pI}=L_p-L_{I\mathrm{n}}$ qualifies the measurement surface: it must not exceed 10 dB for a sound-reflecting specimen (6 dB when the receiving side is sound absorbing), and the probe’s pressure-residual intensity index must exceed $F_{pI}+10$ dB (Clause 4.1) for the dynamic capability to be adequate.

Frequency range (part 1, Clause 6.6). The part 1 and part 2 quantities are measured over the mandatory one-third-octave range 100 Hz to 5000 Hz (18 bands), optionally extended down to 50 Hz. The part 3 quantities at the end of this module answer over 50 Hz to 160 Hz instead (its Clause 1.1), and results from the two ranges are meant to be combined into one 50 Hz to 5000 Hz curve. The single-number weighted rating uses the ISO 717-1 core range, so the automatic rating (RI,w, RI,M,w, DI,n,e,w) is formed via the verified phonometry.building.weighted_rating engine only when exactly 16 one-third-octave (100-3150 Hz) or 5 octave (125-2000 Hz) values are supplied.

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

adaptation_term_kc(
    freq: Sequence[float] | np.ndarray,
    *,
    boundary_area: float,
    volume: float,
) -> np.ndarray

adaptation_term_kc(freq: Sequence[float] | np.ndarray) -> np.ndarray

Adaptation term Kc per ISO 15186-1:2000, Annex B.

Returns, per one-third-octave midband frequency, the term Kc that turns the intensity sound reduction index RI into the modified index $R_{\mathrm{I},\mathrm{M}}=R_{\mathrm{I}}+K_{\mathrm{c}}$ (Clause 3.10). Two forms are available:

• Well-defined receiving room (Formula (B.1)): when both boundary_area (Sb2) and volume (V2) are supplied, $K_{\mathrm{c}}=10{\log }_{10}(1+S_{\mathrm{b}2}\lambda /(8V_2))$ with the midband wavelength $\lambda =c/f$ and $c=340$ m/s.
• Room-independent approximation (Formula (B.2)): when neither is supplied, $K_{\mathrm{c}}=10{\log }_{10}(1+61.4/f)$, the exact reduction of (B.1) for the reference room $S_{\mathrm{b}2}=117$ m², $V_2=81$ m³.

Parameters

Returns: The adaptation term Kc per band, in dB.

Raises

combine_subareas(
    l_in: Sequence[Sequence[float]] | np.ndarray,
    measurement_area: Sequence[float] | np.ndarray,
) -> tuple[np.ndarray, float]

Combine per-subarea intensity levels (ISO 15186-1, Formulas (11)-(12)).

When the measurement surface is divided into subareas Smi each scanned individually, the normal sound intensity level over the whole surface is the area-weighted energy average, in dB,

with the total measured area $S_{\mathrm{m}}={\sum }_i|S_{\mathrm{m}i}|$ (Formula (12)).

Negative-direction subareas (Clause 6.4.6). When the sound intensity of a subarea has a negative direction (net energy flowing back towards the specimen), the standard requires a minus sign before that Smi in Formula (11). Express this by passing the subarea’s area as a negative number: its energy is subtracted in the numerator while Sm keeps the unsigned area sum.

Parameters

Returns: A tuple (LIn, Sm) with the combined level per band, in dB, and the total measured area $S_{\mathrm{m}}=\sum |S_{\mathrm{m}i}|$, in m².

Raises

intensity_element_normalized_difference(
    lp1: Sequence[float] | np.ndarray,
    l_in: Sequence[float] | np.ndarray,
    *,
    measurement_area: float,
    n: int = 1,
) -> IntensityElementNormalizedResult

Intensity element normalized level difference per ISO 15186-1 (Formula (8)).

Computes, per frequency band, the intensity element normalized level difference of a single element unit, in dB,

from the average source-room sound pressure level Lp1, the average normal sound intensity level LIn over the measurement surface of area Sm (measurement_area), the reference absorption area $A_0=10$ m² and the number N of element units installed within the surface. The weighted rating DI,n,e,w is computed via phonometry.building.weighted_rating (ISO 717-1) when exactly 16 or 5 values are supplied.

Parameters

Returns: IntensityElementNormalizedResult.

Raises

intensity_sound_reduction(
    lp1: Sequence[float] | np.ndarray,
    l_in: Sequence[float] | np.ndarray,
    *,
    measurement_area: float,
    area: float,
    kc: Sequence[float] | np.ndarray | None = None,
) -> IntensityReductionResult

Intensity sound reduction index per ISO 15186-1:2000 (Formula (7)).

Computes, per frequency band, the intensity sound reduction index, in dB,

from the average source-room sound pressure level Lp1 and the average normal sound intensity level LIn over the measurement surface of area Sm (measurement_area), for a specimen of area S (area). The same formula gives the apparent index R'I in the field (ISO 15186-2). When an adaptation term kc is supplied (see adaptation_term_kc), the modified index $R_{\mathrm{I},\mathrm{M}}=R_{\mathrm{I}}+K_{\mathrm{c}}$ (Formula (9)) is also formed. Weighted ratings RI,w (and RI,M,w) are computed via phonometry.building.weighted_rating (ISO 717-1) when exactly 16 one-third-octave (100-3150 Hz) or 5 octave (125-2000 Hz) values are supplied.

lp1 and l_in may be one value per band (already averaged) or a two-dimensional (positions, bands) array, in which case the positions are energy-averaged. Subareas scanned separately should first be combined with combine_subareas.

Parameters

Returns: IntensityReductionResult.

Raises

IntensityElementNormalizedResult(
    d_i_n_e: np.ndarray,
    rating: WeightedRatingResult | None,
    measurement_area: float | None = None,
    n: int = 1,
)

Per-band intensity element normalized level difference (ISO 15186-1).

Attributes

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

Plot DI,n,e against the shifted ISO 717-1 reference curve.

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

IntensityElementNormalizedResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
    fpi: Sequence[float] | np.ndarray | None = None,
    residual_index: Sequence[float] | np.ndarray | None = None,
) -> str

Render an ISO 15186-1 element-normalized insulation report to a PDF.

Writes the one-page laboratory test report of ISO 15186-1:2000 Clause 8 for the element-normalized level difference DI,n,e of a small building element measured with sound intensity: 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 rating DI,n,e,w (C; Ctr) (the element-normalized level difference DI,n,e rated per ISO 717-1), the intensity-method statement with the measurement-surface area Sm and unit count N when the result carries them (Clause 8 g), 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.

The applicable ReportMetadata fields describe the intensity measurement: specimen (the tested element and its mounting and sealing, Clause 8 e), area (the element area), client, manufacturer, test_room (the laboratory / facility), laboratory, operator, report_id and test_date, plus the room/climate fields shared with the other insulation fiches. The measurement-surface shape, the measurement distance and the scanning-versus-discrete-point acquisition method (Clause 8 j-l) are not dedicated metadata fields; record them in notes (free text) and name the measurement standard in measurement_standard ("ISO 15186-1"). A requirement adds a PASS/FAIL verdict; the element insulation passes at or above the target.

Parameters

Returns: The written path as a str.

Raises

IntensityReductionResult(
    r_i: np.ndarray,
    r_i_modified: np.ndarray | None,
    rating: WeightedRatingResult | None,
    rating_modified: WeightedRatingResult | None,
    area: float | None = None,
    measurement_area: float | None = None,
)

Per-band intensity sound reduction index (ISO 15186-1:2000).

Attributes

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

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

Delegates to the weighted-rating plot (measured RI 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.

IntensityReductionResult.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
    fpi: Sequence[float] | np.ndarray | None = None,
    residual_index: Sequence[float] | np.ndarray | None = None,
) -> str

Render an ISO 15186-1 intensity sound-insulation report to a PDF.

Writes the one-page laboratory test report of ISO 15186-1:2000 Clause 8 for sound insulation measured with sound intensity: 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 rating RI,w (C; Ctr) (the intensity sound reduction index RI rated per ISO 717-1), the intensity-method statement with the test-object and measurement-surface areas S / Sm when the result carries them (Clause 8 g), 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.

The applicable ReportMetadata fields describe the intensity measurement: specimen (the tested element and its mounting, sealing and mass per unit area, Clause 8 e), client, manufacturer, test_room (the laboratory / facility), laboratory, operator, report_id and test_date, plus the room/climate fields shared with the other insulation fiches. The measurement-surface shape, the measurement distance and the scanning-versus-discrete-point acquisition method (Clause 8 j-l) are not dedicated metadata fields; record them in notes (free text) and name the measurement standard in measurement_standard ("ISO 15186-1").

Parameters

Returns: The written path as a str.

Raises

limp_panel_reduction_index(
    frequencies: Sequence[float] | np.ndarray,
    *,
    surface_mass: float,
    area: float,
    temperature: float = 23.0,
    static_pressure: float = 101300.0,
) -> np.ndarray

Sound reduction index of a limp panel (ISO 15186-3:2002, Annex A).

Annex A is normative and is how a laboratory qualifies itself: measure a limp panel of area $S>1$ m\ :sup:2, calculate what it should read, and require the two to agree within 4,0 dB from 50 Hz to 160 Hz. This is the calculated half.

A.1 states two different things about the area, and this enforces the second: the qualification panel is required to be larger than 1 m², while Formula (A.3) is declared valid “if the area of the test specimen is at least 1 m²”. A panel of exactly 1 m² is therefore refused as a qualification but accepted as an input, which is the boundary the code takes.

with the characteristic impedance and the speed of sound taken from the climate of the test (Formulas (A.4) and (A.5)),

The panel is limp by assumption: $R_0$ is the mass law and ${\sigma }_{\mathrm{d}}$ the radiation efficiency of forced transmission alone. The 160 Hz ceiling is not this annex’s own: Clause 1.1 applies the whole of this part over 50 Hz to 160 Hz, and the qualification inherits it.

Any frequency is computed, and no range is imposed. A.1 declares Formula (A.3) valid “for the frequency range of this part of ISO 15186”, so a result outside 50 Hz to 160 Hz is the model evaluated past its stated validity: useful for seeing where a real panel leaves it, not usable as a qualification. Restricting the input is the caller’s to do, unlike low_frequency_intensity_reduction, whose quantity is defined over that range and nowhere else.

Parameters

Returns: The calculated sound reduction index per band, in dB.

Raises

low_frequency_element_normalized_difference(
    lp_surface: Sequence[float] | np.ndarray,
    l_in: Sequence[float] | np.ndarray,
    *,
    measurement_area: float,
    elements: int = 1,
    l_p: Sequence[float] | np.ndarray | None = None,
    frequencies: Sequence[float] | np.ndarray | None = None,
    absorbing_specimen_surface: bool = False,
) -> LowFrequencyElementResult

Element normalized level difference at low frequencies (ISO 15186-3).

Clause 3.9, Formula (8), for small building elements measured with the surface-pressure method of this part:

with the reference absorption area $A_0=10$ m². Two things separate it from its part 1 sibling (intensity_element_normalized_difference): the 9 dB of the surface measurement in place of 6, and the sign of the $10\lg N$ term, which this part prints as the derivable one. Part 1 prints it subtracted, which is registered in docs/ERRATA.md; the two parts disagree on the page, and this is the one that agrees with the physics.

Parameters

Returns: LowFrequencyElementResult.

Raises

low_frequency_intensity_reduction(
    lp_surface: Sequence[float] | np.ndarray,
    l_in: Sequence[float] | np.ndarray,
    *,
    measurement_area: float,
    area: float,
    l_p: Sequence[float] | np.ndarray | None = None,
    frequencies: Sequence[float] | np.ndarray | None = None,
    absorbing_specimen_surface: bool = False,
) -> LowFrequencyIntensityResult

Intensity sound reduction index at low frequencies (ISO 15186-3:2002).

Below 100 Hz a source room has too few modes for its average pressure to describe what reaches the specimen, so this part measures the pressure on the surface of the specimen instead and the receiving side with an intensity probe as before (Clause 3.8, Formula (7)):

The 9 dB is the whole difference from intensity_sound_reduction, which subtracts 6: close to a rigid boundary a diffuse field carries twice the mean-square pressure it carries away from one, so the surface average sits three decibels above the room average of the same field.

Clause 7 requires the surface-pressure intensity indicator $F_{pI}=L_p-L_{I\mathrm{n}}$ (Formula (5)) to be reported beside the index, and Clause 6.4.2 refuses the measurement surface where it exceeds 10 dB for a sound-reflecting test specimen, or 6 dB for a specimen with a sound-absorbing surface in the receiving room. Those bands come back flagged rather than dropped, because the standard’s answer to them is to improve the measurement environment, not to discard the band.

Both levels of Formula (5) are read on the measurement surface in the receiving room, so the indicator needs l_p and not the source-room surface levels Formula (7) is built from. Clause 6.4.2 asks for that second measurement “if possible”, so it is optional here and its absence leaves the indicator and the qualification unanswered rather than guessed.

Clause 6.4.2 refuses a negative measured intensity for the same reason, which a level cannot carry: pass the signed sub-area intensities through combine_subareas first, which is where the sign lives.

lp_surface and l_in may be one value per band or a (positions, bands) array, in which case the positions are energy-averaged. Sub-areas scanned separately are combined first with combine_subareas, which is Formulas (9) and (10) here.

Parameters

Returns: LowFrequencyIntensityResult.

Raises

LowFrequencyElementResult(
    d_i_n_e: np.ndarray,
    surface_pressure_intensity: np.ndarray | None,
    qualified: np.ndarray | None,
    frequencies: np.ndarray | None,
    measurement_area: float,
    elements: int,
    absorbing_specimen_surface: bool,
)

Per-band element normalized level difference at low frequencies.

The result of ISO 15186-3:2002, Clause 3.9, Formula (8), the small-element counterpart of LowFrequencyIntensityResult. No single-number rating accompanies it: Clause 6.6 stops at 160 Hz, six one-third octaves, and ISO 717-1 needs sixteen.

Attributes

property

The Clause 6.4.2 limit on FpI that this result was judged by.

Returns: 6.0 dB when the specimen presents a sound-absorbing surface in the receiving room, 10.0 dB when it is sound-reflecting.

LowFrequencyElementResult.plot(
    ax: Axes | None = None,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Draw DI,n,e per band, hatching any band Clause 6.4.2 refuses.

Parameters

Returns: The axes.

LowFrequencyIntensityResult(
    r_i: np.ndarray,
    surface_pressure_intensity: np.ndarray | None,
    qualified: np.ndarray | None,
    frequencies: np.ndarray | None,
    area: float,
    measurement_area: float,
    absorbing_specimen_surface: bool,
)

Per-band intensity sound reduction index at low frequencies.

The result of ISO 15186-3:2002, Clause 3.8, Formula (7). It differs from its part 1 sibling in where the source-room pressure is measured and so in what has to be subtracted from it: 9 dB against the surface of the specimen, where part 1 subtracts 6 dB from a room average.

Attributes

property

The Clause 6.4.2 limit on FpI that this result was judged by.

Reported beside the indicator, and drawn by plot so the figure does not have to restate which of the two limits applies.

Returns: 6.0 dB when the specimen presents a sound-absorbing surface in the receiving room, 10.0 dB when it is sound-reflecting.

LowFrequencyIntensityResult.plot(
    ax: Axes | None = None,
    language: str = 'en',
    **kwargs: Any,
) -> Axes

Draw the index per band, hatching any band Clause 6.4.2 refuses.

Parameters

Returns: The axes.

surface_pressure_intensity_indicator(
    lp: Sequence[float] | np.ndarray,
    l_in: Sequence[float] | np.ndarray,
) -> np.ndarray

Surface pressure-intensity indicator FpI (ISO 15186-1, Formula (10)).

Returns $F_{pI}=L_p-L_{I\mathrm{n}}$ per band from the surface- and time-averaged sound pressure level Lp and normal sound intensity level LIn on the measurement surface (Clause 3.6 / 6.4.2). The measurement surface is adequately qualified when FpI does not exceed 10 dB for a sound-reflecting specimen, or 6 dB when the receiving side is sound absorbing (Clause 6.4.2 flags $F_{pI}>10$ dB / $F_{pI}>6$ dB as not satisfactory); in addition the probe’s pressure-residual intensity index must exceed $F_{pI}+10$ dB (Clause 4.1).

Parameters

Returns: The indicator FpI per band, in dB.

Raises