emission.workstation
What the ISO 11200 group shares: the emission sound pressure level at a work station, its two corrections and its uncertainty.
The sound power level says how much noise a machine makes. The emission sound pressure level says how much of it reaches the person working at it, and it is the number a machine is declared and bought by. ISO 4871 already has this library declaring ; nothing computed it until now.
Five standards determine it, and they differ only in how they get rid of the room:
| Part | How it gets rid of the room |
|---|---|
| ISO 11201:2010 | Free field over a reflecting plane, so there is no room to get rid of and . |
| ISO 11202:2010 | Two approximate routes to , one for a machine with a dominating source and one from the directivity the work station sees. |
| ISO 11203:1995 | No sound-pressure measurement at the work station: the level is derived from the sound power level, which was itself determined somehow. |
| ISO 11204:2010 | The same piecewise as ISO 11202 method A.2, reached accurately rather than approximately. |
| ISO 11205:2003 | By sound intensity, and not implemented here. |
Everything they share is in this module, transcribed once, and each part’s own method sits beside it in its own module.
The quantity. ISO 11201:2010 Equation (7), ISO 11202:2010 Equation (10) and ISO 11204:2010 Equation (9) print one law three times,
where is what the meter read, removes the background noise and removes the reflections the room sent back. ISO 11201 prints it without the term because its environment is qualified so that the term is negligible, which is the same equation with a zero in it.
Peak levels take no correction at all. ISO 11204:2010 clause 7 and
ISO 11202:2010 clause 8 both say so: is reported as
measured. A correction derived from mean-square pressures has no meaning for a
single largest excursion. Nothing here can tell a peak level from any other,
since both arrive as a number of decibels, so this is a rule for the caller and
not a guard: do not put a peak level through
emission_sound_pressure_level.
The background correction is the same expression the sound-power side
already uses, ISO 3744:2010 Equation (16), but this group sets its own
thresholds: 15 dB of margin makes it negligible, and 6 dB (grade 2) or 3 dB
(grade 3) is as far down as a result may be claimed. Below that the correction
is clamped and the level becomes an upper bound, which is why
background_noise_correction_at_workstation reports the clamp rather than
raising: the reading is still worth reporting, it just stops being a
determination.
The local environmental correction is where the group divides. Both ISO 11202 Equation (A.5) and ISO 11204 Equations (A.2)/(A.5) print the same piecewise function of one dimensionless ratio ,
and differ only in how is reached. The two branches meet: at the middle branch gives dB, so the 7 dB cap is the curve’s own value rounded, not a discontinuity.
The uncertainty is one pair of equations in all three measuring parts (ISO 11201 Equations (10) and (11), ISO 11202 (13) and (14), ISO 11204 (12) and (13)):
with the reproducibility of the method and the instability of the machine itself, estimated from repeated measurements by Equation (C.1).
Sources (clean-room, implemented from the standard texts): ISO 11201:2010, ISO 11202:2010 and its Amendment 1:2020, ISO 11203:1995 and its Amendment 1:2020, ISO 11204:2010, with the worked examples of ISO 11200:2014 Annex B.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
background_noise_correction_at_workstation
Section titled “background_noise_correction_at_workstation”background_noise_correction_at_workstation( measured_level: NumericArrayLike, background_level: NumericArrayLike, *, grade: Literal['engineering', 'survey'] = 'engineering',) -> WorkstationBackgroundCorrectionBackground-noise correction for the ISO 11200 group.
ISO 11201:2010 Equation (5), ISO 11202:2010 Equation (8) and
ISO 11204:2010 Equation (7), one expression printed three times. It is the
same closed form as ISO 3744:2010 Equation (16) on the sound-power side, and
this group puts its own thresholds around it, which
WorkstationBackgroundCorrection applies. A held correction emits
a SoundPowerWarning.
Parameters
| Name | Description |
|---|---|
measured_level |
The reading with the machine running, , in decibels; a scalar or one value per band. |
background_level |
The reading with it stopped, , in decibels, of the same shape. |
grade |
'engineering' (grade 2, 6 dB) or 'survey' (grade 3, 3 dB), which sets how far down a determination may be claimed. |
Returns: The correction, as a WorkstationBackgroundCorrection: in its correction, and in its upper_bound whether the background held it anywhere.
Raises
| Exception | When |
|---|---|
| ValueError | If the two arguments do not have the same shape, or the grade is neither of the two. |
| TypeError | if grade is not a text, or background_level or measured_level holds a text or a value that is not a real number. |
DEFAULT_COVERAGE_FACTOR
Section titled “DEFAULT_COVERAGE_FACTOR”Constant (float).
DEFAULT_COVERAGE_FACTOR = 1.6emission_expanded_uncertainty
Section titled “emission_expanded_uncertainty”emission_expanded_uncertainty( total_standard_deviation_db: float, coverage_factor: float = 1.6,) -> floatExpanded uncertainty .
ISO 11201:2010 Equation (11), ISO 11202:2010 Equation (14) and ISO 11204:2010 Equation (13). The coverage factor is the caller’s to choose: gives the two-sided 95 % interval of a normal distribution, while the worked examples of ISO 11200:2014 Annex B all print , which is the one-sided factor used when the result is compared with a limit value, and is this function’s default.
Parameters
| Name | Description |
|---|---|
total_standard_deviation_db |
in decibels. |
coverage_factor |
(default DEFAULT_COVERAGE_FACTOR). |
Returns: in decibels.
Raises
| Exception | When |
|---|---|
| ValueError | If either argument is negative. |
| TypeError | if coverage_factor or total_standard_deviation_db is not a single number. |
emission_sound_pressure_level
Section titled “emission_sound_pressure_level”emission_sound_pressure_level( measured_level: float | np.floating[Any] | np.integer[Any], *, background_correction: float | np.floating[Any] | np.integer[Any] = ..., local_correction: float | np.floating[Any] | np.integer[Any] = ...,) -> float
emission_sound_pressure_level( measured_level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], *, background_correction: NumericArrayLike = ..., local_correction: NumericArrayLike = ...,) -> NDArray[np.float64]
emission_sound_pressure_level( measured_level: float | np.floating[Any] | np.integer[Any], *, background_correction: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], local_correction: NumericArrayLike = ...,) -> NDArray[np.float64]
emission_sound_pressure_level( measured_level: float | np.floating[Any] | np.integer[Any], *, background_correction: float | np.floating[Any] | np.integer[Any] = ..., local_correction: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],) -> NDArray[np.float64]
emission_sound_pressure_level( measured_level: NumericArrayLike, *, background_correction: NumericArrayLike = ..., local_correction: NumericArrayLike = ...,) -> float | NDArray[np.float64]The emission sound pressure level, reading less both corrections.
ISO 11201:2010 Equation (7) (which prints no because its environment makes the term negligible), ISO 11202:2010 Equation (10) and ISO 11204:2010 Equation (9).
Never call this for a peak level. ISO 11202:2010 clause 8 and ISO 11204:2010 clause 7 both forbid correcting , which is reported exactly as measured: neither correction has a meaning for a single largest excursion, both being derived from mean-square pressures. A peak level reaches this function as an ordinary number of decibels and cannot be recognised, so the rule is the caller’s to keep.
Parameters
| Name | Description |
|---|---|
measured_level |
The uncorrected reading , in decibels. |
background_correction |
in decibels (default 0). |
local_correction |
in decibels (default 0). |
Returns: in decibels; a float when the reading and the two corrections are all numbers; an array of their broadcast shape when one is a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if background_correction, local_correction or measured_level holds a text or a value that is not a real number. |
EmissionPressureResult
Section titled “EmissionPressureResult”EmissionPressureResult( level: float | NDArray[np.float64], measured_level: float | NDArray[np.float64], background_correction: float | NDArray[np.float64], local_correction: float | NDArray[np.float64], grade: Literal['engineering', 'survey'], *, background_margin_db: float | NDArray[np.float64], standard: str,)An emission sound pressure level and the two corrections behind it.
Attributes
| Name | Description |
|---|---|
level |
Emission sound pressure level , in decibels re 20 uPa: what the meter read, less both corrections. |
measured_level |
The uncorrected reading , in decibels. |
background_correction |
, in decibels. |
local_correction |
, in decibels. |
grade |
Accuracy grade the determination earns. One of "engineering" or "survey". |
background_margin_db |
, the margin of the reading over the background, in decibels, a scalar or one per band; upper_bound is read from it and the grade’s minimum. |
standard |
The part of the group the determination followed. |
EmissionPressureResult.plot()
Section titled “EmissionPressureResult.plot()”EmissionPressureResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the reading, the two corrections and what is left of them.
Parameters
| Name | Description |
|---|---|
ax |
Existing axes, or None to create a figure. |
language |
Label language, "en" (default) or "es". |
kwargs |
Forwarded to the bars’ Axes.bar. |
Returns: The axes.
Raises
| Exception | When |
|---|---|
| TypeError | for x, height or bottom, which the plot sets itself: each bar stands where the reading and its corrections put it. |
EmissionPressureResult.upper_bound
Section titled “EmissionPressureResult.upper_bound”property
Whether the background margin fell below the grade’s minimum.
The level is then an upper bound rather than a determination
(MIN_BACKGROUND_MARGIN_DB: 6 dB for grade 2, 3 dB for
grade 3), judged on the settled margin as is.
environmental_ratio_from_absorption
Section titled “environmental_ratio_from_absorption”environmental_ratio_from_absorption( absorption_area: float | np.floating[Any] | np.integer[Any], measurement_surface_m2: float, directivity_index: float | np.floating[Any] | np.integer[Any] = ...,) -> float
environmental_ratio_from_absorption( absorption_area: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], measurement_surface_m2: float, directivity_index: NumericArrayLike = ...,) -> NDArray[np.float64]
environmental_ratio_from_absorption( absorption_area: float | np.floating[Any] | np.integer[Any], measurement_surface_m2: float, directivity_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],) -> NDArray[np.float64]
environmental_ratio_from_absorption( absorption_area: NumericArrayLike, measurement_surface_m2: float, directivity_index: NumericArrayLike = ...,) -> float | NDArray[np.float64]The ratio from the equivalent sound absorption area.
ISO 11204:2010 Equation (A.6). It is the same quantity
environmental_ratio_from_k2 returns, reached without going through
: under the ISO 3744 definition
the two are identically equal, which is
why ISO 11204 A.1.2 says the two routes rest on the same assumptions.
Parameters
| Name | Description |
|---|---|
absorption_area |
Equivalent sound absorption area of the test room, in square metres, strictly positive. |
measurement_surface_m2 |
Area of the reference measurement surface, in square metres, strictly positive. |
directivity_index |
in decibels (default 0). |
Returns: The ratio ; a float when absorption_area and directivity_index are both numbers; an array of their broadcast shape when one is a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | If either area is not strictly positive. |
| TypeError | if measurement_surface_m2 is not a single number, or absorption_area or directivity_index holds a text or a value that is not a real number. |
environmental_ratio_from_k2
Section titled “environmental_ratio_from_k2”environmental_ratio_from_k2( environmental_correction: float | np.floating[Any] | np.integer[Any], directivity_index: float | np.floating[Any] | np.integer[Any] = ...,) -> float
environmental_ratio_from_k2( environmental_correction: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], directivity_index: NumericArrayLike = ...,) -> NDArray[np.float64]
environmental_ratio_from_k2( environmental_correction: float | np.floating[Any] | np.integer[Any], directivity_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],) -> NDArray[np.float64]
environmental_ratio_from_k2( environmental_correction: NumericArrayLike, directivity_index: NumericArrayLike = ...,) -> float | NDArray[np.float64]The ratio from the environmental correction of the test room.
ISO 11202:2010 Equation (A.4) and ISO 11204:2010 Equation (A.3).
is the average environmental correction of the reference measurement
surface, the quantity environmental_correction
computes for the sound-power methods, and is the
apparent directivity index the work station sees.
With no directivity to speak of the expression collapses to
, so : a work station that sees
the machine no more strongly than the measurement surface does needs the
same correction the surface needed. That holds until the cap bites, at
dB; above it the local correction stays at
MAX_K3 however large the environmental one grows, which is the
piecewise function of local_environmental_correction and not a
limitation here.
Parameters
| Name | Description |
|---|---|
environmental_correction |
in decibels, non-negative. |
directivity_index |
in decibels (default 0, no directivity). |
Returns: The ratio ; a float when environmental_correction and directivity_index are both numbers; an array of their broadcast shape when one is a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if directivity_index or environmental_correction holds a text or a value that is not a real number. |
GRADE_2_MAX_K3
Section titled “GRADE_2_MAX_K3”Constant (float).
GRADE_2_MAX_K3 = 4.0grade_from_local_correction
Section titled “grade_from_local_correction”grade_from_local_correction( local_correction: NumericArrayLike, *, largest_dimension_m: float | None = None,) -> Literal['engineering', 'survey']The accuracy grade a local environmental correction earns.
ISO 11202:2010 A.1.3 puts the boundary at
GRADE_2_MAX_K3: a greatest possible of 4 dB or less
is grade 2 (engineering), and more than that is grade 3 (survey). That is
the boundary applied when largest_dimension_m is not given, and the one
ISO 11204 5.6 applies too.
Method A.2 is stricter. Its Condition (A.6) of A.2.5 adds a margin
to the bound on the approximate directivity index,
because that index is only approximate, and the margin grows with the
largest dimension of the source: 0.5 dB up to 1 m,
1 dB up to 3 m and 1.5 dB beyond. Give largest_dimension_m and the
margin is read from it. Once Equations (A.4) and (A.5) are substituted,
the condition no longer holds and bounds alone,
so grade 2 holds for up to 3.34 dB, 2.82 dB or 2.41 dB.
The worst band decides, since a determination is only as good as its weakest part.
Parameters
| Name | Description |
|---|---|
local_correction |
in decibels; a scalar or one value per band. |
largest_dimension_m |
Largest dimension of the source, in metres, for a determined by method A.2 of ISO 11202 (Default: None, the 4 dB of A.1.3). |
Returns: 'engineering' or 'survey'.
Raises
| Exception | When |
|---|---|
| ValueError | if largest_dimension_m is not strictly positive. |
| TypeError | if local_correction holds a text or a value that is not a real number, or largest_dimension_m is not a single number. |
local_environmental_correction
Section titled “local_environmental_correction”local_environmental_correction( ratio: float | np.floating[Any] | np.integer[Any],) -> float
local_environmental_correction( ratio: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],) -> NDArray[np.float64]
local_environmental_correction( ratio: NumericArrayLike,) -> float | NDArray[np.float64]Local environmental correction from the ratio .
ISO 11202:2010 Equation (A.5) and ISO 11204:2010 Equations (A.2) and (A.5),
the same three lines printed three times; only the route to
differs between them, and that is environmental_ratio_from_k2 and
environmental_ratio_from_absorption.
The cap is the curve’s own value, not a separate rule: dB, so the function is continuous where the 7 dB takes over. The upper branch is a floor for the same reason a correction cannot be negative: the room can only add to the reading.
Parameters
| Name | Description |
|---|---|
ratio |
The dimensionless , strictly positive; a scalar or one value per band. |
Returns: in decibels, of the shape of ratio; a float for a number; an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| ValueError | If any value is not strictly positive. |
| TypeError | if ratio holds a text or a value that is not a real number. |
MAX_K3
Section titled “MAX_K3”Constant (float).
MAX_K3 = 7.0MIN_BACKGROUND_MARGIN_DB
Section titled “MIN_BACKGROUND_MARGIN_DB”Constant (mapping).
MIN_BACKGROUND_MARGIN_DB = {'engineering': 6.0, 'survey': 3.0}NEGLIGIBLE_BACKGROUND_MARGIN_DB
Section titled “NEGLIGIBLE_BACKGROUND_MARGIN_DB”Constant (float).
NEGLIGIBLE_BACKGROUND_MARGIN_DB = 15.0operating_standard_deviation
Section titled “operating_standard_deviation”operating_standard_deviation(levels: NumericArrayLike) -> floatStandard deviation of the operating and mounting conditions.
Equation (C.1), identical in ISO 11201:2010, ISO 11202:2010 and ISO 11204:2010. It is the sample standard deviation of levels measured under the same nominal conditions, and it answers how repeatable the machine is rather than how good the method is: the measurements are made in situ, so the readings need no correction before going in.
The divisor is , as printed. The two worked examples of
ISO 11200:2014 Annex B disagree with each other about that, and
docs/ERRATA.md records it; this library follows the equation.
Parameters
| Name | Description |
|---|---|
levels |
Repeated readings under the same conditions, in decibels; at least two. |
Returns: in decibels.
Raises
| Exception | When |
|---|---|
| ValueError | If fewer than two readings are given. |
| TypeError | if levels holds a text or a value that is not a real number. |
subinterval_level
Section titled “subinterval_level”subinterval_level( levels: NumericArrayLike, durations_s: NumericArrayLike,) -> floatOne level for a cycle made of operating periods of different lengths.
ISO 11201:2010 Equation (8), ISO 11202:2010 Equation (11) and ISO 11204:2010 Equation (10). A machine that idles, cuts and returns spends a different length of time in each state, so the states are energy-averaged weighted by how long each lasts, not by how many there are.
Parameters
| Name | Description |
|---|---|
levels |
The level of each sub-interval, in decibels. |
durations_s |
How long each lasted, in seconds, strictly positive and of the same length. |
Returns: The level of the whole interval, in decibels.
Raises
| Exception | When |
|---|---|
| ValueError | If the two are of different lengths, or a duration is not strictly positive. |
| TypeError | if durations_s or levels holds a text or a value that is not a real number. |
total_standard_deviation
Section titled “total_standard_deviation”total_standard_deviation( reproducibility_db: float, sigma_omc_db: float = 0.0,) -> floatTotal standard deviation of the determination.
ISO 11201:2010 Equation (10), ISO 11202:2010 Equation (13) and ISO 11204:2010 Equation (12). The two components are taken as statistically independent, which is what lets them add in quadrature: one is a property of the method and the other of the machine.
Parameters
| Name | Description |
|---|---|
reproducibility_db |
of the method, in decibels. |
sigma_omc_db |
of the machine, in decibels (default 0, a source whose emission does not wander). |
Returns: in decibels.
Raises
| Exception | When |
|---|---|
| ValueError | If either component is negative. |
| TypeError | if reproducibility_db or sigma_omc_db is not a single number. |
WorkstationBackgroundCorrection
Section titled “WorkstationBackgroundCorrection”WorkstationBackgroundCorrection( background_margin_db: float | NDArray[np.float64], *, grade: Literal['engineering', 'survey'] = 'engineering',)The background-noise correction of the ISO 11200 group.
Above NEGLIGIBLE_BACKGROUND_MARGIN_DB the correction is taken as
zero, and below the grade’s entry in MIN_BACKGROUND_MARGIN_DB it
is held at the value it has there. The correction and whether it was held
are read from the margin and the grade, so they are not fields: a record
cannot be built to hold a correction its margin does not give.
Attributes
| Name | Description |
|---|---|
background_margin_db |
, the reading with the machine running less the reading with it stopped, in decibels; a number, or one value per band. |
grade |
'engineering' (grade 2, 6 dB) or 'survey' (grade 3, 3 dB), which sets how far down a determination may be claimed. |
WorkstationBackgroundCorrection.correction
Section titled “WorkstationBackgroundCorrection.correction”property
, in decibels: a number, or one value per band.
A float when background_margin_db is a number, and an array
when it is a sequence or an array, a zero-dimensional one included.
WorkstationBackgroundCorrection.upper_bound
Section titled “WorkstationBackgroundCorrection.upper_bound”property
Whether the correction was held anywhere, which makes the level an upper bound.
A held correction does not fail the measurement; it makes the level an upper bound, which the caller must carry into what it publishes.