building.intensity_insulation

Sound insulation measured with sound intensity (ISO 15186).

This is the sound-intensity counterpart of the sound-pressure methods in phonometry.lab_insulation (ISO 10140) and phonometry.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,

RI = Lp1 - 6 - [LIn + 10 lg(Sm / S)] 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)). RI,M = RI + Kc 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 lg(1 + Sb2 lambda / (8 V2)) (Formula (B.1)) for a well-defined receiving room of boundary area Sb2 and volume V2, or the room-independent approximation 10 lg(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 Sb2 = 117 m², V2 = 81 m³ reduces to (B.2).

Intensity element normalized level difference (Clause 3.9, Formula (8)). For small building elements, DI,n,e = Lp1 - 6 - (LIn + 10 lg(Sm / A0)) + 10 lg N dB with the reference absorption area A0 = 10 m² and the number N of element units in the measurement surface. The printed Formula (8) subtracts its 10 lg(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)). FpI = Lp - LIn 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 FpI + 10 dB (Clause 4.1) for the dynamic capability to be adequate.

Frequency range (Clause 6.6). Quantities are measured over the mandatory one-third-octave range 100 Hz to 5000 Hz (18 bands), optionally extended down to 50 Hz. 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.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

adaptation_term_kc(
    freq: Sequence[float] | np.ndarray,
    *,
    boundary_area: float | None = None,
    volume: float | None = None,
) -> 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 RI,M = RI + Kc (Clause 3.10). Two forms are available:

Well-defined receiving room (Formula (B.1)): when both boundary_area (Sb2) and volume (V2) are supplied, Kc = 10 lg(1 + Sb2 lambda / (8 V2)) with the midband wavelength lambda = c / f and c = 340 m/s.
Room-independent approximation (Formula (B.2)): when neither is supplied, Kc = 10 lg(1 + 61,4 / f), the exact reduction of (B.1) for the reference room Sb2 = 117 m², V2 = 81 m³.

Parameters

Name	Description
`freq`	One-third-octave midband frequencies, in Hz.
`boundary_area`	Total boundary-surface area `Sb2` of the receiving room, in m². Supply together with `volume` for (B.1).
`volume`	Receiving-room volume `V2`, in m³.

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

Raises

Exception	When
ValueError	If `freq` is not positive/finite, if only one of `boundary_area` / `volume` is supplied, or if either is not positive.

combine_subareas

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

LIn = 10 lg[ (1/Sm) sum_i Smi 10^(0,1 LIni) ] dB

with the total measured area Sm = sum_i |Smi| (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

Name	Description
`l_in`	Per-subarea intensity levels as a `(subareas, bands)` array (one row per subarea), in dB (magnitude of the intensity).
`measurement_area`	Subarea areas `Smi`, in m² (one per row). Negative values mark reverse-flow subareas per Clause 6.4.6; zero is invalid.

Returns: A tuple (LIn, Sm) with the combined level per band, in dB, and the total measured area Sm = sum |Smi|, in m².

Raises

Exception	When
ValueError	If the shapes are inconsistent or values non-finite, if any subarea area is zero, or if the signed energy sum of Formula (11) is not positive in some band (the reverse flows cancel or exceed the forward flow, so no level exists).

intensity_element_normalized_difference

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

DI,n,e = Lp1 - 6 - (LIn + 10 lg(Sm / A0)) + 10 lg N 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 A0 = 10 m² and the number N of element units installed within the surface. The weighted rating DI,n,e,w is computed via phonometry.weighted_rating (ISO 717-1) when exactly 16 or 5 values are supplied.

Parameters

Name	Description
`lp1`	Source-room sound pressure levels, in dB.
`l_in`	Normal sound intensity levels over the measurement surface, in dB.
`measurement_area`	Measurement-surface area `Sm`, in m².
`n`	Number `N` of small element units in the surface (Default: 1).

Returns: IntensityElementNormalizedResult.

Raises

Exception	When
ValueError	If the band counts differ, if `measurement_area` is not positive, if `n` is not a positive integer, or if inputs are non-finite.

intensity_sound_reduction

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

RI = Lp1 - 6 - [LIn + 10 lg(Sm / S)] 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 RI,M = RI + Kc (Formula (9)) is also formed. Weighted ratings RI,w (and RI,M,w) are computed via phonometry.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

Name	Description
`lp1`	Source-room sound pressure levels, in dB.
`l_in`	Normal sound intensity levels over the measurement surface, in dB.
`measurement_area`	Measurement-surface area `Sm`, in m².
`area`	Specimen area `S`, in m².
`kc`	Adaptation term `Kc` per band (dB) for the modified index, or `None` to skip it.

Returns: IntensityReductionResult.

Raises

Exception	When
ValueError	If the band counts differ, if `measurement_area` / `area` are not positive, or if inputs are non-finite.

IntensityElementNormalizedResult

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

Name	Description
`d_i_n_e`	Intensity element normalized level difference `DI,n,e = Lp1 - 6 - (LIn + 10 lg(Sm/A0)) + 10 lg N` per band, in dB (Clause 3.9, Formula (8) with the corrected sign of its `10 lg N` term; see `docs/ERRATA.md`).
`rating`	Single-number weighted rating `DI,n,e,w` with `C` / `Ctr` (ISO 717-1), or `None` when the band count is neither 16 (one-third octave) nor 5 (octave).
`measurement_area`	Measurement-surface area `Sm`, in m², or `None` on a manually built result (Clause 8 g).
`n`	Number `N` of element units within the measurement surface.

IntensityElementNormalizedResult.plot()

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

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

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 left table shows the ISO 717 evaluation per band (the `DI,n,e` value, the shifted reference and the unfavourable deviation) instead of the two-column form.
`language`	Fiche language: `"en"` (default, English) or `"es"` (Spanish, with a comma decimal separator).
`fpi`	Optional per-band surface pressure-intensity indicator `FpI` (Clause 8 i requires it as a function of frequency); annexed as a table column when supplied.
`residual_index`	Optional per-band pressure-residual intensity index `δpI0` of the probe and analyser (Clause 8 i); annexed as a table column when supplied.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If `engine` is unknown, `language` is not one of the supported values, 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), or `fpi` / `residual_index` do not match the band count.
ImportError	If reportlab is not installed (`pip install phonometry[report]`), or matplotlib is missing for the embedded rating figure (`pip install phonometry[plot]`).

IntensityReductionResult

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

Name	Description
`r_i`	Intensity sound reduction index `RI = Lp1 - 6 - [LIn + 10 lg(Sm/S)]` per band, in dB (Clause 3.8, Formula (7)). In the field (ISO 15186-2) this is the apparent index `R'I`.
`r_i_modified`	Modified index `RI,M = RI + Kc` per band, in dB (Clause 3.10, Formula (9)), or `None` when no adaptation term was supplied.
`rating`	Single-number weighted rating `RI,w` with `C` / `Ctr` (ISO 717-1), or `None` when the band count is neither 16 (one-third octave) nor 5 (octave).
`rating_modified`	Weighted rating `RI,M,w` of the modified index, or `None` when unavailable.
`area`	Test-object area `S`, in m², or `None` on a manually built result. Carried so the report can state it (Clause 8 g).
`measurement_area`	Measurement-surface area `Sm`, in m², or `None` on a manually built result (Clause 8 g).

IntensityReductionResult.plot()

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

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

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` and the Kc-modified index `RI,M` is available, the table annexes `RI,M` beside the reported `RI`.
`language`	Fiche language: `"en"` (default, English) or `"es"` (Spanish, with a comma decimal separator).
`fpi`	Optional per-band surface pressure-intensity indicator `FpI` (Clause 8 i requires it as a function of frequency); annexed as a table column when supplied.
`residual_index`	Optional per-band pressure-residual intensity index `δpI0` of the probe and analyser (Clause 8 i); annexed as a table column when supplied.

Returns: The written path as a str.

Raises

Exception	When
ValueError	If `engine` is unknown, `language` is not one of the supported values, 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), or `fpi` / `residual_index` do not match the band count.
ImportError	If reportlab is not installed (`pip install phonometry[report]`), or matplotlib is missing for the embedded rating figure (`pip install phonometry[plot]`).

surface_pressure_intensity_indicator

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 FpI = Lp - LIn 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 FpI > 10 dB / FpI > 6 dB as not satisfactory); in addition the probe’s pressure-residual intensity index must exceed FpI + 10 dB (Clause 4.1).

Parameters

Name	Description
`lp`	Surface-averaged sound pressure levels, in dB.
`l_in`	Normal sound intensity levels on the surface, in dB.

Returns: The indicator FpI per band, in dB.

Raises

Exception	When
ValueError	If the shapes differ or contain non-finite values.

Created and maintained byJosé Manuel Requena Plens· GitHub· PyPI· All projects