metrology.random_incidence

Random-incidence and diffuse-field sensitivity of a sound level meter (IEC 61183:1994).

A sound level meter is calibrated for sound arriving from one direction, its reference direction, and most of the sound it is used on arrives from all of them. IEC 61183 gives the two ways of finding what the instrument reads in such a field. The free-field method of clause 4 and Annex A rotates the instrument in an anechoic room, measures what it indicates for each direction of incidence, and weights each reading by the solid angle it stands for; the diffuse-field method of clause 5 and Annex B compares the instrument with a reference instrument in a reverberation room.

The free-field method. The random-incidence sensitivity level is the free-field sensitivity level for the reference direction less the directivity of the instrument, Formulas (1) and (A.6):

where $L_{\mathrm{rd}}$ is what the instrument indicates for a plane wave from the reference direction and $L_{\mathrm{o}}$ the level of that wave without the instrument. The directivity factor $\gamma$ of Formula (2) is $4\pi$ over the integral, across the sphere, of what the instrument indicates relative to $L_{\mathrm{rd}}$; Formula (3) writes the direction as the angle $\varphi$ from the reference direction and the angle $\alpha$ about it:

and in practice the sum of Formula (4) over m angles ${\varphi }_i$ in steps $\Delta \varphi =2\pi /m$ and n planes ${\alpha }_j$ in steps $\Delta \alpha =\pi /n$, each reading weighted by the share of the sphere its element covers, Formula (5). Integrated, Formulas (6) and (7) give

adjustment_factors evaluates them for any angular step that divides the half circle and any number of planes. Two planes at right angles, $\Delta \alpha =\pi /2$, are Formulas (A.1) and (A.2) of Annex A, whose factors for 10° steps Table A.1 prints; four planes at 45°, which NOTE 2 of A.6 asks for when the reference direction is not normal to the diaphragm, halve them.

The directivity factor then follows by one of three routes, each a function here returning a DirectivityFactor:

• directivity_factor, two (or four) planes, Formula (A.3);
• axisymmetric_directivity_factor, one plane for an instrument with rotational symmetry about its reference direction, Formula (A.4);
• equal_area_directivity_factor, the 38 directions of equal-area elements of the note to A.1.8, Formula (A.5), at the directions equal_area_incidence_angles gives.

random_incidence_sensitivity applies Formula (1) band by band and returns a RandomIncidenceSensitivity.

The diffuse-field method. The instrument and a reference instrument are placed in turn at the same positions in a diffuse field, and the difference of what they indicate, Formula (8), is added to the diffuse-field sensitivity level of the reference, known in one of three ways: Formula (9) for a reference calibrated by clause 4, Formula (10) for one calibrated in a free field with its directivity factor known, and Formula (11) for one calibrated in a pressure field with the difference between its diffuse-field and pressure sensitivity levels known. diffuse_field_sensitivity takes any of the three and returns a DiffuseFieldSensitivity. Table B.1 prints both the directivity factor and that difference for a type LS2aP/LS2F laboratory standard microphone, one of the two types Annex B recommends for the reference (the other is LS2bP); IEC61183_TABLE_B1 holds it and supplies them by default.

The two poles of Formula (A.3). Both sums of (A.3) run from 0° to 350°, and the paragraph under it notes that the readings at 0° and 180° are the same in the two planes and “have only to be taken into account once”. They have to be measured once; they are counted in both sums. Each plane’s pole factor of Formula (A.2) covers half of the polar cap, so the 72 factors of Table A.1 sum to exactly one only with the poles in both sums, and an omnidirectional instrument then has $\gamma =1$. Counted once, the factors sum to 0,998097: the sum of (A.3) loses the second plane’s two pole terms, and $10\lg \gamma$ comes out high by

which is 0,008 dB (0,19 % on $\gamma$) for an omnidirectional instrument and grows with the directivity: about 0,02 dB at $10\lg \gamma =7$ dB when little arrives from behind. This module does not make that error.

The angles of the equal-area elements. The note to A.1.8 prints the 38 directions to 0,1° without saying how they were placed. Each is the direction that halves its element’s area in polar angle: the cap about each pole takes 1/38 of the sphere, and the nine rings between them 4/38 each, split into four elements by the two planes. That construction reproduces the note’s list of 20 angles to the 0,1° it is printed to, except two: 77,9° and its mirror 282,1° break the list’s own symmetry about 90° (77,9° + 102,2° is 180,1°, where all the other pairs sum to 180,0°), the construction gives 77,85° and 282,15°, and the two are recorded 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_factors(
    step_deg: float,
    *,
    planes: int = 2,
) -> NDArray[np.float64]

Adjustment factors $K(\varphi )$ for one plane of measurements (IEC 61183:1994, Formulas (6), (7), (A.1) and (A.2)).

The share of the sphere each reading stands for, at the angles $\varphi =0,\Delta \varphi ,\dots ,360°-\Delta \varphi$ from the reference direction, for measurements in planes planes through the reference direction at equal angles $\Delta \alpha =180°/n$ apart:

the first being Formula (6) with the difference of cosines written as a product. With the two planes of Annex A this is $(1/8)[\cos (\varphi -\Delta \varphi /2)-\cos (\varphi +\Delta \varphi /2)]$ and $(1/4)[1-\cos (\Delta \varphi /2)]$, Formulas (A.1) and (A.2), which Table A.1 prints for 10° steps; with the four planes of NOTE 2 of A.6 every factor is halved, and with one plane, the rotationally symmetric instrument of Formula (A.4), doubled.

The factors of all the planes together sum to one: the pole factor of each of the $n$ planes covers $1/n$ of the polar cap (half of it in the two planes of Annex A), so the pole readings enter every plane’s sum (see the module notes).

Parameters

Returns: The 360 / step_deg factors, read-only, the first at 0°.

Raises

Warns

axisymmetric_directivity_factor(
    levels_db: ArrayLike,
    *,
    reference_level_db: float | None = None,
) -> DirectivityFactor

Directivity factor of an instrument with rotational symmetry, from one plane (IEC 61183:1994, Formula (A.4)).

NOTE 1 of A.4.7: when the instrument is rotationally symmetric about its reference direction, the X-Z plane repeats the X-Y plane and one rotation (A.4.5) is enough. This is Formula (A.3) with the two planes equal, and the factor 2 makes the weights those of adjustment_factors with one plane.

Parameters

Returns: The DirectivityFactor.

Raises

Warns

diffuse_field_sensitivity(
    frequencies_hz: ArrayLike,
    indicated_level_db: ArrayLike,
    reference_indicated_level_db: ArrayLike,
    *,
    reference_random_incidence_level_db: ArrayLike | None = None,
    reference_free_field_level_db: ArrayLike | None = None,
    reference_directivity_index_db: ArrayLike | None = None,
    reference_pressure_level_db: ArrayLike | None = None,
    reference_diffuse_pressure_difference_db: ArrayLike | None = None,
) -> DiffuseFieldSensitivity

Diffuse-field sensitivity level by comparison with a reference sound level meter (IEC 61183:1994, Formulas (8) to (11)).

and then, by the calibration the reference instrument has,

Exactly one of reference_random_incidence_level_db, reference_free_field_level_db and reference_pressure_level_db selects the formula. For Formulas (10) and (11), the directivity factor and the diffuse-to-pressure difference of the reference default to Table B.1, the type LS2aP/LS2F microphone, one of the two types Annex B recommends for the reference, at each preferred frequency from 25 Hz to 20 kHz.

Parameters

Returns: The DiffuseFieldSensitivity.

Raises

DiffuseFieldSensitivity(
    frequencies_hz: NDArray[np.float64],
    indicated_level_db: NDArray[np.float64],
    reference_indicated_level_db: NDArray[np.float64],
    reference_sensitivity_level_db: NDArray[np.float64],
    reference_correction_db: NDArray[np.float64],
    route: str,
)

The diffuse-field sensitivity level of a sound level meter, by comparison with a reference instrument (IEC 61183:1994, clause 5).

where the diffuse-field sensitivity level of the reference, $G_{\mathrm{D},\mathrm{ref}}$, is its calibrated sensitivity level plus a correction that depends on how it was calibrated: none for a random-incidence calibration, Formula (9); $-10\lg {\gamma }_{\mathrm{ref}}$ for a free-field calibration, Formula (10); $+{\Delta }_{\mathrm{DP}}$ for a pressure calibration, Formula (11).

Attributes

property

$G_{\mathrm{D}}$, the diffuse-field sensitivity level of the instrument under test, in dB (Formulas (9) to (11)).

property

$\Delta G_{\mathrm{D}}=L_{\mathrm{D}}-L_{\mathrm{D},\mathrm{ref}}$, in dB (Formula (8)).

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

Plot $G_{\mathrm{D}}$, $\Delta G_{\mathrm{D}}$ and $G_{\mathrm{D},\mathrm{ref}}$ against frequency.

Parameters

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

property

$G_{\mathrm{D},\mathrm{ref}}$, the diffuse-field sensitivity level of the reference instrument, in dB.

directivity_factor(
    levels_db: ArrayLike,
    *,
    reference_level_db: float | None = None,
) -> DirectivityFactor

Directivity factor from readings in two or more planes (IEC 61183:1994, Formula (A.3)).

for the 10° steps and two planes of A.4.5 and A.4.6, with the factors of Table A.1. The angular step is read off the number of readings in a plane, and the factors are adjustment_factors for that step and that number of planes: four planes, as NOTE 2 of A.6 asks for when the reference direction is not normal to the diaphragm, take half the factors of Table A.1.

The readings at 0° and 180° are the same in every plane, and A.4.7 says they have only to be taken into account once. They are measured once and enter every plane’s sum here, which is what makes the factors sum to one and an omnidirectional instrument read $\gamma =1$; counted once, $10\lg \gamma$ would come out 0,008 dB high for an omnidirectional instrument and more for a directional one (see the module notes).

Parameters

Returns: The DirectivityFactor.

Raises

Warns

DirectivityFactor(
    incidence_angles_deg: NDArray[np.float64],
    plane_angles_deg: NDArray[np.float64],
    levels_db: NDArray[np.float64],
    weights: NDArray[np.float64],
    reference_level_db: float,
    gamma: float,
    largest_element_fraction: float,
    formula: str,
)

The directivity factor of a sound level meter at one frequency (IEC 61183:1994, Formulas (A.3) to (A.5)).

over every reading, each weighted by the share of the sphere it stands for. The readings are held flat, one entry per reading, with the plane each was taken in.

Attributes

property

$10\lg \gamma$, in dB: what Formula (1) subtracts from $G_{\mathrm{F}}$, and what Table B.1 tabulates.

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

Plot the directional response or the weight of each reading.

Parameters

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

Raises

property

$L(\varphi )-L_{\mathrm{rd}}$ of each reading, in dB.

equal_area_directivity_factor(
    horizontal_levels_db: ArrayLike,
    vertical_levels_db: ArrayLike,
    *,
    reference_level_db: float | None = None,
) -> DirectivityFactor

Directivity factor from 38 equal-area elements (IEC 61183:1994, Formula (A.5)).

NOTE 2 of A.4.7: with the directions of the note to A.1.8, every element is 1/38 of the sphere (2,6 %) and every reading weighs the same.

Parameters

Returns: The DirectivityFactor.

Raises

equal_area_incidence_angles() -> tuple[NDArray[np.float64], NDArray[np.float64]]

The 38 directions of equal-area elements (IEC 61183:1994, note to A.1.8).

The sphere is divided into 38 elements of equal area: a cap about each pole, and nine rings of four elements between them, cut by the horizontal (X-Y) and vertical (X-Z) planes. Each direction is the one that halves its element’s area in polar angle, so the k-th ring from the reference direction is at

which is 32,6°, 50,8°, 65,1°, 77,8° and 90° up to grazing incidence. The note prints the same angles to 0,1°, except 77,9° and its mirror 282,1°, which are errata (see the module notes).

Returns: (horizontal, vertical) in degrees, read-only. The horizontal plane holds both poles and runs 0°, ${\varphi }_1,\dots ,{\varphi }_9$, 180°, $360°-{\varphi }_9,\dots ,360°-{\varphi }_1$: 20 directions in the order the note prints them. The vertical plane holds the same without the poles: 18.

Constant (mapping).

largest_element_fraction(step_deg: float, *, planes: int = 2) -> float

The largest element a set of incidence angles divides the sphere into, as a fraction of its surface (IEC 61183:1994, A.1.6 and A.1.7).

The planes cut each ring between the poles into $2n$ elements of $K(\varphi )$ each, the largest at the direction nearest 90°, and leave the cap about each pole whole, ${\sin }^2(\Delta \varphi /4)$ of the sphere. A.1.6 asks for the largest to be no more than 3 %; with the two planes of Annex A and 10° steps it is the element at 90°, 2,18 %, the “approximately 2,2 %” of A.1.7. One plane measured under rotational symmetry stands for the same two planes and is judged on their division.

Parameters

Returns: The fraction, between 0 and 1.

Raises

random_incidence_sensitivity(
    frequencies_hz: ArrayLike,
    free_field_level_db: ArrayLike,
    directivity_index_db: ArrayLike,
) -> RandomIncidenceSensitivity

Random-incidence sensitivity level from the free-field sensitivity level and the directivity factor (IEC 61183:1994, Formulas (1) and (A.6)).

at each frequency. $G_{\mathrm{F}}=L_{\mathrm{rd}}-L_{\mathrm{o}}$ depends on the individual instrument and $\gamma$ only on its dimensions and geometry, so one model’s directivity factors serve every instrument of that model (4.2).

Parameters

Returns: The RandomIncidenceSensitivity.

Raises

RandomIncidenceSensitivity(
    frequencies_hz: NDArray[np.float64],
    free_field_level_db: NDArray[np.float64],
    directivity_index_db: NDArray[np.float64],
    random_incidence_level_db: NDArray[np.float64],
)

The random-incidence sensitivity level of a sound level meter, band by band (IEC 61183:1994, Formulas (1) and (A.6)).

$G_{\mathrm{RI}}=G_{\mathrm{F}}-10\lg \gamma$ at each frequency.

Attributes

property

$G_{\mathrm{RI}}-G_{\mathrm{F}}=-10\lg \gamma$ at each frequency, in dB: what the instrument reads in a random-incidence field relative to a plane wave from its reference direction.

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

Plot the sensitivity levels or the correction against frequency.

Parameters

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

Raises

ReferenceMicrophoneRow(
    directivity_index_db: float,
    diffuse_pressure_difference_db: float,
)

One row of IEC 61183:1994 Table B.1.

The characteristics of a type LS2aP/LS2F laboratory standard microphone (IEC 61094-1), one of the two types Annex B recommends for the reference of the diffuse-field method, at one preferred frequency. The table rounds both to 0,05 dB, determined with pure tones, with a measurement uncertainty of ±0,03 dB (B.5).

Attributes

The angular step divides the sphere into elements that are too large.

Emitted when the largest element of the sphere a set of incidence angles divides it into is more than 3 % of its surface, the limit A.1.6 of IEC 61183:1994 sets for a reading to stand for the directions around it.