Ir al contenido

emission: sound power in an anechoic room

La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.

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(
*,
temperature_c: float = 23.0,
static_pressure_kpa: float = 101.325,
air_absorption_db_per_m: NumericArrayLike | None = None,
radius: float = 1.0,
) -> MeteorologicalCorrection

Meteorological 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(
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(
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(
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(
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(
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(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot 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(
path: str | os.PathLike[str],
*,
metadata: ReportMetadata | None = None,
engine: Literal['reportlab'] = 'reportlab',
verbose: bool = False,
language: Literal['en', 'es'] = 'en',
) -> str

Render 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(
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 = ...,
) -> PrecisionSoundPowerResult

Sound 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.