metrology.free_field_corrections

Corrections that bring a sound level meter to its free-field response (IEC 62585:2012).

A periodic test of a sound level meter by IEC 61672-3 drives its microphone with a sound calibrator, a comparison coupler or an electrostatic actuator, none of which is the plane progressive wave the meter is specified for. The test needs, at each frequency, the correction that turns what the meter indicates on that source into what it would indicate in a free field of the same sound pressure level, and the manufacturer has to state it. IEC 62585 gives the methods for finding those corrections and the uncertainty they may carry.

The adjustment value, Annex A. The manufacturer adjusts the meter’s sensitivity to minimise the averaged deviation of its free-field response from the incident level over the whole frequency range, then applies the recommended calibrator and reads $L_4$. The adjustment value quoted in the manual is $\Delta L=L_1-L_4$, $L_1$ being the level stated for the calibrator. adjustment_value makes the fit and returns an AdjustmentValue.

The corrections, Annexes D, E and F. Each compares the meter with a laboratory standard microphone of type LS2P, in a free field and on the source, and adds the free-field correction of that microphone, which comes from IEC/TS 61094-7 and is an input here:

for a multi-frequency sound calibrator (sound_calibrator_correction), Formula (E.6) for a comparison coupler (comparison_coupler_correction), and Formula (F.13), normalised to the calibration check frequency, for an electrostatic actuator (electrostatic_actuator_correction). All three return a FreeFieldCorrection, which averages the determinations of the combinations clause 7 asks for and keeps the range of the corrections over the microphones, the quantity clauses 12 to 14 judge.

The uncertainty, Annex I and clauses 9 to 14. correction_uncertainty_budget builds the budget of Table I.1 on combine_uncertainty: its 15 components, each divided by the divisor its distribution sets, and the effective degrees of freedom by Welch-Satterthwaite, which choose the coverage factor for a level of confidence of 95 %. verify_correction_uncertainty judges the expanded uncertainty at each frequency against the maximum permitted by the clause the correction belongs to, maximum_expanded_uncertainty, and for clauses 12 to 14 the range of the corrections over the microphones against the same maximum.

The exact frequencies, Annex H. The corrections are reported at exact base-ten frequencies, exact_frequencies.

The fit of Annex A. The text asks for the sensitivity that minimises “the averaged deviation” of the free-field response, with the tolerance limits of IEC 61672-1, which vary with frequency, “taken into account”, and prints no formula. adjustment_value takes the least-squares reading: the sensitivity adjustment $s$ minimises ${\sum }_i{w}_i(d_i+s{)}^2$, $d_i$ the deviation at frequency $i$ and $w_i=1/t_i^2$ for a tolerance $t_i$, so a frequency with a tight tolerance pulls the fit harder than one with a loose one, and a frequency without a tolerance ($t_i=\infty$) does not pull it at all. Without tolerances every frequency weighs the same and $s$ is minus the mean deviation.

The labels of Annex E. Figure E.1, the list of symbols under (E.6) and the descriptors a3 and a4 of Table I.1 all define $L_{ind3a}$ as the reading of the reference microphone in the coupler and $L_{ind3b}$ as that of the meter, with $L_{p,P1}$ at the reference and $L_{p,P2}$ at the meter. Equations (E.4) to (E.6) are written the other way round, as (D.5) to (D.7) are for a calibrator, and with the figure’s definitions they do not follow from (E.1) to (E.3B): they come out $2(\Delta L_{\mathrm{P},\mathrm{SLM}}-\Delta L_{\mathrm{P},\mathrm{RM}})$ away from the correction. comparison_coupler_correction names its inputs by what each reading is of, so neither labelling reaches it, and the defect is in docs/ERRATA.md.

The coverage factor of Table I.2. The budget at 1 kHz reproduces the printed combined standard uncertainty, 0,0590 dB, and effective degrees of freedom, 29,98, but prints $k=2,11$, the Student factor for about 17 degrees of freedom. For 29,98 it is 2,042, and the expanded uncertainty $2,042\times 0,05903=0,121$ dB rather than the 0,124 dB the table prints to its guard digit. The budget here gives 2,042, and the defect is in docs/ERRATA.md.

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

adjustment_value(
    frequencies_hz: ArrayLike,
    free_field_indicated_level_db: ArrayLike,
    calibrator_reading_db: float,
    *,
    calibrator_level_db: float,
    incident_level_db: ArrayLike | None = None,
    tolerance_db: ArrayLike | None = None,
    pressure_indicated_level_db: ArrayLike | None = None,
    check_frequency_hz: float = 1000.0,
) -> AdjustmentValue

The adjustment value at the calibration check frequency (IEC 62585:2012, Annex A).

The free-field response of the meter is measured “with where possible a measured level equal to the stated level for the recommended sound calibrator”, the sensitivity is adjusted “to minimise the averaged deviation” of the indication from the incident level over the frequency range, and the adjusted meter is then exposed to the calibrator:

with $d_i$ the indication less the incident level at each frequency, $w_i=1/t_i^2$ for a tolerance $t_i$ (or equal weights), and $L_4^{\prime }$ the indication on the calibrator at the sensitivity the free-field readings were taken at. The least-squares weighting is this module’s reading of a text that prints no formula (see the module notes). Where the achievable free-field level differs from $L_1$, incident_level_db carries it, which is the allowance the text asks for.

Parameters

Returns: The AdjustmentValue.

Raises

AdjustmentValue(
    frequencies_hz: NDArray[np.float64],
    free_field_deviation_db: NDArray[np.float64],
    calibrator_level_db: float,
    calibrator_reading_db: float,
    check_frequency_hz: float = 1000.0,
    tolerance_db: NDArray[np.float64] | None = None,
    pressure_deviation_db: NDArray[np.float64] | None = None,
)

The adjustment value at the calibration check frequency (IEC 62585:2012, Annex A).

The free-field response of the meter before its sensitivity is adjusted, the tolerances the fit weighs it with, and what the meter indicates on its sound calibrator at that same sensitivity. The fit and everything that follows from it are derived from those, so a result cannot state an adjustment its own readings do not give. Figure A.1 names the levels at the calibration check frequency $f_{\mathrm{R}}$: $L_1$ the level stated for the calibrator, $L_2$ the indication in a free field at that level, $L_3$ the indication in a pressure field at that level, $L_4$ the indication on the calibrator, all after the adjustment. The manual states $\Delta L=L_1-L_4$ as a fixed number, without an uncertainty (clause 8).

Attributes

property

The deviation of the free-field response after the adjustment, $d+s$, in dB: curve (2) less curve (1) of Figure A.1.

property

$\Delta L=L_1-L_4$, in dB: the value the manual states, added to the indication on the calibrator to obtain its stated level.

property

$L_4=L_4^{\prime }+s$, what the adjusted meter indicates on the calibrator, in dB.

property

$L_2-L_1$, in dB: the deliberate “offset” NOTE 1 of clause 8 allows at the calibration check frequency, which the fit over the whole range leaves in the free-field response there.

property

$L_2$, the indication in a free field at $L_1$ and the calibration check frequency, after the adjustment, in dB.

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

Plot the free-field deviation before and after the adjustment, with the tolerances it was weighed against.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

property

$L_3$, the indication in a pressure field at $L_1$ and the calibration check frequency, after the adjustment, in dB; None without the pressure response. $L_3-L_4$ is what the loading of the calibrator by the microphone makes of it (NOTE to Figure A.1).

property

The pressure-to-free-field correction of the meter at each frequency, in dB: the free-field level (1) less the indication in the pressure field (3), after the adjustment. None without the pressure response.

property

$s=-{\sum }_i{w}_i{d}_i$, the change of sensitivity the fit makes, in dB: added to every indication.

property

The weight of each frequency in the fit, $1/t_i^2$ normalised to sum to one; equal without tolerances.

comparison_coupler_correction(
    frequencies_hz: ArrayLike,
    slm_free_field_level_db: ArrayLike,
    reference_free_field_level_db: ArrayLike,
    slm_coupler_level_db: ArrayLike,
    reference_coupler_level_db: ArrayLike,
    *,
    reference_free_field_correction_db: ArrayLike,
    free_field_level_difference_db: ArrayLike = 0.0,
    coupler_level_difference_db: ArrayLike = 0.0,
    microphones: Sequence[Hashable] | None = None,
) -> FreeFieldCorrection

Free-field corrections for use with a comparison coupler (IEC 62585:2012, Annex E, Formula (E.6)).

with the symbols of Figure E.1: the meter in a free progressive field (measurement 1), a type LS2P reference microphone in its place (2), and both face to face in the two openings of the coupler (3), the reference reading $L_{ind3a}$ at $L_{p,P1}$ and the meter $L_{ind3b}$ at $L_{p,P2}$. Formula (E.6) as printed exchanges the two readings in the coupler (see the module notes); the inputs here are named by what each reading is of, so the result is the meter’s free-field response relative to its response in the coupler either way.

Each reading may be one value per frequency or a matrix of one row per determination; E.2 step 5 asks for three microphones at least, and the correction is their mean.

Parameters

Returns: The FreeFieldCorrection.

Raises

correction_uncertainty_budget(
    values_db: Mapping[str, float],
    *,
    repeatability_dof: float,
    frequency_hz: float,
    correction_db: float = 0.0,
    static_pressure_kpa: float | None = None,
    additional_components: Sequence[Quantity] = (),
    coverage: float = 0.95,
) -> CorrectionUncertaintyBudget

The uncertainty budget of a correction with the 15 components of Table I.1 (IEC 62585:2012, Annex I).

Each component is given as Table I.2 prints it in its “Value” column: the half-width of a rectangular distribution for most, the expanded uncertainty ($k=2$) from IEC/TS 61094-7 for the free-field correction of the reference microphone (a7), and the standard uncertainty from repeated measurements for the repeatability (a15). The divisors of Table I.1, $\sqrt{3}$, 2 and 1, turn them into standard uncertainties; the combination is combine_uncertainty on Formula (E.6), every component a correction with a sensitivity of $\pm 1$; the effective degrees of freedom are Welch-Satterthwaite’s, with only the repeatability finite; and the coverage factor is the Student factor for them at a level of confidence of 95 % (clause 5).

Table I.2 at 1 kHz gives $u_{\mathrm{c}}=0,0590$ dB and ${\nu }_{\mathrm{eff}}=29,98$, so $k=2,04$ and $U=0,12$ dB (the table prints $k=2,11$, an erratum; see the module notes); Table I.3 at 8 kHz gives $u_{\mathrm{c}}=0,140$ dB, $k=2,00$ and $U=0,28$ dB.

Table I.1 is written for the comparison coupler of Annex E. The budget of a calibrator (Annex D) has the same 15 components with the readings on the calibrator in place of those in the coupler; one of an actuator (Annex F) adds its own, which additional_components carries.

Parameters

Returns: The CorrectionUncertaintyBudget.

Raises

CorrectionUncertaintyBudget(
    frequency_hz: float,
    descriptors: tuple[str, ...],
    symbols: tuple[str, ...],
    values_db: NDArray[np.float64],
    divisors: NDArray[np.float64],
    dofs: NDArray[np.float64],
    uncertainty: UncertaintyResult,
    coverage: float = 0.95,
)

The uncertainty budget of a correction at one frequency (IEC 62585:2012, Annex I, Tables I.1 to I.3).

One entry per component, in the order of Table I.1 and then any component the laboratory adds: the value the budget states, the divisor that turns it into a standard uncertainty $u_i$, and its degrees of freedom. The combination is the law of propagation of the GUM, with every component entering Formula (E.6) with a sensitivity of $\pm 1$, and the coverage factor the Student factor for the Welch-Satterthwaite effective degrees of freedom at the stated level of confidence.

Attributes

property

$u(C_{\mathrm{FF},\mathrm{SLM}})$, the combined standard uncertainty, in dB.

property

The correction the budget is for, in dB (0 when not given).

property

$k$, the Student factor for the effective degrees of freedom at coverage.

property

The Welch-Satterthwaite effective degrees of freedom, $u_{\mathrm{c}}^4/{\sum }_i{u}_i^4/{\nu }_i$.

property

$U=k{u}_{\mathrm{c}}$, in dB.

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

Plot the standard uncertainty of each component, with $u_{\mathrm{c}}$, $k$ and $U$.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

property

$u_i$, each value over its divisor, in dB.

CorrectionUncertaintyVerification(
    clause: int,
    frequencies_hz: NDArray[np.float64],
    expanded_uncertainty_db: NDArray[np.float64],
    correction_db: NDArray[np.float64] | None = None,
    coverage_factor: NDArray[np.float64] | None = None,
    correction_range_db: NDArray[np.float64] | None = None,
)

The expanded uncertainties of a set of corrections against the maxima of their clause (IEC 62585:2012, clauses 5 and 9 to 14).

Clause 5: “If the actual expanded uncertainty of measurement exceeds any of the maximum permitted values, the measurement shall not be used to evaluate the corrections provided in the instruction manual.” Clauses 12 to 14 add a second requirement on the microphone: when the range of the corrections measured with three microphones exceeds the maximum permitted expanded uncertainty at a frequency, the microphone is unsuitable for the source unless more samples show otherwise. Both are “shall not exceed”, so a value equal to its maximum passes, and so does one that lands on it through floating-point arithmetic: the comparison is the one verify_conformance makes for the IEC TC 29 instrument standards, which forgives an excess of one part in $10^9$. The maximum is derived from the clause and the frequencies, maximum_uncertainty_db, so a verdict cannot be judged against a maximum its clause does not give.

Attributes

property

The frequencies where either requirement fails, in Hz.

property

The maximum less the expanded uncertainty at each frequency, in dB: negative where it fails.

property

The maximum permitted at each frequency by the clause, in dB, maximum_expanded_uncertainty.

property

Whether every expanded uncertainty, and every range when given, is within the maximum of the clause.

True says the measurement may be used for the corrections in the manual and, for clauses 12 to 14 with a range, that the microphone is suitable for the source. It says nothing of whether the corrections conform to IEC 61672-1, which clause 15 p) asks separately.

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

Plot the expanded uncertainty and the range against the maximum of the clause.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

property

Whether the range of the corrections is within the maximum, frequency by frequency; None when no range was given.

CorrectionUncertaintyVerification.report(
    path: str,
    *,
    metadata: ReportMetadata | None = None,
    engine: str = 'reportlab',
    verbose: bool = False,
    language: str = 'en',
) -> str

Render the documentation of clause 15 n) and o) to a PDF.

One page: the standard-basis line, an optional metadata header, the table of the corrections with their expanded uncertainty, coverage factor, maximum and verdict at each frequency beside the plot, and the boxed statement of whether the uncertainties are within the maximum permitted values.

Parameters

Returns: The written path as a str.

Raises

property

What the clause corrects for, in the words of its title.

property

Whether the expanded uncertainty is within the maximum, frequency by frequency.

electrostatic_actuator_correction(
    frequencies_hz: ArrayLike,
    slm_free_field_level_db: ArrayLike,
    reference_free_field_level_db: ArrayLike,
    slm_actuator_level_db: ArrayLike,
    *,
    reference_sensitivity_level_db: ArrayLike,
    reference_channel_gain_db: ArrayLike = 0.0,
    actuator_level_db: ArrayLike = 0.0,
    free_field_level_difference_db: ArrayLike = 0.0,
    check_frequency_hz: float = 1000.0,
    microphones: Sequence[Hashable] | None = None,
) -> FreeFieldCorrection

Free-field corrections, normalised to the calibration check frequency, for use with an electrostatic actuator (IEC 62585:2012, Annex F, Formula (F.13)).

every term $X_{\mathrm{N}}=X(f)-X(f_0)$ normalised to the calibration check frequency $f_0$ (Formulas (F.5) to (F.12)). Three measurements (Figure F.1): the meter in a free progressive field (1), a type LS2P reference microphone of known free-field sensitivity in its place (2), and the actuator on the meter (3). An actuator is not an absolute source (NOTE 4 to 3.4), so the correction is relative to $f_0$, where it is zero, and the absolute response there comes from a sound calibrator (NOTE 2 of F.2).

Each reading may be one value per frequency or a matrix of one row per determination; F.2 step 5 averages the combinations of microphone and actuator clause 7 asks for.

Parameters

Returns: The FreeFieldCorrection, zero at $f_0$.

Raises

exact_frequencies(
    lowest_hz: float,
    highest_hz: float,
    *,
    fraction: int = 12,
) -> NDArray[np.float64]

The exact base-ten frequencies between two limits (IEC 62585:2012, Annex H, Formula (H.1)).

for every integer $x$, with $f_{\mathrm{r}}=1000$ Hz and the step-width designator $b$. Annex H gives it for $b=12$, one-twelfth-octave steps, whose decade from 1 kHz to 10 kHz Table H.1 prints to seven significant digits; they are the band edges of one-twelfth-octave filters, so 1 kHz and every one-third-octave midband frequency are among them. Clause 10 and Annexes B and C (B.2, C.2) require the measurements to be made and reported at these exact frequencies rather than at the nominal ones. $b=1$ gives the exact octave midband frequencies clause 10 measures a microphone at, and $b=3$ the one-third-octave ones.

Parameters

Returns: Every exact frequency from lowest_hz to highest_hz inclusive, in Hz, increasing and read-only. It may be empty when the range is narrower than a step.

Raises

FreeFieldCorrection(
    frequencies_hz: NDArray[np.float64],
    corrections_db: NDArray[np.float64],
    reference_correction_db: NDArray[np.float64],
    source: str,
    check_frequency_hz: float | None = None,
    microphones: tuple[Hashable, ...] | None = None,
)

The corrections that bring a meter on a source to its free-field response (IEC 62585:2012, Formulas (D.7), (E.6) and (F.13)).

One row of corrections_db per determination, one combination of microphone and source, and one column per frequency. The correction the manual states is their mean at each frequency (D.2 step 6, E.2 step 5, F.2 step 5). Clauses 12 to 14 judge “the range of correction values at each frequency measured using a sample of three microphones” against the maximum permitted expanded uncertainty, range_db: over the microphones, not over every determination, so that nine determinations of three microphones on three calibrators (D.2 step 6) are not judged on the spread between the calibrators. microphones says which determinations share a microphone.

Attributes

property

The clause whose maximum uncertainty the correction is judged against: 12, 13 or 14.

property

The mean correction over the determinations at each frequency, in dB: the value the manual states.

property

The number of determinations averaged.

property

The formula applied: "D.7", "E.6" or "F.13".

property

The correction of each microphone, the mean over its determinations, in dB, shape (microphones, frequencies).

property

The number of microphones the determinations were made with.

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

Plot the correction against frequency, with every determination and the range between them.

Parameters

Returns: The axes. Requires matplotlib (pip install phonometry[plot]).

property

The range of the corrections over the microphones at each frequency, the largest less the smallest of microphone_corrections_db, in dB: the range clauses 12 to 14 judge. Zero for a single microphone.

Constant (mapping).

maximum_expanded_uncertainty(
    frequencies_hz: ArrayLike,
    *,
    clause: int,
) -> NDArray[np.float64]

The maximum permitted expanded uncertainty of a correction (IEC 62585:2012, clauses 9 to 14).

====== ========================================== ========================= Clause Correction for Maximum, dB ====== ========================================== ========================= 9 reflections from the case, diffraction 0,25 to 4 kHz; 0,35 above 10 the microphone’s non-uniform response 0,25 from 63 Hz to 4 kHz; 0,35 to 8 kHz; 0,45 above 11 windscreens and similar accessories 0,20 to 4 kHz; 0,30 above 12-14 a calibrator, a coupler, an actuator 0,25 to 4 kHz; 0,35 below 10 kHz; 0,50 from 10 kHz ====== ========================================== =========================

“To 4 kHz” includes 4 kHz; 10 kHz is in the band “at and above 10 kHz”. Clauses 10 and 11 exclude the reproducibility component of the samples of microphone or accessory. A frequency within 2 % of a boundary is read as it, so the exact base-ten frequencies of Annex H fall where their nominal ones do.

Parameters

Returns: The maximum at each frequency, in dB, read-only.

Raises

sound_calibrator_correction(
    frequencies_hz: ArrayLike,
    slm_free_field_level_db: ArrayLike,
    reference_free_field_level_db: ArrayLike,
    slm_calibrator_level_db: ArrayLike,
    reference_calibrator_level_db: ArrayLike,
    *,
    reference_free_field_correction_db: ArrayLike,
    free_field_level_difference_db: ArrayLike = 0.0,
    calibrator_level_difference_db: ArrayLike = 0.0,
    microphones: Sequence[Hashable] | None = None,
) -> FreeFieldCorrection

Free-field corrections for use with a multi-frequency sound calibrator (IEC 62585:2012, Annex D, Formula (D.7)).

Four measurements (Figure D.1): the meter in a free progressive field (1), a type LS2P reference microphone in its place in the same field (2), the calibrator on the meter (3) and the same calibrator on the reference (4). Neither the meter nor the calibrator has to be calibrated absolutely: the result is the meter’s free-field response relative to its response on the calibrator, carried over from the reference microphone’s known free-field correction.

Each reading may be one value per frequency or a matrix of one row per determination; D.2 step 6 asks for at least nine, three microphones on three calibrators, and the correction is their mean. microphones names the microphone of each row, so that the range clause 12 judges is taken over the three microphones and not over the calibrators as well.

Parameters

Returns: The FreeFieldCorrection.

Raises

UncertaintyComponentRow(
    symbol: str,
    description: str,
    distribution: str,
    divisor: float,
)

One row of IEC 62585:2012 Table I.1, the likely components of the uncertainty of a correction measured with a comparison coupler (Annex E).

Attributes

verify_correction_uncertainty(
    frequencies_hz: ArrayLike,
    expanded_uncertainty_db: ArrayLike,
    *,
    clause: int,
    correction_db: ArrayLike | None = None,
    coverage_factor: ArrayLike | None = None,
    correction_range_db: ArrayLike | None = None,
) -> CorrectionUncertaintyVerification

Verify the expanded uncertainties of a set of corrections against the maxima of their clause (IEC 62585:2012, clauses 5 and 9 to 14).

The actual expanded uncertainty at each frequency, at a level of confidence of 95 % with the coverage factor stated (clause 5), has not to exceed maximum_expanded_uncertainty of the clause; for a calibrator, a coupler or an actuator (clauses 12 to 14) the range of the corrections over three microphones has not to exceed it either. A FreeFieldCorrection knows its clause, clause, and its range over the microphones, range_db, once it knows which determinations share a microphone; a CorrectionUncertaintyBudget per frequency gives the expanded uncertainty and the coverage factor. A value that reaches its maximum through floating-point arithmetic is on it, not above it.

Parameters

Returns: The CorrectionUncertaintyVerification.

Raises