# building.measurement.flanking_transmission

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-07-15
Updated: 2026-11-16T21:36:14Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Laboratory measurement of flanking sound transmission (ISO 10848:2006/2010).

---

Laboratory measurement of flanking sound transmission (ISO 10848:2006/2010).

This is the **measurement** counterpart of the flanking-transmission
*prediction* in [`phonometry.building.prediction.simplified_model`](https://docs.jmrp.io/phonometry/reference/api/building/simplified-model/). EN 12354-1 predicts the
apparent in-situ performance from, among other inputs, the **vibration
reduction index** `Kij` of each junction; ISO 10848 is the standard that
*measures* that `Kij` (and the overall flanking descriptors `Dn,f` /
`Ln,f`) in a qualified test facility. The measured `Kij` is a
situation-invariant junction descriptor that feeds straight into the
[`phonometry.building.flanking_path`](https://docs.jmrp.io/phonometry/reference/api/building/simplified-model/#flanking_path) model.

**Vibration reduction index (Part 1, Clause 3.9).** From the *direction
averaged* velocity level difference
$\overline{D}_{\mathrm{v},ij} = \frac{1}{2}(D_{\mathrm{v},ij} + D_{\mathrm{v},ji})$ (Formula (11))
this module forms, per one-third-octave band,
$K_{ij} = \overline{D}_{\mathrm{v},ij} + 10 \log_{10}(l_{ij} / \sqrt{a_i a_j})$
(Formula (13)) with the common-edge
junction length `lij` and the equivalent absorption lengths `ai`, `aj` of
the two elements. For lightweight, well-damped elements the equivalent
absorption length collapses to the element area ($a_j = S_j / l_0$,
$l_0 = 1$ m,
Clause 3.8 Note 3) and Formula (13) reduces to Formula (14),
$K_{ij} = \overline{D}_{\mathrm{v},ij} + 10 \log_{10}(l_{ij} / \sqrt{S_i S_j})$.
Because it uses the direction average,
`Kij` is symmetric ($K_{ij} = K_{ji}$).

**Equivalent absorption length (Part 1, Formula (12)).**

$$
a_j = \frac{2.2\,\pi^2\,S_j}{T_{\mathrm{s},j}\,c_0} \sqrt{\frac{f_{\mathrm{ref}}}{f}}
$$

with the structural
reverberation time `Ts,j`, the element area `Sj`, the speed of sound in air
`c0` and the reference frequency $f_{\mathrm{ref}} = 1000$ Hz. The
related total loss
factor is $\eta = 2.2 / (f \, T_\mathrm{s})$ (Clause 7.3.1).

**Overall flanking descriptors (Part 1, Clauses 3.2/3.3).** With airborne
excitation the normalized flanking level difference is
$D_\mathrm{n,f} = L_1 - L_2 - 10 \log_{10}(A/A_0)$ (Formula (4)); with a
tapping machine on the source-room floor the normalized flanking impact level
is $L_\mathrm{n,f} = L_2 + 10 \log_{10}(A/A_0)$ (Formula (5)), both with
the reference absorption area $A_0 = 10$ m². Their single-number ratings
`Dn,f,w (C; Ctr)` and `Ln,f,w (CI)` follow ISO 717-1/-2 through the
verified [`phonometry.building.weighted_rating`](https://docs.jmrp.io/phonometry/reference/api/building/ratings/#weighted_rating) /
[`phonometry.building.weighted_impact_rating`](https://docs.jmrp.io/phonometry/reference/api/building/ratings/#weighted_impact_rating) engines, reused unchanged.

**Validity of Kij.** `Kij` rests on a statistical-energy-analysis
simplification (weak coupling, diffuse vibration fields). This module exposes
the standard's own applicability checks: the strong-coupling inequality
(Formula (15)), and, for heavy junctions (Part 4), the modal density,
in-band mode count and modal overlap factor (Formulas (5), (4), (6)) whose
thresholds bracket or exclude unreliable bands.

**c0 note.** ISO 10848 writes `c0` only as "the speed of sound in air" and
gives no number. This module defaults to `343 m/s` (20 °C) and exposes it as
a parameter so a facility can pin its own value.

**Frequency range (Part 1, Clause 7.5).** The mandatory one-third-octave range
is 100 Hz to 5000 Hz (18 bands). The single-number `Kij` is the arithmetic
mean over 200 Hz to 1250 Hz for one-third-octave bands, or over 125 Hz to
1000 Hz for octave bands (Annex A); the automatic mean is formed only when
the corresponding band set is present in the supplied frequencies. For heavy
junctions (Part 4, Clause 9) bands whose modal overlap factor is below 0.25
are bracketed and excluded from the single-number mean when the per-band
`modal_overlap` is supplied.

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

## band_mode_count

```python
band_mode_count(
    frequencies: float | np.floating[Any] | np.integer[Any],
    area: float,
    critical_frequency: float,
    *,
    speed_of_sound: float = ...,
) -> float

band_mode_count(
    frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    area: float,
    critical_frequency: float,
    *,
    speed_of_sound: float = ...,
) -> NDArray[np.float64]

band_mode_count(
    frequencies: NumericArrayLike,
    area: float,
    critical_frequency: float,
    *,
    speed_of_sound: float = ...,
) -> float | NDArray[np.float64]
```

In-band mode count $N = B \cdot n$ (Part 4, Formula (4)).

With the one-third-octave bandwidth approximation
$B = 0.23 \cdot f$ and the
modal density `n` from [`modal_density`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#modal_density). $N \ge 5$ modes per
band is
"always satisfactory".

**Parameters**

| Name | Description |
| :--- | :--- |
| `frequencies` | Band centre frequency `f`, in Hz, per band. |
| `area` | Element area `S`, in m². |
| `critical_frequency` | Critical frequency `fc`, in Hz. |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s. |

**Returns:** In-band mode count `N` per band (dimensionless). A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any input is not positive/finite. |
| TypeError | if `frequencies` holds a text or a value that is not a real number. |

## check_strong_coupling

```python
check_strong_coupling(
    velocity_level_difference: NumericArrayLike,
    mass_i: float,
    mass_j: float,
    critical_frequency_i: float,
    critical_frequency_j: float,
    *,
    frequencies: NumericArrayLike | None = None,
) -> StrongCouplingCheck
```

Is the coupling of the two elements weak enough for `Kij`? (Part 1, Formula (15)).

The measured `Kij` may not be relevant, the elements being strongly
coupled, in a band where
$D_{\mathrm{v},ij} \ge 3 - 10 \log_{10}\frac{m_i f_{\mathrm{c}j}}{m_j f_{\mathrm{c}i}}$
does not hold (Part 1, 4.3.3).

**Parameters**

| Name | Description |
| :--- | :--- |
| `velocity_level_difference` | Velocity level difference `Dv,ij` per band from element `i` (excited) to element `j`, in dB; one direction, not the average of both. |
| `mass_i` | Mass per unit area `mi` of element `i`, in kg/m². |
| `mass_j` | Mass per unit area `mj` of element `j`, in kg/m². |
| `critical_frequency_i` | Critical frequency `fci` of element `i`, in Hz. |
| `critical_frequency_j` | Critical frequency `fcj` of element `j`, in Hz. |
| `frequencies` | The band centre frequencies of the differences, in Hz, for the plot to name the bands by; `None` (the default) numbers them. |

**Returns:** The verdict, as a [`StrongCouplingCheck`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#strongcouplingcheck); band by band in its [`holds`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#strongcouplingcheckholds).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any scalar input is not positive/finite, or the band frequencies are not one positive value per band. |
| TypeError | if `critical_frequency_i`, `critical_frequency_j`, `mass_i` or `mass_j` is not a single number, or `frequencies` or `velocity_level_difference` holds a text or a value that is not a real number. |

## critical_frequency

```python
critical_frequency(
    longitudinal_wave_speed: float,
    thickness_m: float,
    *,
    speed_of_sound: float = 343.0,
) -> float
```

Thin-plate critical frequency `fc` (Part 1, Formula (20)).

$f_\mathrm{c} = c_0^2 / (1.8 \, c_\mathrm{L} \, h)$ for a homogeneous
isotropic element. The constant 1.8 already carries the
$2\pi/\sqrt{12}$ factor of the thin-plate dispersion relation, so for
a plate whose bending stiffness and mass are mutually consistent this
equals [`phonometry.vibration.coincidence_frequency`](https://docs.jmrp.io/phonometry/reference/api/vibration/radiation-efficiency/#coincidence_frequency) (Hopkins Eq.
2.201) to within the rounding of the constant.

**Note**

The printed ISO 10848-1:2006 Formula (20) carries a spurious extra
`π` in the denominator ($1.8 \, c_\mathrm{L} \, h \, \pi$), which
would misplace
`fc` by a factor π; the π-free form implemented here is the one
ISO 10848-1:2017 restores in its Formula (5), ISO 12354-1:2017
prints in its symbol definitions
($f_\mathrm{c} = c_0^2/(1.8 \, c_\mathrm{L} t)$) and
Hopkins Eq. 2.201 derives. See `docs/ERRATA.md`.

**Parameters**

| Name | Description |
| :--- | :--- |
| `longitudinal_wave_speed` | Longitudinal wave speed `cL`, in m/s. |
| `thickness_m` | Element thickness `h`, in m. |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s. |

**Returns:** Critical frequency `fc`, in Hz.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any input is not positive/finite. |
| TypeError | if `longitudinal_wave_speed`, `speed_of_sound` or `thickness_m` is not a single number. |

## direction_averaged_level_difference

```python
direction_averaged_level_difference(
    dv_ij: float | np.floating[Any] | np.integer[Any],
    dv_ji: float | np.floating[Any] | np.integer[Any],
) -> float

direction_averaged_level_difference(
    dv_ij: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    dv_ji: NumericArrayLike,
) -> NDArray[np.float64]

direction_averaged_level_difference(
    dv_ij: float | np.floating[Any] | np.integer[Any],
    dv_ji: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

direction_averaged_level_difference(
    dv_ij: NumericArrayLike,
    dv_ji: NumericArrayLike,
) -> float | NDArray[np.float64]
```

Direction-averaged velocity level difference (Formula (11)).

$\overline{D}_{\mathrm{v},ij} = \frac{1}{2}(D_{\mathrm{v},ij} + D_{\mathrm{v},ji})$ with
`Dv,ij` measured exciting element
`i` and `Dv,ji` exciting element `j`. The average makes the derived
`Kij` symmetric.

**Parameters**

| Name | Description |
| :--- | :--- |
| `dv_ij` | `Dv,ij` (element `i` excited), in dB, per band. |
| `dv_ji` | `Dv,ji` (element `j` excited), in dB, per band. |

**Returns:** `D̄v,ij` per band, in dB. A `float` when `dv_ij` and `dv_ji` are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are empty, non-finite, or differ in length. |
| TypeError | if `dv_ij` or `dv_ji` holds a text or a value that is not a real number. |

## equivalent_absorption_length

```python
equivalent_absorption_length(
    area: float,
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: float | np.floating[Any] | np.integer[Any],
    speed_of_sound: float = ...,
) -> float

equivalent_absorption_length(
    area: float,
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    speed_of_sound: float = ...,
) -> NDArray[np.float64]

equivalent_absorption_length(
    area: float,
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: NumericArrayLike,
    speed_of_sound: float = ...,
) -> float | NDArray[np.float64]
```

Equivalent absorption length `aj` (Formula (12)).

$$
a_j = \frac{2.2\,\pi^2\,S_j}{T_{\mathrm{s},j}\,c_0} \sqrt{\frac{f_{\mathrm{ref}}}{f}}
$$

with $f_{\mathrm{ref}} = 1000$ Hz.

**Parameters**

| Name | Description |
| :--- | :--- |
| `area` | Element surface area `Sj`, in m². |
| `structural_reverberation_time` | Structural reverberation time `Ts,j`, in s, per band (or a single value broadcast to all bands). |
| `frequencies` | Band centre frequency `f`, in Hz, per band. |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s (default 343 m/s). |

**Returns:** Equivalent absorption length `aj`, in m, per band. A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any input is not positive/finite or the band counts are incompatible. |
| TypeError | if `area` or `speed_of_sound` is not a single number, or `frequencies` or `structural_reverberation_time` holds a text or a value that is not a real number. |

## FlankingImpactLevelResult

```python
FlankingImpactLevelResult(
    l_n_f: NDArray[np.float64],
    rating: ImpactRatingResult | None,
)
```

Normalized flanking impact level `Ln,f` (Formula (5)).

**Attributes**

| Name | Description |
| :--- | :--- |
| `l_n_f` | $L_\mathrm{n,f} = L_2 + 10 \log_{10}(A/A_0)$ per band, in dB. |
| `rating` | Single-number `Ln,f,w` with `CI` (ISO 717-2), or `None` when the band count is neither 16 nor 5. |

### FlankingImpactLevelResult.plot()

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

Plot `Ln,f` against the shifted ISO 717-2 reference curve.

**Parameters**

| Name | Description |
| :--- | :--- |
| `language` | The language of the labels: `"en"` or `"es"`. |

### FlankingImpactLevelResult.report()

```python
FlankingImpactLevelResult.report(
    path: str | os.PathLike[str],
    *,
    metadata: ReportMetadata | None = None,
    engine: Literal['reportlab'] = 'reportlab',
    verbose: bool = False,
    language: Literal['en', 'es'] = 'en',
    part: int | np.integer[Any] = 2,
) -> str
```

Render a normalized flanking impact level `Ln,f` fiche to a PDF.

Writes the one-page impact flanking-transmission report of the
ISO 10848 series: the standard-basis line naming the part governing
the tested construction, an optional metadata header, the per-band
`Ln,f` table beside the measured-versus-shifted-ISO 717-2
reference curve, the boxed single-number `Ln,f,w (CI)`, the
measurement statement, an optional requirement verdict and a footer.

**Parameters**

| Name | Description |
| :--- | :--- |
| `path` | Destination path of the PDF file. |
| `metadata` | Optional [`ReportMetadata`](https://docs.jmrp.io/phonometry/reference/api/building/insulation/#reportmetadata); `None` produces a lightweight fiche (body, rating 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 `Ln,f` 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). |
| `part` | The ISO 10848 part governing the tested construction and named in the basis line: `2` (lightweight elements, default, ISO 10848-2:2006), `3` (lightweight elements with a junction of substantial influence, ISO 10848-3:2006) or `4` (heavy, Type A elements, ISO 10848-4:2010). |

**Returns:** The written `path` as a `str`.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `engine` is unknown, `part` is not 2, 3 or 4, or the result has no single-number rating (the band count is neither 16 nor 5). |
| ImportError | If reportlab is not installed (the `[report]` extra), or matplotlib is missing for the embedded figure (the `[plot]` extra). |

## FlankingLevelDifferenceResult

```python
FlankingLevelDifferenceResult(
    d_n_f: NDArray[np.float64],
    rating: WeightedRatingResult | None,
)
```

Normalized flanking level difference `Dn,f` (airborne, Formula (4)).

**Attributes**

| Name | Description |
| :--- | :--- |
| `d_n_f` | $D_\mathrm{n,f} = L_1 - L_2 - 10 \log_{10}(A/A_0)$ per band, in dB. |
| `rating` | Single-number `Dn,f,w` with `C`/`Ctr` (ISO 717-1), or `None` when the band count is neither 16 nor 5. |

### FlankingLevelDifferenceResult.plot()

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

Plot `Dn,f` against the shifted ISO 717-1 reference curve.

**Parameters**

| Name | Description |
| :--- | :--- |
| `language` | The language of the labels: `"en"` or `"es"`. |

### FlankingLevelDifferenceResult.report()

```python
FlankingLevelDifferenceResult.report(
    path: str | os.PathLike[str],
    *,
    metadata: ReportMetadata | None = None,
    engine: Literal['reportlab'] = 'reportlab',
    verbose: bool = False,
    language: Literal['en', 'es'] = 'en',
    part: int | np.integer[Any] = 2,
) -> str
```

Render a normalized flanking level difference `Dn,f` fiche to a PDF.

Writes the one-page airborne flanking-transmission report of the
ISO 10848 series: the standard-basis line naming the part governing
the tested construction, an optional metadata header, the per-band
`Dn,f` table beside the measured-versus-shifted-ISO 717-1
reference curve, the boxed single-number `Dn,f,w (C; Ctr)`, the
measurement statement, an optional requirement verdict and a footer.

**Parameters**

| Name | Description |
| :--- | :--- |
| `path` | Destination path of the PDF file. |
| `metadata` | Optional [`ReportMetadata`](https://docs.jmrp.io/phonometry/reference/api/building/insulation/#reportmetadata); `None` produces a lightweight fiche (body, rating 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 `Dn,f` 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). |
| `part` | The ISO 10848 part governing the tested construction and named in the basis line: `2` (lightweight elements, default, ISO 10848-2:2006), `3` (lightweight elements with a junction of substantial influence, ISO 10848-3:2006) or `4` (heavy, Type A elements, ISO 10848-4:2010). |

**Returns:** The written `path` as a `str`.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If `engine` is unknown, `part` is not 2, 3 or 4, or the result has no single-number rating (the band count is neither 16 nor 5). |
| ImportError | If reportlab is not installed (the `[report]` extra), or matplotlib is missing for the embedded figure (the `[plot]` extra). |

## modal_density

```python
modal_density(
    area: float,
    critical_frequency: float,
    *,
    speed_of_sound: float = 343.0,
) -> float
```

Modal density $n = \pi \cdot S \cdot f_\mathrm{c} / c_0^2$ (Part 4, (5)).

**Parameters**

| Name | Description |
| :--- | :--- |
| `area` | Element area `S`, in m². |
| `critical_frequency` | Critical frequency `fc`, in Hz. |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s. |

**Returns:** Modal density `n`, in modes per Hz.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any input is not positive/finite. |
| TypeError | if `area`, `critical_frequency` or `speed_of_sound` is not a single number. |

## modal_overlap_factor

```python
modal_overlap_factor(
    area: float,
    critical_frequency: float,
    structural_reverberation_time: float | np.floating[Any] | np.integer[Any],
    *,
    speed_of_sound: float = ...,
) -> float

modal_overlap_factor(
    area: float,
    critical_frequency: float,
    structural_reverberation_time: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    *,
    speed_of_sound: float = ...,
) -> NDArray[np.float64]

modal_overlap_factor(
    area: float,
    critical_frequency: float,
    structural_reverberation_time: NumericArrayLike,
    *,
    speed_of_sound: float = ...,
) -> float | NDArray[np.float64]
```

Modal overlap factor $M = 2.2 \cdot n / T_\mathrm{s}$ (Part 4, F. (6)).

With the modal density `n` from [`modal_density`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#modal_density). Part 4 prefers
$M \ge 1$ at 250 Hz and above, and requires bands with
$M < 0.25$ to be
bracketed in the report and excluded from the single-number rating
(Clause 9). This function only computes `M`; pass it to
[`vibration_reduction_index`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#vibration_reduction_index) via `modal_overlap` to apply the
bracketing and single-number exclusion.

**Parameters**

| Name | Description |
| :--- | :--- |
| `area` | Element area `S`, in m². |
| `critical_frequency` | Critical frequency `fc`, in Hz. |
| `structural_reverberation_time` | `Ts`, in s, per band (or a single value). |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s. |

**Returns:** Modal overlap factor `M` per band (dimensionless). A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If any input is not positive/finite. |
| TypeError | if `structural_reverberation_time` holds a text or a value that is not a real number. |

## normalized_flanking_impact_level

```python
normalized_flanking_impact_level(
    receive_level: NumericArrayLike,
    absorption_area: NumericArrayLike,
    *,
    reference_area: float = 10.0,
    fraction: Literal[1, 3] | np.integer[Any] | None = None,
) -> FlankingImpactLevelResult
```

Normalized flanking impact level `Ln,f` (Formula (5)).

$L_\mathrm{n,f} = L_2 + 10 \log_{10}(A/A_0)$ with the reference absorption
area $A_0 = 10$ m², from the receiving-room impact level with the
tapping machine on the source-room floor.

**Parameters**

| Name | Description |
| :--- | :--- |
| `receive_level` | Receiving-room average impact SPL `L2` per band, in dB. |
| `absorption_area` | Receiving-room equivalent absorption area `A` per band, in m². |
| `reference_area` | `A0`, in m² (default 10 m²). |
| `fraction` | Band set passed to [`phonometry.building.weighted_impact_rating`](https://docs.jmrp.io/phonometry/reference/api/building/ratings/#weighted_impact_rating), 3 for one-third octaves or 1 for octaves; read from the number of bands when `None`. One of `1` or `3`. |

**Returns:** A [`FlankingImpactLevelResult`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#flankingimpactlevelresult); the single-number rating is formed only for 16 (one-third-octave) or 5 (octave) bands.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | On incompatible band counts or non-positive areas. |
| TypeError | if `reference_area` is not a single number, or `fraction` is not an integer (a word, a flag or a float), or `absorption_area` or `receive_level` holds a text or a value that is not a real number. |

## normalized_flanking_level_difference

```python
normalized_flanking_level_difference(
    source_level: NumericArrayLike,
    receive_level: NumericArrayLike,
    absorption_area: NumericArrayLike,
    *,
    reference_area: float = 10.0,
    fraction: Literal[1, 3] | np.integer[Any] | None = None,
) -> FlankingLevelDifferenceResult
```

Normalized flanking level difference `Dn,f` (airborne, Formula (4)).

$D_\mathrm{n,f} = L_1 - L_2 - 10 \log_{10}(A/A_0)$ with the reference absorption
area $A_0 = 10$ m².

**Parameters**

| Name | Description |
| :--- | :--- |
| `source_level` | Source-room average SPL `L1` per band, in dB. |
| `receive_level` | Receiving-room average SPL `L2` per band, in dB. |
| `absorption_area` | Receiving-room equivalent absorption area `A` per band, in m². |
| `reference_area` | `A0`, in m² (default 10 m²). |
| `fraction` | Band set passed to [`phonometry.building.weighted_rating`](https://docs.jmrp.io/phonometry/reference/api/building/ratings/#weighted_rating), 3 for one-third octaves or 1 for octaves; read from the number of bands when `None`. One of `1` or `3`. |

**Returns:** A [`FlankingLevelDifferenceResult`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#flankingleveldifferenceresult); the single-number rating is formed only for 16 (one-third-octave) or 5 (octave) bands.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | On incompatible band counts or non-positive areas. |
| TypeError | if `reference_area` is not a single number, or `fraction` is not an integer (a word, a flag or a float), or `absorption_area`, `receive_level` or `source_level` holds a text or a value that is not a real number. |

## StrongCouplingCheck

```python
StrongCouplingCheck(
    velocity_level_difference: NDArray[np.float64],
    *,
    mass_i: float,
    mass_j: float,
    critical_frequency_i: float,
    critical_frequency_j: float,
    frequencies: NDArray[np.float64] | None = None,
)
```

The strong-coupling condition of Part 1, Formula (15), band by band.

Where the elements are so strongly coupled that they cannot be taken as
separate SEA subsystems, the measured `Kij` may not be relevant (Part
1, 4.3.1 a) and 4.3.3); the coupling is weak enough for it only where

$$
D_{\mathrm{v},ij} \ge 3 - 10 \lg \frac{m_i f_{\mathrm{c}j}}{m_j f_{\mathrm{c}i}}
$$

The difference is the one-way `Dv,ij` from element `i` to element
`j`, not the direction average: the threshold changes when `i` and
`j` swap, so each direction is judged on its own.

The threshold and the verdicts are read from the two elements and the
measured differences, so they are not fields: a check cannot be built
against another threshold.

**Attributes**

| Name | Description |
| :--- | :--- |
| `velocity_level_difference` | Velocity level difference `Dv,ij` per band, element `i` excited, in dB. |
| `mass_i` | Mass per unit area `mi` of element `i`, in kg/m². |
| `mass_j` | Mass per unit area `mj` of element `j`, in kg/m². |
| `critical_frequency_i` | Critical frequency `fci` of element `i`, in Hz. |
| `critical_frequency_j` | Critical frequency `fcj` of element `j`, in Hz. |
| `frequencies` | The band centre frequencies of the differences, in Hz, or `None` where the bands were not named; only the plot reads them. |

### StrongCouplingCheck.holds

*property*

Whether the inequality holds in each band.

Judged settled: for two like elements the threshold is 3 dB to the
last bits of the logarithm of a ratio that is 1 in decimal.

### StrongCouplingCheck.min_velocity_level_difference

*property*

The least `Dv,ij`, $3 - 10 \lg (m_i f_{\mathrm{c}j} / (m_j f_{\mathrm{c}i}))$, in dB.

### StrongCouplingCheck.passes

*property*

The verdict: the inequality holds in every band given.

In none of them, then, does strong coupling put `Kij` in doubt.

### StrongCouplingCheck.plot()

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

Plot `Dv,ij` band by band against the bound of Formula (15).

The bound $3 - 10 \lg (m_i f_{\mathrm{c}j} / (m_j f_{\mathrm{c}i}))$ is drawn across the bands with the side under it
shaded, where the elements are strongly coupled and `Kij` may not be
relevant, and a band where the inequality does not hold is marked.

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 `Dv,ij` curve. |

**Returns:** The axes.

## total_loss_factor

```python
total_loss_factor(
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: float | np.floating[Any] | np.integer[Any],
) -> float

total_loss_factor(
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

total_loss_factor(
    structural_reverberation_time: NumericArrayLike,
    *,
    frequencies: NumericArrayLike,
) -> float | NDArray[np.float64]
```

Total loss factor $\eta = 2.2 / (f \, T_\mathrm{s})$ (Clause 7.3.1).

**Parameters**

| Name | Description |
| :--- | :--- |
| `frequencies` | Band centre frequency `f`, in Hz, per band. |
| `structural_reverberation_time` | Structural reverberation time `Ts`, in s, per band (or a single value broadcast to all bands). |

**Returns:** Total loss factor `η` (dimensionless) per band. A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are not positive/finite or their band counts are incompatible. |
| TypeError | if `frequencies` or `structural_reverberation_time` holds a text or a value that is not a real number. |

## velocity_level_difference

```python
velocity_level_difference(
    source_level: float | np.floating[Any] | np.integer[Any],
    receive_level: float | np.floating[Any] | np.integer[Any],
) -> float

velocity_level_difference(
    source_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    receive_level: NumericArrayLike,
) -> NDArray[np.float64]

velocity_level_difference(
    source_level: float | np.floating[Any] | np.integer[Any],
    receive_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

velocity_level_difference(
    source_level: NumericArrayLike,
    receive_level: NumericArrayLike,
) -> float | NDArray[np.float64]
```

Velocity level difference $D_{\mathrm{v},ij} = L_{\mathrm{v},i} - L_{\mathrm{v},j}$ (Formula (8)).

**Parameters**

| Name | Description |
| :--- | :--- |
| `source_level` | Average velocity level `Lv,i` of the excited element, in dB, per band. |
| `receive_level` | Average velocity level `Lv,j` of the receiving element, in dB, per band. |

**Returns:** `Dv,ij` per band, in dB. A `float` when `source_level` and `receive_level` are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the inputs are empty, non-finite, or differ in length. |
| TypeError | if `receive_level` or `source_level` holds a text or a value that is not a real number. |

## vibration_reduction_index

```python
vibration_reduction_index(
    velocity_level_difference: NumericArrayLike,
    junction_length: float,
    area_i: float,
    area_j: float,
    *,
    frequencies: NumericArrayLike | None = None,
    structural_reverberation_time_i: NumericArrayLike | None = None,
    structural_reverberation_time_j: NumericArrayLike | None = None,
    speed_of_sound: float = 343.0,
    modal_overlap: NumericArrayLike | None = None,
) -> VibrationReductionResult
```

Vibration reduction index `Kij` (Formula (13), or simplified (14)).

$K_{ij} = \overline{D}_{\mathrm{v},ij} + 10 \log_{10}(l_{ij} / \sqrt{a_i a_j})$.
When the structural reverberation
times and the frequencies are supplied, the equivalent absorption lengths
`ai`, `aj` come from Formula (12) and the full Formula (13) is used.
Otherwise the lightweight, well-damped simplification
$a_j = S_j / l_0$ ($l_0 = 1$ m) applies and Formula (14),
$K_{ij} = \overline{D}_{\mathrm{v},ij} + 10 \log_{10}(l_{ij} / \sqrt{S_i S_j})$,
is used.

**Parameters**

| Name | Description |
| :--- | :--- |
| `velocity_level_difference` | Direction-averaged velocity level difference `D̄v,ij` (see [`direction_averaged_level_difference`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#direction_averaged_level_difference)), in dB, per band. |
| `junction_length` | Common-edge junction length `lij`, in m. |
| `area_i` | Area `Si` of element `i`, in m². |
| `area_j` | Area `Sj` of element `j`, in m². |
| `frequencies` | Band centre frequencies, in Hz. Required for Formula (12) and for the single-number mean; optional for the simplified form. |
| `structural_reverberation_time_i` | `Ts,i` per band (or a single value), in s. Supply together with `structural_reverberation_time_j` and `frequencies` to use Formula (12); omit for the simplified form. |
| `structural_reverberation_time_j` | `Ts,j` per band (or a single value), in s. |
| `speed_of_sound` | Speed of sound in air `c0`, in m/s. |
| `modal_overlap` | Modal overlap factor `M` per band for the heavier (least-overlapped) of the two elements (see [`modal_overlap_factor`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#modal_overlap_factor)). When supplied, bands with $M < 0.25$ are flagged as bracketed and excluded from the single-number `K̄ij` (ISO 10848-4:2010, Clause 9). |

**Returns:** A [`VibrationReductionResult`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#vibrationreductionresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | On incompatible band counts, non-positive geometry, or if only one of the two structural reverberation times is supplied. |
| TypeError | if `area_i`, `area_j` or `junction_length` is not a single number, or `frequencies`, `modal_overlap` or `velocity_level_difference` holds a text or a value that is not a real number, or `speed_of_sound` is not a single number. |

## vibration_reduction_index_from_flanking

```python
vibration_reduction_index_from_flanking(
    normalized_flanking_level_difference: NumericArrayLike,
    reduction_index_i: NumericArrayLike,
    reduction_index_j: NumericArrayLike,
    junction_length: float,
    area_i: float,
    area_j: float,
    absorption_length_i: NumericArrayLike,
    absorption_length_j: NumericArrayLike,
    *,
    reference_area: float = 10.0,
) -> float | NDArray[np.float64]
```

Indirect `Kij` from the normalized flanking level difference.

ISO 10848-1:2006, Clause 4.3.1 Note 2 (unnumbered):

$$
K_{ij} = D_\mathrm{n,f} - \frac{R_i + R_j}{2} - 10 \log_{10}\frac{\sqrt{a_i a_j}}{l_{ij}} + 10 \log_{10}\frac{\sqrt{S_i S_j}}{A_0}
$$

The standard warns this holds only for resonant-only transmission; measured
`R` also includes forced transmission, so a direct measurement of `Kij`
(Formula (13)) is preferred. Provided for completeness.

**Parameters**

| Name | Description |
| :--- | :--- |
| `normalized_flanking_level_difference` | `Dn,f` per band, in dB. |
| `reduction_index_i` | Sound reduction index `Ri` per band, in dB. |
| `reduction_index_j` | Sound reduction index `Rj` per band, in dB. |
| `junction_length` | `lij`, in m. |
| `area_i` | `Si`, in m². |
| `area_j` | `Sj`, in m². |
| `absorption_length_i` | `ai` per band, in m. |
| `absorption_length_j` | `aj` per band, in m. |
| `reference_area` | `A0`, in m² (default 10 m²). |

**Returns:** `Kij` per band, in dB. A `float` when `normalized_flanking_level_difference`, `reduction_index_i`, `reduction_index_j`, `absorption_length_i` and `absorption_length_j` are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | On incompatible band counts or non-positive geometry. |
| TypeError | if `area_i`, `area_j`, `junction_length` or `reference_area` is not a single number, or `absorption_length_i`, `absorption_length_j`, `normalized_flanking_level_difference`, `reduction_index_i` or `reduction_index_j` holds a text or a value that is not a real number. |

## VibrationReductionResult

```python
VibrationReductionResult(
    frequencies: NDArray[np.float64] | None,
    k_ij: NDArray[np.float64],
    modal_overlap: NDArray[np.float64] | None = None,
    fraction: Literal[1, 3] | None = None,
)
```

Per-band vibration reduction index `Kij` (ISO 10848-1:2006).

**Attributes**

| Name | Description |
| :--- | :--- |
| `frequencies` | Band centre frequencies, in Hz, or `None` when they were not supplied. |
| `k_ij` | Vibration reduction index `Kij` per band, in dB (Formula (13) or the simplified Formula (14)). |
| `single_number` | Arithmetic-mean single-number `K̄ij` over 200 Hz to 1250 Hz (one-third octave) or 125 Hz to 1000 Hz (octave) per Annex A, in dB, or `None` when the frequencies do not cover the corresponding band set. Bands bracketed for poor modal overlap (ISO 10848-4:2010 Clause 9) are excluded from the mean. |
| `bracketed` | Per-band boolean flags, `True` where the modal overlap factor is below 0.25 so the band is bracketed and excluded from the single-number rating (ISO 10848-4:2010 Clause 9), or `None` when no modal overlap was supplied. |
| `modal_overlap` | The modal overlap factor `M` per band the bands are bracketed by, or `None` when none was supplied. An octave band carries the smallest of its three one-third-octave bands, since it is bracketed when any of them is. |
| `fraction` | The band set the caller states for the Annex A range the single number is averaged over, 3 for one-third octaves or 1 for octaves, as `octave_bands` states it (`fraction=1`); `None` (the default, and what [`vibration_reduction_index`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#vibration_reduction_index) leaves) reads it from the spacing of the frequencies each time. One of `1` or `3`. |

`single_number` and `bracketed` are read from the fields, the
0.25 of ISO 10848-4 Clause 9 and the Annex A range, so they are not
fields.

### VibrationReductionResult.bracketed

*property*

Per band, whether the modal overlap is below 0.25 (ISO 10848-4 Clause 9).

`None` when no modal overlap was supplied.

### VibrationReductionResult.octave_bands()

```python
VibrationReductionResult.octave_bands() -> VibrationReductionResult
```

Combine one-third-octave `Kij` into octave bands.

$K_{ij,\mathrm{oct}} = -10 \log_{10}\!\left[ \tfrac{1}{3} \sum 10^{-K_{ij}/10} \right]$
over each group of three
one-third-octave bands (Part 2/3/4). Requires a band count that is a
multiple of three and, for the frequency labels, that frequencies were
supplied; supplied frequencies must group into whole octave triples
(lower/centre/upper one-third around an octave centre). The octave
single-number `K̄ij` is averaged over 125 Hz to 1000 Hz (Annex A).
An octave band is bracketed when any of its one-third-octave bands is.

**Returns:** A new [`VibrationReductionResult`](https://docs.jmrp.io/phonometry/reference/api/building/flanking-transmission/#vibrationreductionresult) on octave centres.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | If the band count is not a multiple of three, or the frequencies do not open on complete octave triples. |

### VibrationReductionResult.plot()

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

Plot `Kij` against frequency.

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

**Parameters**

| Name | Description |
| :--- | :--- |
| `language` | The language of the labels: `"en"` or `"es"`. |

### VibrationReductionResult.report()

```python
VibrationReductionResult.report(
    path: str | os.PathLike[str],
    *,
    metadata: ReportMetadata | None = None,
    engine: Literal['reportlab'] = 'reportlab',
    verbose: bool = False,
    language: Literal['en', 'es'] = 'en',
) -> str
```

Render a vibration reduction index `Kij` junction fiche to a PDF.

Writes the one-page ISO 10848-1:2006 junction-characterization report:
the standard-basis line, an optional metadata header, the per-band
`Kij` table beside the `Kij(f)` curve, the boxed single-number mean
`Kij` (Annex A band range) with the count of averaged and bracketed
bands, the measurement statement and a footer. Bands bracketed for poor
modal overlap (ISO 10848-4:2010 Clause 9) are printed in brackets and
excluded from the single number.

**Parameters**

| Name | Description |
| :--- | :--- |
| `path` | Destination path of the PDF file. |
| `metadata` | Optional [`ReportMetadata`](https://docs.jmrp.io/phonometry/reference/api/building/insulation/#reportmetadata); `None` produces a lightweight fiche (body, result and disclaimer only). |
| `engine` | Rendering back end; only `"reportlab"` is supported. |
| `verbose` | When `True`, the per-band table adds a column stating whether each band enters the single-number mean. |
| `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 or the result carries no band centre frequencies. |
| ImportError | If reportlab is not installed (the `[report]` extra), or matplotlib is missing for the embedded figure (the `[plot]` extra). |

### VibrationReductionResult.single_number

*property*

The Annex A mean `K̄ij` over the bands not bracketed, in dB, or `None`.
