Skip to content

emission.intensity_compliance

IEC 61043:1993 sound-intensity instrument class verification.

A two-microphone (p-p) intensity chain is graded by its pressure-residual intensity index delta_pI0: feed both measurement channels the same pink noise (or expose both probe microphones to the same pressure) and the true intensity is exactly zero, yet the residual phase mismatch between the channels reports a small false intensity. The difference between the indicated sound pressure level and that residual intensity level, evaluated for an air density of 1.2048 kg/m3, is delta_pI0 (IEC 61043:1993, definition 3.11).

Table 2 of the standard (EN 61043:1994 standard page 14) prescribes the minimum delta_pI0 per one-third-octave band from 50 Hz to 6.3 kHz for a probe, a processor and a complete instrument, in class 1 and class 2, at the nominal microphone separation of 25 mm. The table is transcribed digit for digit below. Its Note 1 gives the separation rule: for any other microphone separation x in millimetres, add dB to every figure, so a wider spacer both earns and demands more low-frequency margin. Note 2 restricts the requirement to the octave-band centre frequencies for processors that only analyse in octave bands.

Two related requirements of the same standard are exposed here as well:

  • Clause 6.1 (frequency range of processors): a class 1 processor covers at least 45 Hz to 7.1 kHz in one-third-octave bands (the 22 tabulated bands from 50 Hz to 6.3 kHz). A class 2 processor covers either that same one-third-octave range or, alternatively, 45 Hz to 5.6 kHz in octave bands (the 7 octave bands from 63 Hz to 4 kHz). A verdict computed over a narrower set of bands attests only the bands supplied, which verify_intensity_class flags as range_limited. Because the octave range is open to class 2 alone, a class 1 verdict reached over octave bands only is flagged too, and a probe (tested in one-third octaves by clause 12.4) cannot use the alternative at all.

    The Spanish translation UNE-EN 61043:1999 states only the octave alternative for class 2, dropping the one-third-octave one; this module follows the EN/IEC text (see docs/ERRATA.md).

  • Clause 8 (instrument assembled from separate components): a class 1 instrument consists of a class 1 processor and a class 1 probe; a class 2 instrument of any other combination of class 1 and class 2 components. See instrument_class_from_components.

The index is also the instrument’s phase-error floor in disguise. In an axially propagating plane progressive wave the true phase difference across the spacer is , so a residual intensity produced by a channel phase mismatch gives (Fahy, Sound Intensity 2nd ed., equation (7.16)); phase_mismatch_from_residual_index and residual_index_from_phase_mismatch convert between the two. Fahy’s worked check in section 6.8 is the anchor: dB means a mismatch of one hundredth of , about 0.26 degrees at 1 kHz over a 25 mm separation.

The measured delta_pI0 this module classifies is a property of the whole probe-spacer-analyser chain and must be determined with the spacer that will be fitted in the field; the library does not measure it. Once classified, the ISO 9614 dynamic capability follows from phonometry.emission.intensity.dynamic_capability_index.

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

instrument_class_from_components(
probe_class: int | np.integer[Any],
processor_class: int | np.integer[Any],
) -> int

Class of an instrument assembled from a separate probe and processor.

IEC 61043:1993 clause 8: when a probe and a processor are supplied separately, a class 1 instrument consists of a class 1 processor and a class 1 probe, while a class 2 instrument consists of any other combination of class 1 and class 2 components (class 1 processor with class 2 probe, class 2 processor with class 1 probe, or both class 2). The rule therefore reduces to the looser of the two component classes.

Parameters

Name Description
probe_class Class of the probe (1 or 2).
processor_class Class of the processor (1 or 2).

Returns: The class of the assembled instrument (1 or 2).

Raises

Exception When
ValueError If either class is not 1 or 2. The non-real-time class 2X of clause 4 is not modelled here.
TypeError if probe_class or processor_class is a flag, a text or an array where a count goes.
IntensityInstrumentComplianceResult(
frequencies: NDArray[np.float64],
residual_index: NDArray[np.float64],
device: Literal['probe', 'processor', 'instrument'],
spacing_m: float,
)

IEC 61043:1993 class verdict of a p-p sound-intensity chain.

What verify_intensity_class returns: the measured spectrum, the device and the separation it was judged at. The two Table 2 masks, the band rows, the classes and the range are read from them, so none of them is a field: a verdict cannot be built, or rewritten with dataclasses.replace, against another minimum or with a class its index does not reach.

Attributes

Name Description
frequencies Nominal band centre frequencies, in Hz.
residual_index Measured delta_pI0 per band, in dB.
device "probe", "processor" or "instrument".
spacing_m Microphone separation the verdict applies to, in metres.

property

The per-band verdicts, read from the spectrum and Table 2.

One {"frequency", "class", "residual_index_db", "limit_class1_db", "limit_class2_db", "margin_class1_db", "margin_class2_db"} per band: a band meets a class when its index is at least that class’s minimum, so a band exactly on the limit passes. A fresh copy at every read.

IntensityInstrumentComplianceResult.binding_margin()

Section titled “IntensityInstrumentComplianceResult.binding_margin()”
IntensityInstrumentComplianceResult.binding_margin(
device_class: int | np.integer[Any] | None = None,
) -> float

Smallest per-band margin to a class, in dB (the binding margin).

Parameters

Name Description
device_class 1 or 2; None (default) uses reference_class.

Raises

Exception When
ValueError If device_class is not 1 or 2.
TypeError if device_class is a flag, a text or an array where a count goes.

IntensityInstrumentComplianceResult.failing_bands()

Section titled “IntensityInstrumentComplianceResult.failing_bands()”
IntensityInstrumentComplianceResult.failing_bands(
device_class: int | np.integer[Any] | None = None,
) -> list[float]

Nominal centre frequencies of the bands that miss a class, in Hz.

Parameters

Name Description
device_class 1 or 2; None (default) uses reference_class.

Raises

Exception When
TypeError if device_class is a flag, a text or an array where a count goes.

IntensityInstrumentComplianceResult.limit_class1

Section titled “IntensityInstrumentComplianceResult.limit_class1”

property

Class 1 minimum delta_pI0 per band, in dB, rescaled to spacing_m.

Returns: Table 2 for device, plus spacing_offset_db.

IntensityInstrumentComplianceResult.limit_class2

Section titled “IntensityInstrumentComplianceResult.limit_class2”

property

Class 2 minimum delta_pI0 per band, in dB, rescaled to spacing_m.

Returns: Table 2 for device, plus spacing_offset_db.

IntensityInstrumentComplianceResult.overall_class

Section titled “IntensityInstrumentComplianceResult.overall_class”

property

The strictest class every band meets (1 or 2), or None.

None when at least one band meets neither. It is the largest per-band class, because a band meeting class 1 meets class 2 as well.

IntensityInstrumentComplianceResult.phase_mismatch_deg()

Section titled “IntensityInstrumentComplianceResult.phase_mismatch_deg()”
IntensityInstrumentComplianceResult.phase_mismatch_deg(
*,
speed_of_sound: float = 343.0,
) -> NDArray[np.float64]

Equivalent channel phase mismatch per band, in degrees.

Converts the measured delta_pI0 spectrum with phase_mismatch_from_residual_index at the result’s own microphone separation, so the verdict can be read as the phase-matching the chain achieves.

Parameters

Name Description
speed_of_sound Speed of sound in m/s (default 343.0).

IntensityInstrumentComplianceResult.plot()

Section titled “IntensityInstrumentComplianceResult.plot()”
IntensityInstrumentComplianceResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the measured delta_pI0 over the Table 2 class masks.

See phonometry._plot.emission.plot_intensity_class. Requires matplotlib (the [plot] extra) and returns the Axes.

Parameters

Name Description
language Label language, "en" (default) or "es".

IntensityInstrumentComplianceResult.range_limited

Section titled “IntensityInstrumentComplianceResult.range_limited”

property

Whether the verified bands fall short of the range of clause 6.1.

True when they cover neither the 22 one-third-octave bands nor, for a class 2 processor or instrument, the 7 octave bands, so the stated class attests only the bands supplied. Clause 6.1 gives the one-third-octave range to class 1 and offers the octave range only to class 2; a probe has no analysis bands of its own and clause 12.4 tests it in one-third octaves, so the alternative is not open to it.

IntensityInstrumentComplianceResult.reference_class()

Section titled “IntensityInstrumentComplianceResult.reference_class()”
IntensityInstrumentComplianceResult.reference_class() -> int

The class whose mask the fiche and the plot read margins against.

The achieved class when the chain complies, else class 2 (the loosest class of the standard, the one it comes closest to meeting).

IntensityInstrumentComplianceResult.report()

Section titled “IntensityInstrumentComplianceResult.report()”
IntensityInstrumentComplianceResult.report(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render an IEC 61043 residual-index verification fiche to a PDF.

Writes a one-page accredited report: the standard-basis line, an optional metadata header block, the per-band table of measured index, Table 2 requirement and margin beside the mask-overlay plot, the boxed class result, an optional verdict row against a supplied required_class and the footer disclaimer.

Parameters

Name Description
path Destination path of the PDF file.
metadata Optional ReportMetadata; None produces a bare fiche (body, result and disclaimer only). A supplied required_class drives the verdict row.
engine Rendering back end; only "reportlab" is supported.
verbose Accepted for a uniform signature; it has no effect on the single-layout intensity-compliance fiche.
language Fiche language: "en" (default) or "es".

Returns: The written path as a str.

Raises

Exception When
ValueError If engine is not "reportlab".
ImportError If reportlab is not installed (the [report] extra), or matplotlib is missing for the embedded figure (the [plot] extra).

IntensityInstrumentComplianceResult.spacing_offset_db

Section titled “IntensityInstrumentComplianceResult.spacing_offset_db”

property

The Table 2 Note 1 term , in dB.

Returns: What the separation adds to the printed 25 mm figures.

phase_mismatch_from_residual_index(
residual_index: float | np.floating[Any] | np.integer[Any],
spacing_m: float,
*,
frequency: float | np.floating[Any] | np.integer[Any],
speed_of_sound: float = ...,
) -> float
phase_mismatch_from_residual_index(
residual_index: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
spacing_m: float,
*,
frequency: NumericArrayLike,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
phase_mismatch_from_residual_index(
residual_index: float | np.floating[Any] | np.integer[Any],
spacing_m: float,
*,
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
speed_of_sound: float = ...,
) -> NDArray[np.float64]
phase_mismatch_from_residual_index(
residual_index: NumericArrayLike,
spacing_m: float,
*,
frequency: NumericArrayLike,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Channel phase mismatch equivalent to a pressure-residual intensity index.

In an axially propagating plane progressive wave the true phase difference between the two sensing points is , and a residual intensity produced by a channel phase mismatch satisfies (Fahy, Sound Intensity 2nd ed., equations (7.4) and (7.16)), so:

The ratio is dimensionless, so is returned in the same angular unit is expressed in; degrees are used here.

Parameters

Name Description
residual_index delta_pI0 in decibels (scalar or array).
frequency Frequency in Hz (scalar or array, broadcast against residual_index).
spacing_m Microphone separation in metres.
speed_of_sound Speed of sound in m/s (default 343.0).

Returns: The equivalent phase mismatch in degrees. A float when residual_index and frequency are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If spacing_m, speed_of_sound or frequency are not positive and finite, or if residual_index is not finite.
TypeError if spacing_m or speed_of_sound is not a single number, or frequency or residual_index holds a text or a value that is not a real number.
residual_index_from_phase_mismatch(
phase_mismatch_deg: float | np.floating[Any] | np.integer[Any],
spacing_m: float,
*,
frequency: float | np.floating[Any] | np.integer[Any],
speed_of_sound: float = ...,
) -> float
residual_index_from_phase_mismatch(
phase_mismatch_deg: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
spacing_m: float,
*,
frequency: NumericArrayLike,
speed_of_sound: float = ...,
) -> NDArray[np.float64]
residual_index_from_phase_mismatch(
phase_mismatch_deg: float | np.floating[Any] | np.integer[Any],
spacing_m: float,
*,
frequency: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
speed_of_sound: float = ...,
) -> NDArray[np.float64]
residual_index_from_phase_mismatch(
phase_mismatch_deg: NumericArrayLike,
spacing_m: float,
*,
frequency: NumericArrayLike,
speed_of_sound: float = ...,
) -> float | NDArray[np.float64]

Pressure-residual intensity index of a given channel phase mismatch.

The inverse of phase_mismatch_from_residual_index:

with and both in degrees (the ratio is dimensionless). Because grows with frequency while a mismatch that is constant in degrees does not, the index rises by 10 dB per decade of frequency: this is why a fixed phase-matching quality yields the falling low-frequency delta_pI0 that IEC 61043 Table 2 grades band by band, and why a wider spacer buys dB of index exactly as Note 1 of that table requires.

Parameters

Name Description
phase_mismatch_deg in degrees (scalar or array, > 0).
frequency Frequency in Hz (scalar or array, broadcast against phase_mismatch_deg).
spacing_m Microphone separation in metres.
speed_of_sound Speed of sound in m/s (default 343.0).

Returns: delta_pI0 in decibels. A float when phase_mismatch_deg and frequency are both numbers, an array when either is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError If phase_mismatch_deg is not positive and finite, or if spacing_m, speed_of_sound or frequency are not positive and finite.
TypeError if spacing_m or speed_of_sound is not a single number, or frequency or phase_mismatch_deg holds a text or a value that is not a real number.
residual_index_limits(
device: Literal['probe', 'processor', 'instrument'] = 'instrument',
*,
spacing_m: float = 0.025,
frequencies: NumericArrayLike | None = None,
) -> ResidualIndexLimits

IEC 61043:1993 Table 2 minimum pressure-residual intensity index.

Returns the class 1 and class 2 minima the standard requires of a device kind, already rescaled to the microphone separation in use with the Note 1 rule (x in millimetres, i.e. for a spacing in metres).

Parameters

Name Description
device "probe", "processor" or "instrument" (the three column groups of Table 2).
spacing_m Microphone separation in metres (default 0.025, the nominal separation the table is printed for).
frequencies Band centre frequencies in Hz to report the limits at, as nominal labels or the exact base-ten centres behind them. None (default) returns all 22 tabulated one-third-octave bands.

Returns: The nominal band centres in Hz and the two minimum delta_pI0 requirements in dB, as a ResidualIndexLimits (frequencies, class_1, class_2).

Raises

Exception When
ValueError If device is unknown, spacing_m is not positive or a frequency is not a tabulated band.
TypeError if spacing_m is not a single number, or device is not a text, or frequencies holds a text or a value that is not a real number.
ResidualIndexLimits(
frequencies: NDArray[np.float64],
class_1: NDArray[np.float64],
class_2: NDArray[np.float64],
)

The IEC 61043 Table 2 minimum pressure-residual intensity index, per class.

What residual_index_limits returns: the bands and the two class minima, named, where a (frequencies, class1, class2) tuple used to be unpacked by position.

Attributes

Name Description
frequencies The nominal band centres, in Hz.
class_1 The class 1 minimum in each band, in dB, rescaled to the microphone separation.
class_2 The class 2 minimum, in dB.
verify_intensity_class(
residual_index: NumericArrayLike,
*,
frequencies: NumericArrayLike,
device: Literal['probe', 'processor', 'instrument'] = 'instrument',
spacing_m: float = 0.025,
) -> IntensityInstrumentComplianceResult

Verify a measured delta_pI0 spectrum against IEC 61043:1993 Table 2.

Each band’s measured pressure-residual intensity index is compared with the class 1 and class 2 minima of Table 2 for the device kind, rescaled to the microphone separation in use (Note 1, ). A band meets a class when its measured index is greater than or equal to that class’s minimum, so the margin is measured - minimum and a band exactly on the limit passes. The overall class is the loosest per-band class, or None when any band meets neither class.

Clause 6.1 fixes the frequency range the class attests: 45 Hz to 7.1 kHz in one-third-octave bands (the 22 tabulated bands, 50 Hz to 6.3 kHz), or, for an octave-band processor, 45 Hz to 5.6 kHz in octave bands (63 Hz to 4 kHz). range_limited is True when the supplied bands cover neither of those sets, in which case the returned class attests the bands actually verified and not the standard’s full frequency range. The one-third-octave range is required for class 1 and available to class 2, while the octave range is offered as a class 2 alternative only, so a verdict computed over the 7 octave bands attests a class 2 result but is still range_limited when it reaches class 1. The octave alternative is not open to a "probe" at all: a probe has no analysis bands of its own and clause 12.4 determines its index at one-third-octave intervals across the whole 50 Hz to 6.3 kHz range.

Parameters

Name Description
residual_index Measured delta_pI0 per band, in decibels.
frequencies Band centre frequencies in Hz, one per entry of residual_index, as nominal Table 2 labels or the exact base-ten centres behind them.
device "probe", "processor" or "instrument".
spacing_m Microphone separation in metres (default 0.025).

Returns: An IntensityInstrumentComplianceResult, which carries the verdict together with the measured spectrum and the two rescaled Table 2 masks, so it exposes .plot() and an accredited .report() fiche.

Raises

Exception When
ValueError If the inputs disagree in length, a frequency is not a tabulated band, a band is repeated, or device/spacing_m are invalid.
TypeError if device is not a text, or frequencies or residual_index holds a text or a value that is not a real number, or spacing_m is not a single number.