noise_control.cabin_insulation

What a cabin keeps out, measured in the room it stands in (ISO 11957).

An enclosure keeps noise in; a cabin keeps it out. ISO 11957:1996 measures the second, and it measures it as one subtraction: put the cabin in a sound field, measure the level in the room and the level inside the empty cabin, and take the difference band by band.

That is Equation (1) in the laboratory. Equation (2) is the same arithmetic in situ, where the room need not be diffuse, and the answer carries a prime to say so: $D_p^{\prime }$. Equation (3) is the A-weighted difference $D_{p\mathrm{A}}^{\prime }$, and the standard defines it only for the third of its three methods, the one that drives the room with the noise that is actually there. There is no unprimed $D_{p\mathrm{A}}$ in this document, and cabin_insulation refuses to compute one.

• laboratory, clause 6, in a reverberation room to ISO 3741, with at least two loudspeaker positions;
• in situ with a loudspeaker, 7.2.1, in any room at all, where the number of source positions is not fixed in advance but read off the spread of the answer itself (check_source_positions);
• in situ with the actual noise, 7.2.2, where the machinery of the workplace is the source, which is the only method that yields $D_{p\mathrm{A}}^{\prime }$.

Only results from the same method may be compared, which is why the method is a field of CabinInsulationResult and not a remark in a docstring.

Every equation of clauses 6 to 9 is implemented, plus the numeric acceptance rules the clauses state: the source-position criterion of 7.2.1, the flatness of the driving spectrum of 6.4, the clearance of 6.2, the background margins, and the volume ratio clause 10 attaches its uncertainty to. The single-number rating of clause 8 is handed to phonometry.building.weighted_rating, which is ISO 717-1 with $D_p$ written where that standard writes $R$, and the background correction is handed to phonometry.emission.reverberation_background_correction, which is the ISO 3741 the clauses point at.

The leak ratio of definition 3.14 and the seal ratio of its note are printed word for word as in ISO 11546, so they are imported from phonometry.noise_control.enclosure_insulation rather than written twice. The scope is tighter here: ISO 11546 only prefers a leak ratio under 2 %, while clause 1 of ISO 11957 makes it a condition of applicability.

Instrumentation, mounting, the ten operations of every movable part and the report template are procedure, and procedure is not arithmetic. The one piece of clause 11 that computes is the rounding of 11.4 e), which is CabinInsulationResult.rounded.

The document prints no worked example, so the tests are anchored on the algebraic identities of the subtraction, on the printed thresholds, and on the identity that makes estimated_cabin_noise_insulation agree with its own inputs.

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

Constant (mapping).

BAND_FLATNESS_LIMIT_DB = {125.0: 6.0, 250.0: 5.0}

BandFlatnessCheck(
    octave_centres_hz: NDArray[np.float64],
    spread_db: NDArray[np.float64],
)

How flat the driving spectrum is inside each octave, 6.4 and 7.2.1.

The limits are the clause’s, so they are read from the octave and are not fields: a check cannot be built against another limit.

Attributes

property

Whether every octave with a printed limit meets it.

property

What 6.4 allows in each octave, in decibels.

Returns: 6 dB at 125 Hz, 5 dB at 250 Hz and 4 dB above, and nan in the octaves below 125 Hz, for which the clause prints no limit.

property

Whether each octave meets its limit.

Judged settled: three readings 6,0 dB apart in decimal are within the 6 dB of 125 Hz whichever way the last bits of their difference fall. An octave with no printed limit is reported as satisfied.

cabin_insulation(
    room_levels: ArrayLike,
    cabin_levels: ArrayLike,
    *,
    frequencies: ArrayLike | None = None,
    method: CabinMethod = 'laboratory',
    band_fraction: int = 3,
    room_background_levels: ArrayLike | None = None,
    cabin_background_levels: ArrayLike | None = None,
    a_weighted_room_level: float | None = None,
    a_weighted_cabin_level: float | None = None,
    internal_noise_level: float | None = None,
) -> CabinInsulationResult

Sound pressure insulation of a cabin, Equations (1), (2) and (3).

One function for the three equations, because the three are the same subtraction and what separates them is the method, not the arithmetic:

in the laboratory, the same in situ under the name $D_p^{\prime }$, and the A-weighted difference $D_{p\mathrm{A}}^{\prime }=(L_{pA}{)}_{\text{room}}-(L_{pA}{)}_{\text{cabin}}$ when the source is the noise of the workplace. Definition 3.7 ties that last one to the actual-noise method alone, so an A-weighted pair given under another method is refused rather than quietly renamed.

Where a background spectrum is supplied it is taken off first, by the ISO 3741 correction 6.4 asks for, and a margin under MIN_SIGNAL_TO_BACKGROUND_DB is reported.

Parameters

Returns: The insulation, as a CabinInsulationResult.

Raises

CabinInsulationResult(
    frequencies: NDArray[np.float64] | None,
    room_levels: NDArray[np.float64],
    cabin_levels: NDArray[np.float64],
    insulation: NDArray[np.float64],
    a_weighted_insulation: float | None,
    internal_noise_level: float | None,
    method: str,
    band_fraction: int,
)

The sound pressure insulation of a cabin, band by band.

Attributes

Whether the answer carries the prime (apparent) is read from the method, so it is not a field.

property

Whether the answer carries the prime of 3.6.

The word “apparent” says the measurement was carried out in situ (3.6, NOTE 2), so it is read from the method: both in-situ methods give $D_p^{\prime }$, the laboratory method $D_p$.

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

Draw the two levels and the difference between them.

Requires matplotlib (pip install phonometry[plot]).

Parameters

Returns: The Axes.

CabinInsulationResult.rounded() -> NDArray[np.int_]

The band values as 11.4 e) reports them, to the nearest decibel.

property

The symbol clause 12 reports this as, "D_p" or "D'_p".

The measurement is outside a condition ISO 11957 states.

CabinUncertainty(method: str, volume_ratio: float)

What clause 10 will and will not say about a measurement.

Everything but the method and the volume ratio is what clause 10 prints for that method and ratio, so it is read from them and is not a field.

Attributes

property

What this method adds to the standard deviation of the laboratory one, in decibels, or None.

property

The range where a larger uncertainty is expected, in hertz, or None.

property

Whether the volume ratio reaches MIN_ROOM_TO_CABIN_VOLUME_RATIO, judged settled.

property

Whether clause 10 offers any figure at all.

It does not for the actual-noise method, which it sends to ISO 4871 instead.

property

The range the statement covers, in hertz, or None when nothing is stateable.

check_band_flatness(
    third_octave_levels: ArrayLike,
    *,
    frequencies: ArrayLike,
) -> BandFlatnessCheck

Is the driving spectrum flat enough inside each octave? 6.4 and 7.2.1.

An octave-band measurement only means what the standard says it means if the sound that produced it was spread evenly across the octave. The clause puts a number on that: the three one-third-octave levels inside one octave shall not differ by more than 6 dB in the octave of 125 Hz, 5 dB in the one of 250 Hz and 4 dB in the bands of higher frequencies. Nothing is printed for the octaves below 125 Hz, so nothing is claimed for them here.

Parameters

Returns: One row per octave, as a BandFlatnessCheck.

Raises

check_source_positions(
    insulation_by_position: ArrayLike,
) -> SourcePositionCheck

Were there enough loudspeaker positions? 7.2.1.

The only acceptance criterion in the document that is read off the answer rather than fixed in advance: the number of source positions shall be at least the largest difference, in decibels, between the $D_p^{\prime }$ of any two positions, in octave bands. Three positions to begin with, six at most, and a spread past six goes in the report.

The clause says octave bands, and it says so because the spread of a one-third-octave answer is the wider one. A one-third-octave measurement is therefore folded to octaves at the level, by energy-summing the room and the cabin spectra, before the difference is formed; folding the difference itself is not the same number, so this function takes the octave-band $D_p^{\prime }$ already formed and does not pretend to do that conversion.

Parameters

Returns: The verdict, as a SourcePositionCheck.

Raises

Constant (float).

DEFAULT_BAND_FLATNESS_LIMIT_DB = 4.0

estimated_cabin_noise_insulation(
    spectrum_levels: ArrayLike,
    insulation: ArrayLike,
    *,
    frequencies: ArrayLike,
) -> float

What a cabin is worth against a stated spectrum, Annex A.

Both formulas of the annex, which differ only in whether $D_p$ or $D_p^{\prime }$ is substituted:

with $L_A=10\lg {\sum }_{i}10^{0,1(L_i-A_i)}$ the A-weighted total of the assumed spectrum. The sign of $A_i$ is the trap: the annex prints an attenuation, positive where the weighting takes level away, while this library’s band corrections are the correction itself, so $A_i=-C_k$. Both terms are built here from the same table, so the total and the sum cannot disagree, and an insulation of zero returns exactly zero.

The annex assumes a diffuse field and says so; in situ it will usually not be, and nothing here is corrected for flanking through the floor.

Parameters

Returns: $D_{p\mathrm{A},\mathrm{e}}$ or $D_{p\mathrm{A},\mathrm{e}}^{\prime }$, in decibels.

Raises

Constant (float).

IN_SITU_EXCESS_STANDARD_DEVIATION_DB = 2.0

Constant (tuple).

INCREASED_UNCERTAINTY_BAND_RANGE_HZ = (50.0, 200.0)

Constant (float).

INTERNAL_NOISE_CENTRE_HEIGHT_M = 1.55

Constant (float).

INTERNAL_NOISE_CENTRE_TOLERANCE_M = 0.075

Constant (tuple).

INTERNAL_NOISE_CORRECTION_WINDOW_DB = (6.0, 10.0)

internal_noise_level(
    levels: ArrayLike,
    *,
    background_level: float | None = None,
) -> float

The noise a cabin makes on its own, $L_{pA}$ of 6.7.

The A-weighted levels measured at the three positions on the 0,3 m sphere, or over the inclined circular path, averaged on a mean-square basis with the external sources switched off.

The background rule of 6.7 is not the one of 6.4. The margin over the background must reach MIN_SIGNAL_TO_BACKGROUND_DB, and the correction is made only while the margin stays inside INTERNAL_NOISE_CORRECTION_WINDOW_DB: past the top of that window the correction is under a tenth of a decibel and the clause does not ask for it. The correction itself is the $K_1$ of ISO 3741, $-10\lg (1-10^{-0,1\Delta L})$, applied to the A-weighted total rather than band by band, which is what makes it a separate line here from phonometry.emission.reverberation_background_correction.

Parameters

Returns: $L_{pA}$, in decibels.

Raises

Constant (float).

LOW_BAND_CLEARANCE_M = 2.0

Constant (tuple).

LOW_BAND_CLEARANCE_RANGE_HZ = (50.0, 80.0)

Constant (float).

MAX_LEAK_RATIO = 0.02

Constant (float).

MAX_MICROPHONE_TO_CABIN_M = 5.0

Constant (int).

MAX_SOURCE_POSITIONS_IN_SITU = 6

Constant (int).

MIN_FIXED_MICROPHONE_POSITIONS = 6

Constant (int).

MIN_LOUDSPEAKER_POSITIONS = 2

Constant (float).

MIN_LOUDSPEAKER_SEPARATION_M = 3.0

Constant (float).

MIN_MICROPHONE_HEIGHT_M = 1.0

Constant (float).

MIN_ROOM_TO_CABIN_VOLUME_RATIO = 20.0

Constant (float).

MIN_SIGNAL_TO_BACKGROUND_DB = 6.0

Constant (int).

MIN_SOURCE_POSITIONS_IN_SITU = 3

Constant (float).

MIN_SOURCE_TO_CABIN_M = 2.0

Constant (float).

MIN_SOURCE_TO_MICROPHONE_IN_SITU_M = 3.0

Constant (float).

MIN_SOURCE_TO_MICROPHONE_M = 2.0

minimum_cabin_clearance_m(
    lowest_band_frequency_hz: float,
    *,
    speed_of_sound: float = 343.0,
) -> float

How far the cabin stands from the room, 6.2.

Half a wavelength at the centre of the lowest band of interest, between the cabin and the walls, the ceiling and any diffusing element alike. Below 100 Hz the clause stops computing and fixes a flat LOW_BAND_CLEARANCE_M, which at 50 Hz is less than the half wavelength the rule above it would have asked for: the low-frequency sentence relaxes the requirement rather than tightening it, and it is written here exactly as printed.

Parameters

Returns: The least clearance, in metres.

Raises

Constant (float).

OPERATOR_PATH_INCLINATION_DEG = 45.0

Constant (float).

OPERATOR_SPHERE_RADIUS_M = 0.3

Constant (float).

PREFERRED_SIGNAL_TO_BACKGROUND_DB = 12.0

SourcePositionCheck(positions_used: int, max_octave_spread_db: float)

Whether enough loudspeaker positions were used, 7.2.1.

The rule is the clause’s, so only what was measured is a field: the positions used and the spread between them. How many the spread calls for, and the verdict, are read from those two the way 7.2.1 reads them, so a check cannot be built against another rule.

Attributes

property

Whether the spread runs past MAX_SOURCE_POSITIONS_IN_SITU.

7.2.1 says so shall be stated in the report.

property

The fewest positions the spread calls for, 7.2.1.

Returns: The spread in decibels rounded up, never below MIN_SOURCE_POSITIONS_IN_SITU nor above MAX_SOURCE_POSITIONS_IN_SITU.

property

Whether positions_used reaches required_positions.

Constant (tuple).

STATED_UNCERTAINTY_BAND_RANGE_HZ = (250.0, 10000.0)

uncertainty_conditions(
    *,
    room_volume_m3: float,
    cabin_volume_m3: float,
    method: CabinMethod = 'laboratory',
) -> CabinUncertainty

What clause 10 is willing to say about this measurement.

In the laboratory the uncertainty of ISO 3741 carries over from 250 Hz to 10 kHz, but only while the room is at least MIN_ROOM_TO_CABIN_VOLUME_RATIO times the volume of the cabin; below that ratio, and from 50 Hz to 200 Hz in any case, a larger uncertainty is expected. The loudspeaker method in situ adds about IN_SITU_EXCESS_STANDARD_DEVIATION_DB to the standard deviation. For the actual-noise method the clause states nothing at all and sends a declared value to ISO 4871.

Parameters

Returns: The statement, as a CabinUncertainty.

Raises

Constant (float).

WALL_CLEARANCE_FACTOR = 0.5

weighted_cabin_insulation(
    insulation: ArrayLike,
    *,
    apparent: bool = False,
    band_fraction: int = 3,
) -> WeightedCabinInsulation

The single-number rating of a cabin, clause 8.

ISO 717-1 with $D_p$ or $D_p^{\prime }$ written where that standard writes the sound reduction index: the reference curve, the shift and the adaptation terms come from phonometry.building.weighted_rating, and what is done here is the trim to the rating bands and the prime.

Clause 4 calls this the preferred single number and then warns against reading too much into it, because what a cabin is worth depends on the spectrum it stands in. estimated_cabin_noise_insulation is the answer to that objection.

Parameters

Returns: The rating, as a WeightedCabinInsulation.

Raises

WeightedCabinInsulation(
    rating: int,
    c: int,
    ctr: int,
    unfavourable_sum: float,
    band_centres_hz: NDArray[np.float64],
    apparent: bool,
)

The single-number rating of a cabin, clause 8 by way of ISO 717-1.

Attributes