# noise_control.silencer_in_situ

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

Canonical: https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/
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-09-15
Updated: 2026-11-16T21:36:14Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: What a silencer does where it was installed (ISO 11820:1996).

---

What a silencer does where it was installed (ISO 11820:1996).

[`phonometry.noise_control.silencer_measurement`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-measurement/) is the laboratory
measurement a catalogue figure comes from: a qualified rig, a substitution
duct, a stated uncertainty. This is the other one. The silencer is in the
plant, the plant is running, and the question is what the thing is doing
there.

Clause 1.1 puts the relationship between the two in one sentence: results
obtained here **cannot be compared** with performance data obtained from
laboratory measurements to ISO 7235. The reason is in the Introduction: what
is measured in situ carries the flanking transmission, the regenerated flow
noise and the operating conditions with it, and the standard treats all three
as properties of the silencer in that installation rather than as errors to be
removed. A number from this module and a number from a data sheet are two
different quantities, and this library keeps them in two different modules so
that they cannot be added by accident.

Two quantities, twenty installations
------------------------------------

**Transmission loss** $D_\mathrm{ts}$ compares the sound power reaching the
silencer with the sound power leaving it, Equation (4). **Insertion loss**
$D_\mathrm{is}$ compares the plant without the silencer with the plant with it,
Equation (8), and it is the only choice for a blowdown silencer, which does
not exist as a duct element to measure through.

Neither is a bare subtraction of levels. Each starts as a sound pressure level
difference, Equation (1) or (3), and becomes a loss by adding the area ratio
of the two measurement surfaces and the difference of the two field
corrections:

$$
D_\mathrm{ts} = D_{\mathrm{t}p\mathrm{s}} + 10 \lg \frac{S_2}{S_1} + K_2 - K_1
$$

Which areas those are is not a matter of taste. Figure 1 enumerates twenty
installations, sixteen for transmission and four for insertion, by what stands
on each side of the silencer, and clause 9.1.3 gives each of them its own rule
for $S_1$ and $S_2$: a measurement surface in the duct, a quarter
or a half of the silencer intake, a quarter of the room absorption, or a
surface enveloping the open end. [`installation_case`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#installation_case) is that figure and
those rules as data, so that a measurement says which case it is and the areas
follow.

The corrections that are not a correction
-----------------------------------------

Clause 4 corrects for background noise from a **printed table**, not from the
usual logarithmic subtraction, and the two do not agree: at a margin of 5 dB
the table takes off 2 dB where the formula takes off 1.7, and at 8 dB it takes
off 1 where the formula takes off 0.7. [`silencer_background_correction`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#silencer_background_correction)
implements the table as printed, and says so.

Where the extraneous sound can be measured on its own, 9.1.1 and 9.1.2 offer
the energy route of Equations (17) and (18) instead, and cap it: **the maximum
correction is 3 dB**. A measurement that needs more than that does not yield
the quantity at all, and the clause says what may be stated instead, which is
an inequality. [`extraneous_corrected_mean_level`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#extraneous_corrected_mean_level) says whether the
correction went past the cap, so that a capped value cannot be reported as a
determination.

Clause 9.1.5 is the one prohibition worth reading twice: converting
one-third-octave data to octave data is permissible **for measured sound
pressure levels only, but not for level differences**.
[`octave_levels_from_third_octave`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#octave_levels_from_third_octave) does the permitted conversion, and
the docstring names the function in this library that does the forbidden one
for a different standard.

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

## DOWNSTREAM_DISTANCE_COEFFICIENTS

*Constant* (`tuple`).

```python
DOWNSTREAM_DISTANCE_COEFFICIENTS = (12.0, 10.0)
```

## extraneous_corrected_mean_level

```python
extraneous_corrected_mean_level(
    levels: NumericArrayLike,
    extraneous_levels: NumericArrayLike,
) -> ExtraneousCorrectionResult
```

The mean level with the extraneous sound taken off, Equations (17) and (18).

$$
\overline{L_{p1}} = 10 \lg \left[\frac{1}{N} \sum_j \left(10^{0.1 L_{pj}} - 10^{0.1 L_{ej}}\right)\right]
$$

printed $\overline{L_{p1}}$ in Equation (17) and
$\overline{L_{pI}}$ in Equation (18). The energy route 9.1.1 and 9.1.2 offer instead of Table 1, for the case
where the sources the silencer works on can be switched off and the
extraneous sound measured at the same positions: corrections are made
"using table 1 or the relationship" (9.1.1, printed folio 10, PDF page 18
of BS EN ISO 11820:1997).

The clause caps it: **the maximum correction is 3 dB**. Past that the
quantity is not determined, and what may be stated instead is the
inequality of clause 4. Clause 4.1 (folio 4, PDF page 12) ties that to a
correction of 3 dB that "is not sufficient", and Table 1 (folio 5, PDF
page 13) prints where that starts: a margin under 3 dB is invalid, and a
margin of 3 dB takes off 3 dB. The subtraction reaches 3.0206 dB at that
same margin, which is the printed 3 dB unrounded, so the cap is judged on
the margin of the two energy means, $\overline{L_p}$ of the levels
as measured (Equation (2)) over that of the extraneous levels:

$$
\overline{L_p} - \overline{L_e} \ge 3\ \mathrm{dB}
$$

That is the same condition as a correction of at most
$-10 \lg(1 - 10^{-0.3})$ dB, and it keeps the two routes of the
standard in agreement at their shared boundary.

The result's `capped` says whether the correction went past the cap, a
margin more than $10^{-9}$ dB under 3 dB, so that a capped number
cannot be written down as a determination, and a capped measurement also
emits a [`SilencerInSituWarning`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#silencerinsituwarning); a margin of exactly 3 dB emits
nothing. The corrected level itself is given either way.

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | The levels with everything running, in decibels. |
| `extraneous_levels` | The extraneous levels at the same positions, in decibels. |

**Returns:** The corrected mean level and the margin it was read at, as an [`ExtraneousCorrectionResult`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#extraneouscorrectionresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For inputs that do not match point for point, or an extraneous level at or above the level it is subtracted from. |
| TypeError | if `extraneous_levels` or `levels` holds a text or a value that is not a real number. |

## ExtraneousCorrectionResult

```python
ExtraneousCorrectionResult(corrected_level: float, margin_db: float)
```

The mean level with the extraneous sound taken off, and whether it is capped.

9.1.1 and 9.1.2 cap the correction at 3 dB, and Table 1 prints where that
starts: a margin of the two energy means under 3 dB. Whether the
correction went past the cap is read from the margin, so it is not a
field: a capped level cannot be written down as a determination.

**Attributes**

| Name | Description |
| :--- | :--- |
| `corrected_level` | The corrected mean level, printed $\overline{L_{p1}}$ in Equation (17) and $\overline{L_{pI}}$ in Equation (18), in decibels; given either way, capped or not. |
| `margin_db` | $\overline{L_p} - \overline{L_e}$, the margin of the energy mean of the levels as measured ($\overline{L_p}$ of Equation (2), before any correction) over that of the extraneous levels, in decibels. |

### ExtraneousCorrectionResult.capped

*property*

Whether the correction went past the 3 dB cap: a margin under 3 dB.

The cap is judged on the margin of the two energy means and not on the
correction itself: the printed 3 dB is what Table 1 takes off at its
3 dB row, which the subtraction writes unrounded as 3.0206 dB, so a
margin of exactly 3 dB is not capped. A margin is capped when it is
more than $10^{-9}$ dB under 3 dB: one closer than that counts
as 3 dB, on the side Table 1 accepts, since levels written 3.0 dB
apart come out of the two energy means up to
$1.4 \cdot 10^{-14}$ dB either side of it. That is when
[`extraneous_corrected_mean_level`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#extraneous_corrected_mean_level) emits a
[`SilencerInSituWarning`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#silencerinsituwarning).

## flow_velocity_m_s

```python
flow_velocity_m_s(
    velocity_pressure_pa: float | np.floating[Any] | np.integer[Any],
    density: float,
) -> float

flow_velocity_m_s(
    velocity_pressure_pa: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    density: float,
) -> NDArray[np.float64]

flow_velocity_m_s(
    velocity_pressure_pa: NumericArrayLike,
    density: float,
) -> float | NDArray[np.float64]
```

The flow velocity a velocity pressure stands for, Equation (28).

$w = \sqrt{2 p_\mathrm{v} / \rho}$.

**Parameters**

| Name | Description |
| :--- | :--- |
| `velocity_pressure_pa` | $p_\mathrm{v}$, in pascals. |
| `density` | $\rho$, in kilograms per cubic metre. |

**Returns:** $w$, in metres per second. A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive density or a negative velocity pressure. |
| TypeError | if `density` is not a single number, or `velocity_pressure_pa` holds a text or a value that is not a real number. |

## FLOW_VELOCITY_REPORT_DEVIATION_PERCENT

*Constant* (`float`).

```python
FLOW_VELOCITY_REPORT_DEVIATION_PERCENT = 10.0
```

## gas_density_kg_m3

```python
gas_density_kg_m3(
    *,
    temperature_c: float,
    molar_mass_kg_kmol: float | None = None,
    atmospheric_pressure_pa: float = 100000.0,
) -> float
```

The density of the gas, Equation (29).

$$
\rho = \frac{M \, p_{\text{amb}}}{R \, (273 + \theta)}
$$

with $R$ the universal gas constant, printed as 8 314.4 N m per
kmol K, and $M$ the molar mass. The standard adds that
$R/M = 287$ N m per kg K for air, and that is what is used when no
molar mass is given.

[`phonometry.noise_control.normal_air_density`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-measurement/#normal_air_density) computes the same
quantity for ISO 7235, from a gauge pressure and with that standard's own
two constants; this one takes the absolute ambient pressure the way
Equation (29) prints it and admits any gas through its molar mass.

**Parameters**

| Name | Description |
| :--- | :--- |
| `temperature_c` | $\theta$, in degrees Celsius. |
| `molar_mass_kg_kmol` | $M$, in kilograms per kilomole. Omit it for air. |
| `atmospheric_pressure_pa` | $p_{\text{amb}}$, in pascals. |

**Returns:** $\rho$, in kilograms per cubic metre.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a temperature that is not finite or at or below the absolute zero the equation uses, or a non-positive pressure or molar mass. |
| TypeError | if `atmospheric_pressure_pa`, `molar_mass_kg_kmol` or `temperature_c` is not a single number. |

## in_situ_insertion_loss

```python
in_situ_insertion_loss(
    levels_without: NumericArrayLike,
    levels_with: NumericArrayLike,
    *,
    area_without_m2: NumericArrayLike,
    area_with_m2: NumericArrayLike,
    frequencies: NumericArrayLike | None = None,
    field_correction_difference: NumericArrayLike = 0.0,
    case: int | np.integer[Any] | None = None,
) -> SilencerInSituResult
```

The insertion loss of a silencer in place, Equation (21).

$$
D_\mathrm{is} = \overline{L_{p\mathrm{II}}} - \overline{L_{p\mathrm{I}}} + 10 \lg \frac{S_\mathrm{II}}{S_\mathrm{I}} + K_\mathrm{II} - K_\mathrm{I}
$$

The same shape as Equation (19) with the two runs in place of the two
sides. NOTE 5 of 3.4 says that in most cases the two areas are equal and
the two field corrections nearly so, and then both terms fall out and the
loss is the level difference; the arguments are still explicit, because
"in most cases" is not "always" and cases 17 and 19 of Figure 1 are where
it fails.

A blowdown silencer can only be measured this way: there is no duct to
measure through.

As in Equation (19), the terms are band quantities (3.4, printed folio 3,
PDF page 11). Where the receiver side is a diffuse room, case 18 of
Figure 1, both areas are a quarter of the room absorption, Equations (10)
and (12), and move band by band with the reverberation time of each run:
pass the two arrays [`reverberant_surface_area_m2`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#reverberant_surface_area_m2) returns. Each area
and the field correction may be one value, applied to every band, or one
value per band.

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels_without` | $\overline{L_{p\mathrm{II}}}$ per band, in decibels. |
| `levels_with` | $\overline{L_{p\mathrm{I}}}$ per band, in decibels. |
| `area_without_m2` | $S_\mathrm{II}$, one value or one per band, in square metres. |
| `area_with_m2` | $S_\mathrm{I}$, one value or one per band, in square metres. |
| `frequencies` | Nominal band centres, in hertz. |
| `field_correction_difference` | $K_\mathrm{II} - K_\mathrm{I}$, one value or one per band, in decibels. |
| `case` | The installation of Figure 1, 17 to 20, carried into the result. |

**Returns:** The loss, as a [`SilencerInSituResult`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#silencerinsituresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For spectra that do not match, an area or a field correction that is neither one value nor one per band, a non-positive area or band centre, a field correction that is not finite, or a case that is not an insertion one. |
| TypeError | if `case` is a flag, a text or an array where a count goes, or `area_with_m2`, `area_without_m2`, `field_correction_difference` or `frequencies` holds a text or a value that is not a real number. |

## in_situ_transmission_loss

```python
in_situ_transmission_loss(
    source_levels: NumericArrayLike,
    receiver_levels: NumericArrayLike,
    *,
    source_area_m2: NumericArrayLike,
    receiver_area_m2: NumericArrayLike,
    frequencies: NumericArrayLike | None = None,
    field_correction_difference: NumericArrayLike = 0.0,
    case: int | np.integer[Any] | None = None,
) -> SilencerInSituResult
```

The transmission loss of a silencer in place, Equation (19).

$$
D_\mathrm{ts} = D_{\mathrm{t}p\mathrm{s}} + 10 \lg \frac{S_2}{S_1} + K_2 - K_1
$$

The level difference of Equation (1), the ratio of the two measurement
areas, and the difference of the two field corrections.
[`installation_case`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#installation_case) says which areas the installation calls for;
[`temperature_field_correction`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#temperature_field_correction) is the correction difference two
temperatures make.

Every term is a band quantity (3.3, printed folio 3, PDF page 11). A
measurement surface in a duct is one area for all bands, but where a side
is a room with a diffuse field its area is a quarter of the absorption,
$(6 \ln 10) V / (c T)$, and moves with the reverberation time from
band to band: pass the array [`reverberant_surface_area_m2`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#reverberant_surface_area_m2) returns.
Each area and the field correction may be one value, applied to every
band, or one value per band.

**Parameters**

| Name | Description |
| :--- | :--- |
| `source_levels` | $\overline{L_{p2}}$ per band, in decibels. |
| `receiver_levels` | $\overline{L_{p1}}$ per band, in decibels. |
| `source_area_m2` | $S_2$, one value or one per band, in square metres. |
| `receiver_area_m2` | $S_1$, one value or one per band, in square metres. |
| `frequencies` | Nominal band centres, in hertz. |
| `field_correction_difference` | $K_2 - K_1$, one value or one per band, in decibels. |
| `case` | The installation of Figure 1, 1 to 16, carried into the result. |

**Returns:** The loss, as a [`SilencerInSituResult`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#silencerinsituresult).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For spectra that do not match, an area or a field correction that is neither one value nor one per band, a non-positive area or band centre, a field correction that is not finite, or a case that is not a transmission one. |
| TypeError | if `case` is a flag, a text or an array where a count goes, or `field_correction_difference`, `frequencies`, `receiver_area_m2` or `source_area_m2` holds a text or a value that is not a real number. |

## insertion_level_difference

```python
insertion_level_difference(
    levels_without: float | np.floating[Any] | np.integer[Any],
    levels_with: float | np.floating[Any] | np.integer[Any],
) -> float

insertion_level_difference(
    levels_without: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    levels_with: NumericArrayLike,
) -> NDArray[np.float64]

insertion_level_difference(
    levels_without: float | np.floating[Any] | np.integer[Any],
    levels_with: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

insertion_level_difference(
    levels_without: NumericArrayLike,
    levels_with: NumericArrayLike,
) -> float | NDArray[np.float64]
```

The level difference the silencer made, Equation (3).

$D_{\mathrm{i}p\mathrm{s}} = L_{p\mathrm{II}} - L_{p\mathrm{I}}$, the level before the silencer was
installed less the level after. Here II is *without* and I is *with*,
which is again the opposite of the reading order, so the arguments say
which run they are.

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels_without` | $L_{p\mathrm{II}}$ per band, in decibels. |
| `levels_with` | $L_{p\mathrm{I}}$ per band, in decibels. |

**Returns:** $D_{\mathrm{i}p\mathrm{s}}$ per band, in decibels. A `float` when `levels_without` and `levels_with` are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For spectra that do not match band for band. |
| TypeError | if `levels_with` or `levels_without` holds a text or a value that is not a real number. |

## installation_case

```python
installation_case(number: int | np.integer[Any]) -> InstallationCase
```

One installation of Figure 1, with the area rules clause 9 gives it.

The figure is a matrix: the source side may be a duct, a room with a
diffuse field, a room with a non-diffuse field or an open space, and so
may the receiver side, which is sixteen transmission cases. The four
insertion cases are keyed by the receiver side alone, because the source
side is not part of what is measured.

**Parameters**

| Name | Description |
| :--- | :--- |
| `number` | The case number Figure 1 prints, 1 to 20. |

**Returns:** The case, as an [`InstallationCase`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#installationcase).

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a number outside the figure. |
| TypeError | if `number` is a flag, a text or an array where a count goes. |

## INSTALLATION_CASES

*Constant* (`mapping`).

## InstallationCase

```python
InstallationCase(
    number: int,
    source_side: Literal['duct', 'diffuse_room', 'non_diffuse_room', 'open_space'] | Literal['any'],
    receiver_side: Literal['duct', 'diffuse_room', 'non_diffuse_room', 'open_space'],
    quantity: Literal['transmission', 'insertion'],
    source_area_rule: str,
    receiver_area_rule: str,
)
```

One of the twenty installations of Figure 1, with its area rules.

**Attributes**

| Name | Description |
| :--- | :--- |
| `number` | The case number Figure 1 prints, 1 to 20. |
| `source_side` | What stands on the source side: `"duct"`, `"diffuse_room"`, `"non_diffuse_room"`, `"open_space"`, or `"any"` for the four insertion cases, whose source side is not part of the case. |
| `receiver_side` | The same for the receiver side. One of `"duct"`, `"diffuse_room"`, `"non_diffuse_room"` or `"open_space"`. |
| `quantity` | `"transmission"` for cases 1 to 16, `"insertion"` for 17 to 20. |
| `source_area_rule` | How 9.1.3 or 9.1.4 says to read $S_2$, the source side of a transmission case, or $S_\mathrm{II}$, the run without the silencer of an insertion one, in the clause's own words. |
| `receiver_area_rule` | The same for $S_1$ or $S_\mathrm{I}$. |

## ISO11820_AIR_GAS_CONSTANT_J_KG_K

*Constant* (`float`).

```python
ISO11820_AIR_GAS_CONSTANT_J_KG_K = 287.0
```

## ISO11820_ATMOSPHERIC_PRESSURE_PA

*Constant* (`float`).

```python
ISO11820_ATMOSPHERIC_PRESSURE_PA = 100000.0
```

## ISO11820_BACKGROUND_CORRECTIONS

*Constant* (`mapping`).

```python
ISO11820_BACKGROUND_CORRECTIONS = {3: 3.0, 4: 2.0, 5: 2.0, 6: 1.0, 7: 1.0, 8: 1.0, 9: 0.5, 10: 0.5}
```

## ISO11820_MIN_BACKGROUND_MARGIN_DB

*Constant* (`float`).

```python
ISO11820_MIN_BACKGROUND_MARGIN_DB = 3.0
```

## ISO11820_MOLAR_GAS_CONSTANT_J_KMOL_K

*Constant* (`float`).

```python
ISO11820_MOLAR_GAS_CONSTANT_J_KMOL_K = 8314.4
```

## ISO11820_NEGLIGIBLE_BACKGROUND_MARGIN_DB

*Constant* (`float`).

```python
ISO11820_NEGLIGIBLE_BACKGROUND_MARGIN_DB = 10.0
```

## ISO11820_OCTAVE_BAND_EXTENDED_RANGE_HZ

*Constant* (`tuple`).

```python
ISO11820_OCTAVE_BAND_EXTENDED_RANGE_HZ = (31.5, 8000.0)
```

## ISO11820_OCTAVE_BAND_RANGE_HZ

*Constant* (`tuple`).

```python
ISO11820_OCTAVE_BAND_RANGE_HZ = (63.0, 4000.0)
```

## ISO11820_SPEED_OF_SOUND_M_S

*Constant* (`float`).

```python
ISO11820_SPEED_OF_SOUND_M_S = 340.0
```

## ISO11820_THIRD_OCTAVE_BAND_EXTENDED_RANGE_HZ

*Constant* (`tuple`).

```python
ISO11820_THIRD_OCTAVE_BAND_EXTENDED_RANGE_HZ = (25.0, 10000.0)
```

## ISO11820_THIRD_OCTAVE_BAND_RANGE_HZ

*Constant* (`tuple`).

```python
ISO11820_THIRD_OCTAVE_BAND_RANGE_HZ = (50.0, 5000.0)
```

## MAX_EXTRANEOUS_CORRECTION

*Constant* (`float`).

```python
MAX_EXTRANEOUS_CORRECTION = 3.0
```

## measurement_distance_downstream_m

```python
measurement_distance_downstream_m(
    downstream_area: float,
    free_area_m2: float,
) -> float
```

How far downstream the measurement surface stands, Equation (16).

$d_\mathrm{d} = 12 \sqrt{S_\mathrm{d}} - 10 \sqrt{S_\mathrm{f}}$, with $S_\mathrm{f}$ the free
cross-sectional area of the silencer, which NOTE 18 warns is not the same
thing as its total intake cross-section.

The expression can return zero or less for a silencer whose free area is a
large fraction of the duct it sits in. 8.3.1 has its own escape for that,
which is agreement between the parties on the distances, and the case is
reported rather than returned as a distance nobody can stand at.

**Parameters**

| Name | Description |
| :--- | :--- |
| `downstream_area` | $S_\mathrm{d}$, in square metres. |
| `free_area_m2` | $S_\mathrm{f}$, in square metres. |

**Returns:** $d_\mathrm{d}$, in metres.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive area. |
| TypeError | if `downstream_area` or `free_area_m2` is not a single number. |

## measurement_distance_upstream_m

```python
measurement_distance_upstream_m(upstream_area: float) -> float
```

How far upstream the measurement surface stands, Equation (15).

$d_\mathrm{u} = 1.5 \sqrt{4 S_\mathrm{u} / \pi}$, which is one and a half equivalent
diameters of the upstream measurement cross-section.

**Parameters**

| Name | Description |
| :--- | :--- |
| `upstream_area` | $S_\mathrm{u}$, in square metres. |

**Returns:** $d_\mathrm{u}$, in metres.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive area. |
| TypeError | if `upstream_area` is not a single number. |

## octave_levels_from_third_octave

```python
octave_levels_from_third_octave(
    levels: NumericArrayLike,
) -> NDArray[np.float64]
```

One-third-octave levels folded into octaves, 9.1.5.

The energy sum of each consecutive group of three. Clause 9.1.5 permits
this conversion **for measured sound pressure levels only, but not for
level differences**, and that sentence is the whole of the clause.

The prohibition is worth stating twice, because this library does perform
the forbidden operation for a different standard:
[`phonometry.noise_control.octave_insertion_loss`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-measurement/#octave_insertion_loss) folds a
one-third-octave insertion loss into octaves, which is Equation (2) of
ISO 11691 and is exactly what ISO 11820 forbids. The two are not
interchangeable: one is a fold of a measured level, the other a fold of a
difference, and ISO 11820 wants the levels folded on each side and the
difference taken afterwards.

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | One-third-octave levels, in decibels, a multiple of three bands in ascending order. |

**Returns:** The octave levels, in decibels.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a count that is not a multiple of three. |
| TypeError | if `levels` holds a text or a value that is not a real number. |

## reverberant_surface_area_m2

```python
reverberant_surface_area_m2(
    volume_m3: float,
    reverberation_time_s: float | np.floating[Any] | np.integer[Any],
    *,
    speed_of_sound: float = ...,
) -> float

reverberant_surface_area_m2(
    volume_m3: float,
    reverberation_time_s: 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]

reverberant_surface_area_m2(
    volume_m3: float,
    reverberation_time_s: NumericArrayLike,
    *,
    speed_of_sound: float = ...,
) -> float | NDArray[np.float64]
```

A quarter of the room absorption, as an area, Equations (6), (10) and (12).

$$
S = \frac{6 \ln 10 \; V}{c \, T}
$$

The three equations are the same expression written three times, for the
receiver room of the transmission measurement and for the room with and
without the silencer of the insertion one. It is a quarter of the Sabine
equivalent absorption area, which is what turns a reverberant level into a
sound power.

The standard prints $c = 340$ m/s "at room temperature"; that value
is the default here and a measurement at another temperature should say
so.

**Parameters**

| Name | Description |
| :--- | :--- |
| `volume_m3` | The room volume, in cubic metres. |
| `reverberation_time_s` | The reverberation time per band, in seconds. |
| `speed_of_sound` | The speed of sound, in metres per second. |

**Returns:** The area, in square metres. A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive volume, time or speed. |
| TypeError | if `speed_of_sound` or `volume_m3` is not a single number, or `reverberation_time_s` holds a text or a value that is not a real number. |

## SABINE_AREA_COEFFICIENT

*Constant* (`float`).

```python
SABINE_AREA_COEFFICIENT = 13.815510557964275
```

## silencer_background_correction

```python
silencer_background_correction(
    level_difference: float | np.floating[Any] | np.integer[Any],
) -> float

silencer_background_correction(
    level_difference: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

silencer_background_correction(
    level_difference: NumericArrayLike,
) -> float | NDArray[np.float64]
```

The background correction of Table 1, in decibels to subtract.

The table is printed stepped and integer-indexed, and it is **not** the
logarithmic subtraction $-10 \lg(1 - 10^{-0.1 \Delta L})$ that most
emission standards use: at a margin of 5 dB it takes off 2 dB where the
formula takes off 1.7, and at 8 dB it takes off 1 where the formula takes
off 0.7. It is implemented as printed.

The table gives no row between its integers. A difference that falls
between two rows is read at the lower one, which is the larger correction
and therefore the lower source level; the standard does not decide this,
and the choice is stated here rather than smoothed away. Above
[`ISO11820_NEGLIGIBLE_BACKGROUND_MARGIN_DB`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#iso11820_negligible_background_margin_db) there is no row to read
at all: 10 dB is the last one the table prints, and anything over it takes
nothing off, so 10.5 dB is corrected by zero rather than by the 0.5 dB of
the 10 dB row.

**Parameters**

| Name | Description |
| :--- | :--- |
| `level_difference` | The difference between the level measured with the source running and the background level alone, in decibels. |

**Returns:** The correction to subtract, in decibels. A `float` for a number, an array for a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a margin under [`ISO11820_MIN_BACKGROUND_MARGIN_DB`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#iso11820_min_background_margin_db), which Table 1 calls invalid. |
| TypeError | if `level_difference` holds a text or a value that is not a real number. |

## silencer_flow_velocity_m_s

```python
silencer_flow_velocity_m_s(
    upstream_mean_velocity_m_s: float,
    *,
    upstream_area: float,
    free_area_m2: float,
) -> float
```

The mean velocity inside the silencer, Equation (31).

$\overline{w_\mathrm{f}} = (S_\mathrm{u} / S_\mathrm{f}) \, \overline{w_\mathrm{u}}$, the upstream mean
velocity scaled by how much the silencer narrows the passage. It is the
velocity the regenerated noise of the installation answers to, which is
why 9.2 asks for it rather than for the duct velocity.

**Parameters**

| Name | Description |
| :--- | :--- |
| `upstream_mean_velocity_m_s` | $\overline{w_\mathrm{u}}$, in metres per second, the arithmetic mean of Equation (30). |
| `upstream_area` | $S_\mathrm{u}$, in square metres. |
| `free_area_m2` | $S_\mathrm{f}$, the free cross-section, in square metres. |

**Returns:** $\overline{w_\mathrm{f}}$, in metres per second.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive area. |
| TypeError | if `free_area_m2`, `upstream_area` or `upstream_mean_velocity_m_s` is not a single number. |

## silencer_mean_sound_pressure_level

```python
silencer_mean_sound_pressure_level(levels: NumericArrayLike) -> float
```

The mean level over the measuring points, Equation (2).

$$
\overline{L_p} = 10 \lg \left(\frac{1}{N} \sum_j 10^{0.1 L_{pj}}\right)
$$

An energy mean, which is what every clause of the standard means by "mean
sound pressure level".

**Parameters**

| Name | Description |
| :--- | :--- |
| `levels` | The levels at the measuring points, in decibels. |

**Returns:** $\overline{L_p}$, in decibels.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For an empty or non-finite set of levels. |
| TypeError | if `levels` holds a text or a value that is not a real number. |

## silencer_sound_power_level

```python
silencer_sound_power_level(
    mean_level: float | np.floating[Any] | np.integer[Any],
    *,
    area: float | np.floating[Any] | np.integer[Any],
    field_correction: float | np.floating[Any] | np.integer[Any] = ...,
) -> float

silencer_sound_power_level(
    mean_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    *,
    area: NumericArrayLike,
    field_correction: NumericArrayLike = ...,
) -> NDArray[np.float64]

silencer_sound_power_level(
    mean_level: float | np.floating[Any] | np.integer[Any],
    *,
    area: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    field_correction: NumericArrayLike = ...,
) -> NDArray[np.float64]

silencer_sound_power_level(
    mean_level: float | np.floating[Any] | np.integer[Any],
    *,
    area: float | np.floating[Any] | np.integer[Any],
    field_correction: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

silencer_sound_power_level(
    mean_level: NumericArrayLike,
    *,
    area: NumericArrayLike,
    field_correction: NumericArrayLike = ...,
) -> float | NDArray[np.float64]
```

A mean level read as a sound power, Equations (5), (7), (9) and (11).

$$
L_W = \overline{L_p} + 10 \lg \frac{S}{S_0} + K, \qquad S_0 = 1\ \text{m}^2
$$

The four equations differ only in which side of the silencer and which run
they belong to. $S$ is whichever area the case calls for, from
[`installation_case`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#installation_case), and $K$ the field correction of Annex A,
which NOTE 4 expects to stay under
[`TYPICAL_FIELD_CORRECTION_LIMIT_DB`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#typical_field_correction_limit_db) in absolute value once the areas
have been chosen as 3.3 and 3.4 define them.

**Parameters**

| Name | Description |
| :--- | :--- |
| `mean_level` | $\overline{L_p}$ per band, in decibels. |
| `area` | $S$, in square metres. |
| `field_correction` | $K$, in decibels. |

**Returns:** $L_W$ per band, in decibels. A `float` when `mean_level`, `area` and `field_correction` are all numbers, an array when one of them is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a non-positive area or mismatched shapes. |
| TypeError | if `area`, `field_correction` or `mean_level` holds a text or a value that is not a real number. |

## SilencerInSituResult

```python
SilencerInSituResult(
    frequencies: NDArray[np.float64] | None,
    level_difference: NDArray[np.float64],
    area_term_db: NDArray[np.float64],
    field_correction_difference: NDArray[np.float64],
    loss: NDArray[np.float64],
    quantity: Literal['transmission', 'insertion'],
    case: InstallationCase | None,
)
```

A silencer measured where it stands, ISO 11820 Equation (19) or (21).

**Attributes**

| Name | Description |
| :--- | :--- |
| `frequencies` | Nominal band centres, in hertz, or `None`. |
| `level_difference` | $D_{\mathrm{t}p\mathrm{s}}$ or $D_{\mathrm{i}p\mathrm{s}}$, the sound pressure level difference the loss is built on, per band. |
| `area_term_db` | $10 \lg(S_2/S_1)$ or $10 \lg(S_\mathrm{II}/S_\mathrm{I})$ per band, in decibels. Always one value per band, even where both areas were given as single values, because the area of a diffuse room moves with the reverberation time from band to band. |
| `field_correction_difference` | $K_2 - K_1$ or $K_\mathrm{II} - K_\mathrm{I}$ per band, in decibels, on the same shape. |
| `loss` | $D_\mathrm{ts}$ or $D_\mathrm{is}$ per band, in decibels. |
| `quantity` | `"transmission"` or `"insertion"`. |
| `case` | The installation of Figure 1 the measurement was made in, or `None` where the caller did not name one. |

### SilencerInSituResult.plot()

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

Draw the level difference and the loss it becomes.

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 `phonometry._plot.noise_control.plot_silencer_in_situ`. |

**Returns:** The `Axes`.

### SilencerInSituResult.symbol

*property*

The symbol clause 11 reports this as, `"D_ts"` or `"D_is"`.

## SilencerInSituWarning

The measurement is outside a condition ISO 11820 states.

Emitted for three conditions:

- an extraneous-sound correction past the 3 dB cap of 9.1.1 and 9.1.2,
  where clause 4 leaves only an inequality to state: a margin of the two
  energy means more than $10^{-9}$ dB under 3 dB
  ([`ExtraneousCorrectionResult.capped`](https://docs.jmrp.io/phonometry/reference/api/noise_control/silencer-in-situ/#extraneouscorrectionresultcapped)). A margin of exactly 3 dB
  takes off 3.02 dB, the printed 3 dB unrounded, and emits nothing;
- a field correction over the 3 dB in absolute value NOTE 4 of 3.3
  expects;
- a downstream distance Equation (16) cannot give, which 8.3.1 leaves to
  agreement between the parties.

## static_pressure_difference_pa

```python
static_pressure_difference_pa(
    total_pressure_loss_pa: float,
    *,
    volume_flow: float,
    density: float,
    upstream_area: float,
    downstream_area: float,
) -> float
```

The static pressure difference behind a change of area, Equation (14).

$$
\Delta p_\mathrm{S} = \Delta p_\mathrm{T} - \frac{\rho \, q_V^2}{2} \left(\frac{1}{S_\mathrm{u}^2} - \frac{1}{S_\mathrm{d}^2}\right)
$$

For a silencer whose inlet and outlet areas differ, where the gas
temperature does not vary markedly. With equal areas the bracket vanishes
and the two pressure differences are the same number, which is what 3.5
says in words.

**Parameters**

| Name | Description |
| :--- | :--- |
| `total_pressure_loss_pa` | $\Delta p_\mathrm{T}$, in pascals. |
| `volume_flow` | $q_V$, in cubic metres per second. |
| `density` | $\rho$, in kilograms per cubic metre. |
| `upstream_area` | $S_\mathrm{u}$, in square metres. |
| `downstream_area` | $S_\mathrm{d}$, in square metres. |

**Returns:** $\Delta p_\mathrm{S}$, in pascals.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a value that is not finite, or a non-positive density or area. |
| TypeError | if `density`, `downstream_area`, `total_pressure_loss_pa`, `upstream_area` or `volume_flow` is not a single number. |

## temperature_field_correction

```python
temperature_field_correction(
    *,
    receiver_temperature_c: float,
    source_temperature_c: float,
) -> float
```

The field correction difference two temperatures make, Equations (20) and (22).

$$
K_2 - K_1 = 5 \lg \frac{273 + \theta_1}{273 + \theta_2}
$$

Unless Annex A gives a reason to say otherwise, the field corrections
account for markedly different temperatures on the two sides and for
nothing else. The standard explains the term by the speed of sound alone,
and that is where the ratio comes out upside down: the factor from squared
pressure to power is the characteristic impedance, and at one ambient
pressure the standard's own Equation (29) makes the density fall as
$1/T$ while $c$ rises as $\sqrt{T}$, so
$\rho c$ falls as $T^{-1/2}$ and the correction rises with
temperature. The printed form is returned unchanged, because a reader
holding ISO 11820 has to find the standard's own number; the defect is
registered in `docs/ERRATA.md` under "ISO 11820:1996, Equations (20) and
(22)".

The same expression is Equation (22) with the two runs of an insertion
measurement in place of the two sides: there $\theta_\mathrm{I}$ is the
temperature with the silencer and $\theta_\mathrm{II}$ without, and the
correction it returns is $K_\mathrm{II} - K_\mathrm{I}$. Pass the with-silencer
temperature as the receiver one and the without-silencer temperature as
the source one, which is the ordering the two equations share.

The standard writes 273 rather than 273.15, and that is what is used.

**Parameters**

| Name | Description |
| :--- | :--- |
| `receiver_temperature_c` | $\theta_1$ on the receiver side, or $\theta_\mathrm{I}$ with the silencer, in degrees Celsius. |
| `source_temperature_c` | $\theta_2$ on the source side, or $\theta_\mathrm{II}$ without the silencer, in degrees Celsius. |

**Returns:** $K_2 - K_1$ or $K_\mathrm{II} - K_\mathrm{I}$, in decibels.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For a temperature that is not finite or at or below the absolute zero the equation uses. |
| TypeError | if `receiver_temperature_c` or `source_temperature_c` is not a single number. |

## total_pressure_loss_pa

```python
total_pressure_loss_pa(
    upstream_total_pressure_pa: float,
    downstream_total_pressure_pa: float,
) -> float
```

The total pressure loss of the silencer, Equation (13).

$\Delta p_\mathrm{T} = \overline{p_\mathrm{Tu}} - \overline{p_\mathrm{Td}}$, the mean total
pressure upstream less the mean total pressure downstream, each of them
the arithmetic mean of Equations (23) and (25). Where the inlet and outlet
areas are equal and neither temperature nor density changes much, this is
also the static pressure difference.

**Parameters**

| Name | Description |
| :--- | :--- |
| `upstream_total_pressure_pa` | $\overline{p_\mathrm{Tu}}$, in pascals, as a difference from the ambient pressure. |
| `downstream_total_pressure_pa` | $\overline{p_\mathrm{Td}}$, in pascals, on the same basis. |

**Returns:** $\Delta p_\mathrm{T}$, in pascals.

**Raises**

| Exception | When |
| :--- | :--- |
| TypeError | if `downstream_total_pressure_pa` or `upstream_total_pressure_pa` is not a single number. |

## transmission_level_difference

```python
transmission_level_difference(
    source_levels: float | np.floating[Any] | np.integer[Any],
    receiver_levels: float | np.floating[Any] | np.integer[Any],
) -> float

transmission_level_difference(
    source_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    receiver_levels: NumericArrayLike,
) -> NDArray[np.float64]

transmission_level_difference(
    source_levels: float | np.floating[Any] | np.integer[Any],
    receiver_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

transmission_level_difference(
    source_levels: NumericArrayLike,
    receiver_levels: NumericArrayLike,
) -> float | NDArray[np.float64]
```

The level difference across the silencer, Equation (1).

$D_{\mathrm{t}p\mathrm{s}} = \overline{L_{p2}} - \overline{L_{p1}}$, the mean level on
the source side less the mean level on the receiver side. The arguments
are named for the side rather than for the subscript, because 1 is the
receiver and 2 the source, which is the opposite of the order most readers
expect.

NOTE 2 of 3.1: this is not a result of its own but the step Equation (19)
turns into a transmission loss.

**Parameters**

| Name | Description |
| :--- | :--- |
| `source_levels` | $\overline{L_{p2}}$ per band, in decibels. |
| `receiver_levels` | $\overline{L_{p1}}$ per band, in decibels. |

**Returns:** $D_{\mathrm{t}p\mathrm{s}}$ per band, in decibels. A `float` when `source_levels` and `receiver_levels` are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For spectra that do not match band for band. |
| TypeError | if `receiver_levels` or `source_levels` holds a text or a value that is not a real number. |

## TYPICAL_FIELD_CORRECTION_LIMIT_DB

*Constant* (`float`).

```python
TYPICAL_FIELD_CORRECTION_LIMIT_DB = 3.0
```

## UPSTREAM_DISTANCE_DIAMETERS

*Constant* (`float`).

```python
UPSTREAM_DISTANCE_DIAMETERS = 1.5
```

## velocity_pressure_pa

```python
velocity_pressure_pa(
    total_pressure_pa: float | np.floating[Any] | np.integer[Any],
    static_pressure_pa: float | np.floating[Any] | np.integer[Any],
) -> float

velocity_pressure_pa(
    total_pressure_pa: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
    static_pressure_pa: NumericArrayLike,
) -> NDArray[np.float64]

velocity_pressure_pa(
    total_pressure_pa: float | np.floating[Any] | np.integer[Any],
    static_pressure_pa: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]

velocity_pressure_pa(
    total_pressure_pa: NumericArrayLike,
    static_pressure_pa: NumericArrayLike,
) -> float | NDArray[np.float64]
```

The velocity pressure, Equation (27).

$p_\mathrm{v} = p_\mathrm{T} - p_\mathrm{S}$, the total pressure less the static pressure, both
reported as differences from the ambient atmospheric pressure as 8.3.2
asks.

**Parameters**

| Name | Description |
| :--- | :--- |
| `total_pressure_pa` | $p_\mathrm{T}$, in pascals. |
| `static_pressure_pa` | $p_\mathrm{S}$, in pascals. |

**Returns:** $p_\mathrm{v}$, in pascals. A `float` when `total_pressure_pa` and `static_pressure_pa` are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

**Raises**

| Exception | When |
| :--- | :--- |
| ValueError | For inputs that do not match. |
| TypeError | if `static_pressure_pa` or `total_pressure_pa` holds a text or a value that is not a real number. |
