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_{pA}^{\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_{pA}$ 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_{pA}^{\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],
    limit_db: NDArray[np.float64],
    satisfied: NDArray[np.bool_],
)

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

Attributes

property

Whether every octave with a printed limit meets it.

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_{pA}^{\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],
    apparent: bool,
    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

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,
    ratio_satisfied: bool,
    stateable: bool,
    stated_band_range_hz: tuple[float, float] | None,
    increased_uncertainty_band_range_hz: tuple[float, float] | None,
    excess_standard_deviation_db: float | None,
)

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

Attributes

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_{pA,e}$ or $D_{pA,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,
    required_positions: int,
    satisfied: bool,
    exceeds_maximum: bool,
)

Whether enough loudspeaker positions were used, 7.2.1.

Attributes

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