Ir al contenido

noise_control: cabin insulation

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

Every name on this page is published by phonometry.noise_control: from phonometry import noise_control, then noise_control.<name>.

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: . Equation (3) is the A-weighted difference , 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 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 .

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 written where that standard writes , 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, and so are the band ranges, so they are written once and published by phonometry.noise_control.enclosure_insulation, the module of the older document, rather than a second time here. 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_frequencies: 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

Name Description
octave_frequencies The nominal octave centre frequencies read, in hertz.
spread_db The difference between the loudest and the quietest of the three one-third-octave bands in each, in decibels.

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

The verdict: every octave with a printed limit meets it.

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 within it.

cabin_insulation(
room_levels: NumericArrayLike,
cabin_levels: NumericArrayLike,
*,
frequencies: NumericArrayLike | None = None,
method: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'] = 'laboratory',
fraction: Literal[1, 3] | np.integer[Any] = 3,
room_background_levels: NumericArrayLike | None = None,
cabin_background_levels: NumericArrayLike | 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 , and the A-weighted difference 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 ISO11957_MIN_BACKGROUND_MARGIN_DB is reported.

Parameters

Name Description
room_levels per band, in decibels.
cabin_levels per band, in decibels.
frequencies Nominal band centres, in hertz.
method "laboratory" (default), "in-situ-loudspeaker" or "in-situ-actual-noise".
fraction The band set, 3 for one-third octaves (default) or 1 for octaves. One of 1 or 3.
room_background_levels Background in the room per band, in decibels, for the correction of 7.2.2.
cabin_background_levels Background inside the cabin per band, in decibels, for the correction of 6.4.
a_weighted_room_level , in decibels.
a_weighted_cabin_level , in decibels.
internal_noise_level of 6.7, in decibels, carried into the result because 11.4 reports it beside the insulation.

Returns: The insulation, as a CabinInsulationResult.

Raises

Exception When
ValueError For spectra that do not match, an unknown method or band fraction, or an A-weighted pair under a method that does not define one.
TypeError if fraction is not an integer (a word, a flag or a float), a_weighted_cabin_level, a_weighted_room_level or internal_noise_level is not a single number, or cabin_background_levels, cabin_levels, frequencies, room_background_levels or room_levels holds a text or a value that is not a real number, or method is not a text.
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: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'],
fraction: Literal[1, 3],
)

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

Attributes

Name Description
frequencies Nominal band centre frequencies, in hertz, or None when the levels were given without them.
room_levels , in decibels, after any background correction.
cabin_levels , in decibels, after any background correction.
insulation or per band, in decibels.
a_weighted_insulation of Equation (3), in decibels, or None. Defined only for the actual-noise method.
internal_noise_level of 6.7, in decibels, or None when the cabin has no integral source.
method "laboratory", "in-situ-loudspeaker" or "in-situ-actual-noise".
fraction The band set, 3 for one-third octaves or 1 for octaves. One of 1 or 3.

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 , the laboratory method .

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

Draw the two levels and the difference between them.

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_cabin_insulation.

Returns: The Axes.

property

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: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'],
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

Name Description
method The method the statement is about. One of "laboratory", "in-situ-loudspeaker" or "in-situ-actual-noise".
volume_ratio .

CabinUncertainty.excess_standard_deviation_db

Section titled “CabinUncertainty.excess_standard_deviation_db”

property

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

CabinUncertainty.increased_uncertainty_band_range_hz

Section titled “CabinUncertainty.increased_uncertainty_band_range_hz”

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: NumericArrayLike,
*,
frequencies: NumericArrayLike,
) -> 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

Name Description
third_octave_levels The one-third-octave levels of the sound in the room, in decibels.
frequencies Their nominal centre frequencies, in hertz.

Returns: One row per octave, as a BandFlatnessCheck.

Raises

Exception When
ValueError For inputs that do not match, a frequency that names no one-third-octave band, a band given twice, or an octave that is not covered by its three bands.
TypeError if frequencies or third_octave_levels holds a text or a value that is not a real number.
check_source_positions(
insulation_by_position: NumericArrayLike,
) -> 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 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 already formed and does not pretend to do that conversion.

Parameters

Name Description
insulation_by_position in octave bands, one row per source position and one column per band, in decibels.

Returns: The verdict, as a SourcePositionCheck.

Raises

Exception When
ValueError For fewer than MIN_SOURCE_POSITIONS_IN_SITU positions, or an array that is not rectangular.
TypeError if insulation_by_position holds a text or a value that is not a real number.

Constant (float).

DEFAULT_BAND_FLATNESS_LIMIT_DB = 4.0
estimated_cabin_noise_insulation(
spectrum_levels: NumericArrayLike,
insulation: NumericArrayLike,
*,
frequencies: NumericArrayLike,
) -> float

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

Both formulas of the annex, which differ only in whether or is substituted:

with the A-weighted total of the assumed spectrum. The sign of 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 . 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

Name Description
spectrum_levels , the assumed noise spectrum per band, in decibels.
insulation or per band, in decibels.
frequencies Nominal band centres, in hertz.

Returns: or , in decibels.

Raises

Exception When
ValueError For inputs that do not match band for band.
TypeError if frequencies, insulation or spectrum_levels holds a text or a value that is not a real number.

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_CENTER_HEIGHT_M = 1.55

Constant (float).

INTERNAL_NOISE_CENTER_TOLERANCE_M = 0.075

Constant (tuple).

INTERNAL_NOISE_CORRECTION_WINDOW_DB = (6.0, 10.0)
internal_noise_level(
levels: NumericArrayLike,
*,
background_level: float | None = None,
) -> float

The noise a cabin makes on its own, 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 ISO11957_MIN_BACKGROUND_MARGIN_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 of ISO 3741, , 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

Name Description
levels The A-weighted levels at the microphone positions, in decibels.
background_level The A-weighted background inside the cabin with the integral sources switched off, in decibels.

Returns: , in decibels.

Raises

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

Constant (float).

ISO11957_MIN_BACKGROUND_MARGIN_DB = 6.0

Constant (float).

ISO11957_PREFERRED_BACKGROUND_MARGIN_DB = 12.0

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
min_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

Name Description
lowest_band_frequency_hz The centre frequency of the lowest band of interest, in hertz.
speed_of_sound Speed of sound in the room, in metres per second.

Returns: The least clearance, in metres.

Raises

Exception When
ValueError For a non-positive frequency or speed.
TypeError if lowest_band_frequency_hz or speed_of_sound is not a single number.

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

Constant (float).

OPERATOR_PATH_INCLINATION_DEG = 45.0

Constant (float).

OPERATOR_SPHERE_RADIUS_M = 0.3
SourcePositionCheck(n_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

Name Description
n_positions_used , the number of source positions measured.
max_octave_spread_db The largest difference in between any two positions, over the octave bands, in decibels.

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

The verdict: n_positions_used reaches n_required_positions.

Constant (tuple).

STATED_UNCERTAINTY_BAND_RANGE_HZ = (250.0, 10000.0)
uncertainty_conditions(
*,
room_volume_m3: float,
cabin_volume_m3: float,
method: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'] = '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

Name Description
room_volume_m3 , in cubic metres.
cabin_volume_m3 , in cubic metres.
method "laboratory" (default), "in-situ-loudspeaker" or "in-situ-actual-noise".

Returns: The statement, as a CabinUncertainty.

Raises

Exception When
ValueError For a non-positive volume or an unknown method.
TypeError if cabin_volume_m3 or room_volume_m3 is not a single number, or method is not a text.

Constant (float).

WALL_CLEARANCE_FACTOR = 0.5
weighted_cabin_insulation(
insulation: NumericArrayLike,
*,
method: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'] = 'laboratory',
fraction: Literal[1, 3] | np.integer[Any] = 3,
) -> WeightedCabinInsulation

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

ISO 717-1 with or 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

Name Description
insulation or over the 16 one-third-octave rating bands or the 5 octave ones, in decibels.
method The method the spectrum was measured by, "laboratory" (default), "in-situ-loudspeaker" or "in-situ-actual-noise", as cabin_insulation takes it. It decides whether the rating is or .
fraction The band set, 3 for one-third octaves (default) or 1 for octaves. One of 1 or 3.

Returns: The rating, as a WeightedCabinInsulation.

Raises

Exception When
ValueError For a spectrum that is not the rating bands, an unknown method or a band set other than 1 or 3.
TypeError if fraction is not an integer (a word, a flag or a float), or insulation holds a text or a value that is not a real number, or method is not a text.
WeightedCabinInsulation(
rating: int,
c: int,
ctr: int,
unfavorable_sum: float,
frequencies: NDArray[np.float64],
method: Literal['laboratory', 'in-situ-loudspeaker', 'in-situ-actual-noise'],
)

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

Attributes

Name Description
rating or , in decibels.
c The spectrum adaptation term , in decibels.
ctr The spectrum adaptation term , in decibels.
unfavorable_sum The sum of unfavourable deviations at the shift the rating was read at, in decibels.
frequencies The bands the rating was read over, in hertz.
method The method the spectrum was measured by: "laboratory", "in-situ-loudspeaker" or "in-situ-actual-noise".

Whether the rating carries the prime of 3.9 (apparent) is read from the method, as on CabinInsulationResult, so it is not a field.

property

Whether the rating carries the prime of 3.9.

Read from the method as CabinInsulationResult.apparent reads it: both in-situ methods give , the laboratory method .