emission: sound power in an anechoic room
Every name on this page is published by phonometry.emission: from phonometry import emission, then emission.<name>.
Sound power level of a source in an anechoic or hemi-anechoic room, from sound pressure over an enveloping surface: ISO 3745:2012 (precision, grade 1).
This is the precision sibling of ISO 3744:2010 (engineering) and ISO 3746:2010 (survey), and the path from the surface-averaged pressure to the sound power level is the same one. What sets it apart is the room. In a qualified (hemi-)free field there is no reflected energy to correct for, so the environmental correction disappears altogether; in its place the standard asks for more of everything else. The background correction is evaluated at every microphone position and every band against a frequency-dependent criterion (clause 9.4.2), the microphone array is a fixed 40-position equal-area set tabulated for the sphere (Annex D) and the hemisphere (Annex E), and three meteorological corrections refer the determination to the reference atmosphere (clause 9.5):
The measurement surface is a full sphere in an anechoic room (Eq. 14) or a hemisphere over the reflecting plane of a hemi-anechoic room (Eq. 15), and each tabulated position carries an equal share of it; unequal partial areas are averaged by Eq. 13 instead. The A-weighted total is combined with the ISO 3744 Annex E band corrections (Annex C, Eq. C.1) and the expanded uncertainty (Eq. 24/25) takes its reproducibility standard deviation from Table 3 (anechoic) or Table 2 (hemi-anechoic).
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
meteorological_corrections
Section titled “meteorological_corrections”meteorological_corrections( *, temperature_c: float = 23.0, static_pressure_kpa: float = 101.325, air_absorption_db_per_m: NumericArrayLike | None = None, radius: float = 1.0,) -> MeteorologicalCorrectionMeteorological corrections C1, C2, C3 (ISO 3745:2012 Eq. 14 block).
Using the measured static pressure (kPa) and air temperature (deg C) form:
kPa. This is the / form of C1 (not the characteristic-impedance form), chosen because it needs only the measured and and is consistent with C2. At the reference conditions (23 deg C, 101.325 kPa) exactly while dB. C3 requires the atmospheric attenuation coefficient from ISO 9613-1 (not computed here); without it .
Parameters
| Name | Description |
|---|---|
temperature_c |
Air temperature theta at the test, in degrees C. |
static_pressure_kpa |
Static pressure ps at the test, in kilopascals. |
air_absorption_db_per_m |
a(f) (dB/m), scalar or per band, for C3; None leaves . |
radius |
Measurement radius r (m), used only in . |
Returns: MeteorologicalCorrection.
Raises
| Exception | When |
|---|---|
| TypeError | if radius, static_pressure_kpa or temperature_c is not a single number, or air_absorption_db_per_m holds a text or a value that is not a real number. |
MeteorologicalCorrection
Section titled “MeteorologicalCorrection”MeteorologicalCorrection( c1: float, c2: float, c3: float | NDArray[np.float64],)Meteorological corrections C1, C2, C3 (ISO 3745:2012 Eq. 14 block).
c1 is the reference-quantity (impedance) correction and c2 the
radiation-impedance correction, both scalars in decibels; c3 is the
air-absorption correction (scalar, or per band when the attenuation
coefficient a(f) is supplied per band). All three are added to
to obtain LW.
precision_background_correction
Section titled “precision_background_correction”precision_background_correction( source_levels: NumericArrayLike, background_levels: NumericArrayLike, *, frequencies: NumericArrayLike,) -> NDArray[np.float64]Per-position background correction K1i (ISO 3745:2012 Eq. 11).
with
evaluated at each microphone position i and band. Above the upper
criterion ( dB) the background is negligible
and . The lower criterion is frequency dependent:
10 dB for one-third-octave mid-bands 250 Hz to 5000 Hz and 6 dB
for bands Hz and Hz. Below it,
is clamped to its value
at the criterion (0.46 dB and 1.26 dB respectively), a
SoundPowerWarning is emitted and those band results are upper
bounds (clause 9.4.2).
Parameters
| Name | Description |
|---|---|
source_levels |
L'pi(ST) per position and band, in decibels; shape (NM, NB) (or (NB,) for one position). |
background_levels |
Lpi(B) in the same shape (or a single spectrum broadcast to every position). |
frequencies |
(NB,) nominal mid-band frequencies (Hz), selecting the per-band lower criterion. |
Returns: K1i per position and band, in decibels, matching the broadcast shape of the inputs.
Raises
| Exception | When |
|---|---|
| TypeError | if background_levels, frequencies or source_levels holds a text or a value that is not a real number. |
precision_positions
Section titled “precision_positions”precision_positions( surface: Literal['sphere', 'hemisphere'], *, radius: float, array: Literal['general', 'broadband'] = 'general', n_positions: int = 40,) -> NDArray[np.float64]Normative ISO 3745:2012 microphone coordinates, scaled by radius.
For a 'sphere' (anechoic room) the coordinates come from Annex D
Table D.1; for a 'hemisphere' (hemi-anechoic room) from Annex E
Table E.1 (array='general') or Table E.2 (array='broadband', an
omnidirectional broadband source). Positions 1-20 are the primary array;
the full 40 add the mirror set (positions 21-40), used when the band-SPL
spread exceeds NM/2 (clause 9.3). Each row is a unit vector (self-checked)
scaled to metres by radius.
Parameters
| Name | Description |
|---|---|
surface |
'sphere' or 'hemisphere'. |
radius |
Measurement radius r, in metres. |
array |
'general' (Table E.1) or 'broadband' (Table E.2); ignored for a sphere (only Table D.1 exists). |
n_positions |
20 (primary array) or 40 (full array). |
Returns: (n_positions, 3) microphone coordinates, in metres.
Raises
| Exception | When |
|---|---|
| TypeError | if radius is not a single number, or array or surface is not a text. |
precision_uncertainty
Section titled “precision_uncertainty”precision_uncertainty( sigma_r0: float | np.floating[Any] | np.integer[Any], sigma_omc_db: float = 0.0, coverage_factor: float = 2.0,) -> float
precision_uncertainty( sigma_r0: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]], sigma_omc_db: float = 0.0, coverage_factor: float = 2.0,) -> NDArray[np.float64]
precision_uncertainty( sigma_r0: NumericArrayLike, sigma_omc_db: float = 0.0, coverage_factor: float = 2.0,) -> float | NDArray[np.float64]Expanded uncertainty (ISO 3745:2012).
ISO 3745:2012 Eq. 24/25: and , with (95 %, two-sided) or (95 %, one-sided, when comparing to a limit).
Parameters
| Name | Description |
|---|---|
sigma_r0 |
Reproducibility standard deviation (Tables 2/3), dB. |
sigma_omc_db |
Operating/mounting standard deviation sigma_omc_db, dB. |
coverage_factor |
k (typically 2 or 1.6). |
Returns: U in decibels, one value or one per band as sigma_r0 is; a float for a number; an array for a sequence or an array, a zero-dimensional one included.
Raises
| Exception | When |
|---|---|
| TypeError | if coverage_factor or sigma_omc_db is not a single number, or sigma_r0 holds a text or a value that is not a real number. |
PrecisionSoundPowerResult
Section titled “PrecisionSoundPowerResult”PrecisionSoundPowerResult( frequencies: NDArray[np.float64] | None, sound_power_level: NDArray[np.float64], surface_pressure_level: NDArray[np.float64], mean_pressure_level: NDArray[np.float64], background_correction: NDArray[np.float64], c1: float, c2: float, c3: NDArray[np.float64], directivity_index: NDArray[np.float64], non_uniformity_index: NDArray[np.float64], surface_area: float, surface: Literal['sphere', 'hemisphere'], sound_power_level_a: float, uncertainty: float, uncertainty_bands: NDArray[np.float64], coverage_factor: float,)Result of an ISO 3745:2012 (precision) sound power determination.
sound_power_level is the per-band
(Eq. 14/15). surface_pressure_level is the surface time-
averaged level Lp_bar after the per-position background correction
(Eq. 12/13); mean_pressure_level the same energy average of the raw
(uncorrected) position levels. background_correction is the
per-position per-band K1i (Eq. 11), shape (NM, NB).
c1/c2/c3 are the
meteorological corrections (Eq. 14). directivity_index is
per position and band (Eq. 21); non_uniformity_index the
per-band VIr sample standard deviation about the arithmetic mean
(Eq. 22). uncertainty is the A-weighted expanded uncertainty
(Eq. 24/25) and uncertainty_bands the
per-band value (NaN without frequencies).
sound_power_level_a is the A-weighted total LWA (Eq. C.1).
Attributes
| Name | Description |
|---|---|
surface |
One of "sphere" or "hemisphere". |
PrecisionSoundPowerResult.plot()
Section titled “PrecisionSoundPowerResult.plot()”PrecisionSoundPowerResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the precision LW spectrum with the A-weighted total.
Requires matplotlib (the [plot] extra); returns the
Axes.
Parameters
| Name | Description |
|---|---|
language |
The language of the labels: "en" or "es". |
PrecisionSoundPowerResult.report()
Section titled “PrecisionSoundPowerResult.report()”PrecisionSoundPowerResult.report( path: str | os.PathLike[str], *, metadata: ReportMetadata | None = None, engine: Literal['reportlab'] = 'reportlab', verbose: bool = False, language: Literal['en', 'es'] = 'en',) -> strRender an ISO 3745:2012 precision sound-power fiche to a PDF.
Writes the same one-page sound-power test sheet as
SoundPowerResult.report, with the standard-basis line naming the
precision method in an anechoic or hemi-anechoic room (ISO 3745:2012,
accuracy grade 1) and the measurement-basis strip stating the applied
meteorological corrections C1/C2/C3 instead of the ISO 3744
K1/K2. The per-band table shows the surface time-averaged level
Lp and the band sound-power level LW; verbose adds the
energy-averaged level Lp'.
Parameters
| Name | Description |
|---|---|
path |
Destination path of the PDF file. |
metadata |
Optional ReportMetadata supplying the header and footer identity and, via requirement, a declared A-weighted sound-power limit (lower is better). |
engine |
Rendering back end; only "reportlab" is supported. |
verbose |
When True the per-band table adds the energy-averaged level Lp'. |
language |
Fiche language: "en" (default) or "es". |
Returns: The written path as a str.
Raises
| Exception | When |
|---|---|
| ValueError | If engine is not "reportlab" or language is unknown. |
| ImportError | If reportlab (or, for the figure, matplotlib) is not installed (the [report] extra). |
sound_power_anechoic
Section titled “sound_power_anechoic”sound_power_anechoic( levels_positions: NumericArrayLike, surface: Literal['sphere', 'hemisphere'], *, radius: float, background_levels: NumericArrayLike, frequencies: NumericArrayLike, areas: NumericArrayLike | None = ..., temperature_c: float = ..., static_pressure_kpa: float = ..., air_absorption_db_per_m: NumericArrayLike | None = ..., sigma_omc_db: float = ..., coverage_factor: float = ..., room_qualification: FreeFieldCheck | None = ...,) -> PrecisionSoundPowerResult
sound_power_anechoic( levels_positions: NumericArrayLike, surface: Literal['sphere', 'hemisphere'], *, radius: float, frequencies: NumericArrayLike | None = ..., areas: NumericArrayLike | None = ..., temperature_c: float = ..., static_pressure_kpa: float = ..., air_absorption_db_per_m: NumericArrayLike | None = ..., sigma_omc_db: float = ..., coverage_factor: float = ..., room_qualification: FreeFieldCheck | None = ...,) -> PrecisionSoundPowerResultSound power level in an (hemi-)anechoic room (ISO 3745:2012, precision).
levels_positions is an (NM, NB) array of time-averaged position
levels (one row per microphone, one column
per band). Each position is background-corrected by
(Eq. 11, from background_levels and frequencies), the corrected
levels are surface-averaged (equal-area Eq. 12, or area-weighted Eq. 13
when areas are given) and combined with the surface area and the
meteorological corrections:
for a 'sphere' (anechoic, Eq. 14) or
for a 'hemisphere' (hemi-anechoic, Eq. 15). There is
no ISO 3744 K2
environmental term. The reproducibility sigma_R0 is taken from Table 3
(sphere/anechoic) or Table 2 (hemisphere/hemi-anechoic).
Parameters
| Name | Description |
|---|---|
levels_positions |
(NM, NB) position levels, in decibels. |
surface |
'sphere' or 'hemisphere'. |
radius |
Measurement radius r, in metres. |
background_levels |
(NM, NB) (or single-spectrum) background levels for K1i; requires frequencies. |
frequencies |
(NB,) nominal mid-band frequencies (Hz), for the K1 criterion, the A-weighted total and the per-band uncertainty. |
areas |
(NM,) partial areas Si for the area-weighted average (Eq. 13); omit for the equal-area average (Eq. 12). |
temperature_c |
Air temperature theta (deg C), for C1/C2. |
static_pressure_kpa |
Static pressure ps (kPa), for C1/C2. |
air_absorption_db_per_m |
a(f) (dB/m) for C3, scalar or per band; None leaves . |
sigma_omc_db |
Operating/mounting standard deviation, dB. |
coverage_factor |
k (2 two-sided, 1.6 one-sided). |
room_qualification |
The check_free_field verdict of the room (Annex A as Amendment 1:2017 wrote it). Its room type must match surface; a SoundPowerWarning says when the room is not qualified, when radius lies beyond the qualified radius, or when a band lies outside the qualified frequency range. |
Returns: PrecisionSoundPowerResult.
Raises
| Exception | When |
|---|---|
| ValueError | for a room qualification of the other room type. |
| TypeError | if radius is not a single number, or surface is not a text, or areas, background_levels, frequencies or levels_positions holds a text or a value that is not a real number. |