Ir al contenido

emission: sound power in situ

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 and sound energy levels of a source in situ, by comparison with a reference sound source: ISO 3747:2010 (engineering grade 2, survey grade 3).

The source stays where it works. A calibrated reference sound source (RSS) of known octave-band sound power LW(RSS) is set beside it and the same three or four microphone positions listen to each source in turn, in the part of the room where the field is reverberant, that is where the excess of sound pressure level over the free field, , is at least 7 dB (clause 4.1, Annex A). Both sources then see the same room and the room drops out of the algebra: the sound power level of the source under test (ST) in each octave band is the calibrated power of the RSS carried across by the difference of the two mean corrected levels (clause 8.3.1),

where the mean corrected levels are the energy averages over the n microphone positions (Eq. 8, 9) of the levels corrected position by position for background noise (clause 8.1),

with three rules around it: a margin above 15 dB needs no correction, a margin between 6 dB and 15 dB takes Eq. (7), and a margin below 6 dB caps the correction at 1.3 dB and turns the band into an upper bound that the report must flag as not meeting the background requirement. The reference source takes the same rule for its own K1i(RSS) (Eq. 9, 10), but a short margin there is no upper bound: its capped correction is subtracted from the level that Eq. (11) subtracts, so it pulls down, and 8.1 gives the upper-bound reading to the margin of the source under test alone. A determination that carries no background reading at all cannot meet the requirement either, since 8.1 declares a measurement valid only where the margin is at least 6 dB and 7.5 has the background obtained once at each position. When the RSS is run at m locations around a large source the calibrated powers and the per-location means are each energy-averaged over the locations before the subtraction (clause 8.3.2, Eq. 12).

An impulsive source is described by its sound energy level instead. The single event levels measured at each position, either N events one at a time (Eq. 13, 15) or one measurement encompassing N events (Eq. 16, 17), are background-corrected with the same rule (Eq. 14), reduced to the level of one event and averaged over positions (Eq. 18); Eq. (19) and (20) are then Eq. (11) and (12) with in place of (clause 8.5). Eq. (14) subtracts the time-averaged background level from a time-integrated event level, exactly as ISO 3741:2010 (9.2.2) and ISO 3744:2010 (8.3.4) print it; the text only asks that both be measured over the same integration time T. As printed the difference is a true signal-to-background margin for T = 1 s; the optional integration_time carries the background to the event’s interval (, clause 3.4 NOTE 1) before the subtraction.

Annex C carries either level to the reference meteorological conditions of 101.325 kPa and 23.0 °C with the radiation-impedance correction , the same C2 as ISO 3741:2010 clause 9.1.4, reused from that module; the whole ISO 3740 family prints = 296 K beside a 23.0 °C reference, so at the reference conditions C2 is +0.003 3 dB rather than zero. Eq. (C.2) estimates the static pressure from the altitude of the site. Annex D forms the A-weighted totals from the Table D.1 band corrections, which are the ISO 3744 Annex E octave values digit for digit.

Clause 9 estimates the uncertainty as (Eq. 22) and (Eq. 23), with the typical upper bound of the reproducibility read from Table 2 by grade: 1.5 dB for grade 2, which needs dB at every microphone position and a source directivity range within ±7 dB, and 4.0 dB for grade 3 otherwise. Table 1, the zoning of the test environment by lines of sight, is normative (7.4.2 divides the environment into zones with a shall, and 7.4.3 draws the microphone positions from them), but it constrains where the sources and microphones go, not what is computed from them: the positions arrive here already chosen, so the zoning is not evaluated.

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

excess_sound_pressure_level(
level: float | np.floating[Any] | np.integer[Any],
reference_sound_power_levels: float | np.floating[Any] | np.integer[Any],
distance: float | np.floating[Any] | np.integer[Any],
) -> float
excess_sound_pressure_level(
level: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
reference_sound_power_levels: NumericArrayLike,
distance: NumericArrayLike,
) -> NDArray[np.float64]
excess_sound_pressure_level(
level: float | np.floating[Any] | np.integer[Any],
reference_sound_power_levels: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
distance: NumericArrayLike,
) -> NDArray[np.float64]
excess_sound_pressure_level(
level: float | np.floating[Any] | np.integer[Any],
reference_sound_power_levels: float | np.floating[Any] | np.integer[Any],
distance: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
) -> NDArray[np.float64]
excess_sound_pressure_level(
level: NumericArrayLike,
reference_sound_power_levels: NumericArrayLike,
distance: NumericArrayLike,
) -> float | NDArray[np.float64]

Excess of sound pressure level over the free field at a distance from the reference sound source (ISO 3747:2010 Annex A, Eq. A.1).

The 11 dB is the spherical free-field relation dB, so is zero in a free field and grows with the reverberant contribution; the microphone positions of the method must lie where it is at least 7 dB (4.1, 7.4.1). Measured with A-weighted levels the quantity is , the indicator Table 2 grades the determination by. The three arguments broadcast against each other, so one calibrated power serves a whole traverse of levels and distances.

Parameters

Name Description
level Sound pressure level(s) Lp(RSS),r measured at distance r from the reference sound source, in decibels.
reference_sound_power_levels Calibrated sound power level LW(RSS) of the reference source, in decibels (per band, or A-weighted).
distance Distance(s) r from the microphone to the reference source, in metres.

Returns: The excess dLf(r), in decibels; a float when the three are all numbers; an array of their broadcast shape when one is a sequence or an array, a zero-dimensional one included.

Raises

Exception When
ValueError if any input is empty or not finite, any distance is not positive, or the three shapes do not broadcast against each other.
TypeError if distance, level or reference_sound_power_levels holds a text or a value that is not a real number.
GradeConditions(
*,
excess_levels: NumericArrayLike | None = None,
directivity_range: float | None = None,
)

The two conditions Table 2 puts on engineering grade 2.

They travel together because they answer one question between them, which row of Table 2 the determination may claim, and neither answers it alone: the grade is engineering only when the field is reverberant enough at every microphone position and the source is not too directional. Either one missing leaves the determination at survey grade 3, which is the grade the standard grants when the evidence is not there.

Parameters

Name Description
excess_levels A-weighted excess of sound pressure level over the free field, , one finite value per microphone position, in decibels (clause 4.1, Annex A). Engineering grade needs at least 7 dB at every position.
directivity_range Range of the A-weighted directivity survey of the source under test, in decibels (clause 7.2). Engineering grade needs it within 7 dB.
InSituSoundPowerResult(
frequencies: NDArray[np.float64],
sound_power_level: NDArray[np.float64],
sound_energy_level: NDArray[np.float64],
mean_source_level: NDArray[np.float64],
mean_reference_level: NDArray[np.float64],
reference_levels: NDArray[np.float64],
reference_power_level: NDArray[np.float64],
background_correction: NDArray[np.float64],
reference_background_correction: NDArray[np.float64],
background_margin_db: NDArray[np.float64],
reference_background_margin_db: NDArray[np.float64],
c2: float,
excess_levels: NDArray[np.float64] | None,
directivity_range_db: float | None,
sigma_omc_db: float,
coverage_factor: float,
sound_power_level_a: float,
sound_energy_level_a: float,
quantity: Literal['power', 'energy'],
)

Result of an ISO 3747:2010 in situ determination by comparison.

quantity says which of the two determinations this is: 'power' carries the octave-band sound power level LW (Eq. 11 or 12) in sound_power_level with sound_energy_level all NaN, and 'energy' the sound energy level LJ (Eq. 19 or 20) in sound_energy_level with sound_power_level all NaN. Both are at the meteorological conditions of the test; the properties sound_power_level_at_reference_conditions and sound_energy_level_at_reference_conditions add the Annex C correction c2 (Eq. C.1, C.3).

mean_source_level is the mean corrected level of the source under test, (Eq. 8) or (Eq. 18); reference_levels the mean corrected level of the reference sound source at each of its m locations (Eq. 9, 10) and mean_reference_level their energy mean (the second term of Eq. 12, equal to Eq. 9 for one location); reference_power_level the calibrated power of the reference source, energy-averaged over its locations (the first term of Eq. 12).

background_correction is K1i at each microphone position and band for the source under test (Eq. 7; for N events measured one at a time it is the per-position shift the per-event corrections of Eq. 13 produce in the mean of Eq. 15), reference_background_correction the same for the reference source at each location (Eq. 9, 10). background_margin_db and reference_background_margin_db are the smallest margin over the background per band, of the source under test over its positions (and events) and of the reference source over its locations and positions, NaN where no background was measured; the two flags below are read from them and the 6 dB of 8.1, so they are not fields. background_requirement_met is True only where a background level reached every position (7.5) and every margin over it was at least 6 dB. Clause 8.1 writes that margin for the source under test alone (); the flag extends the same test to the reference source, whose level enters Eq. 11 carrying a K1 of its own, rather than call a band sound on a correction the standard had to cap. It is False in a band where either margin fell below 6 dB, and False throughout when no background levels were supplied at all, since nothing was measured against. upper_bound marks the bands 8.1 calls upper bounds: the margin of the source under test was measured and fell below 6 dB while the reference source’s margin met it everywhere, so the capped K1i leaves the level too high. A band where the reference source’s margin is short is not one, since its capped correction pulls the level down; it is flagged by background_requirement_met alone.

excess_levels and directivity_range_db are the two indicators Table 2 grades the determination by, the A-weighted excess at each microphone position and the directivity range of the source, None where they were not determined. grade is the accuracy grade Table 2 grants from them ('engineering' or 'survey') and sigma_r0 its typical reproducibility; sigma_omc_db, sigma_tot and expanded_uncertainty are the operating-and-mounting deviation, Eq. (22) and Eq. (23) for coverage_factor, NaN when no sigma_omc_db was supplied. The grade and the three figures read from it are read-only properties, so they are not fields. sound_power_level_a and sound_energy_level_a are the Annex D A-weighted totals of the level that was determined (NaN for the other).

InSituSoundPowerResult.background_requirement_met

Section titled “InSituSoundPowerResult.background_requirement_met”

property

Per band, whether every margin of both sources reached the 6 dB of 8.1.

False where no background was measured. The margins are judged settled, as K1 is read from them.

InSituSoundPowerResult.expanded_uncertainty

Section titled “InSituSoundPowerResult.expanded_uncertainty”

property

Eq. (23), coverage_factor times sigma_tot, in dB.

property

The accuracy grade Table 2 grants, 'engineering' or 'survey'.

Engineering only with an excess of at least 7 dB at every position and a directivity range within 7 dB; survey whenever either indicator fails or was not determined.

InSituSoundPowerResult.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the determined spectrum with the A-weighted total annotated.

One bar per octave band of LW (or LJ for an energy determination); a band that 8.1 makes an upper bound is hatched and named as one, and a band that fails the background requirement otherwise is cross-hatched and named as that. Requires matplotlib (the [plot] extra); returns the Axes.

Parameters

Name Description
language The language of the labels: "en" or "es".

property

The typical reproducibility of Table 2 at grade, in dB.

property

Eq. (22), , NaN without sigma_omc_db.

InSituSoundPowerResult.sound_energy_level_at_reference_conditions

Section titled “InSituSoundPowerResult.sound_energy_level_at_reference_conditions”

property

LJ under the reference meteorological conditions, LJ + C2 (ISO 3747:2010 Annex C, Eq. C.3); NaN for a power determination.

InSituSoundPowerResult.sound_power_level_at_reference_conditions

Section titled “InSituSoundPowerResult.sound_power_level_at_reference_conditions”

property

LW under the reference meteorological conditions, LW + C2 (ISO 3747:2010 Annex C, Eq. C.1); NaN for an energy determination.

property

Per band, whether 8.1 calls the level an upper bound.

The margin of the source under test was measured and fell below 6 dB while the reference source’s margin met it everywhere.

sound_energy_in_situ(
event_levels: NumericArrayLike,
reference_levels: NumericArrayLike,
reference_sound_power_levels: NumericArrayLike | ReferenceSourceCalibration,
*,
frequencies: NumericArrayLike,
n_events: int | np.integer[Any] | None = None,
background_levels: NumericArrayLike | None = None,
reference_background_levels: NumericArrayLike | None = None,
integration_time: float | None = None,
temperature_c: float = 23.0,
static_pressure_kpa: float = 101.325,
conditions: GradeConditions | None = None,
sigma_omc_db: float | None = None,
coverage_factor: float = 2.0,
) -> InSituSoundPowerResult

Sound energy level of an impulsive source in situ, by comparison with a reference sound source (ISO 3747:2010, clauses 8.4 and 8.5).

The single event levels are given in one of the two forms clause 8.4 admits. Measured one event at a time, event_levels is (n, N, bands): each event is corrected for background (Eq. 13, 14) and the N corrected levels are energy-averaged into the mean single event level of the position (Eq. 15). Measured once over N successive events, event_levels is (n, bands) with n_events=N: the level is corrected (Eq. 16) and reduced by to one event (Eq. 17). Either way the per-position levels are energy-averaged (Eq. 18) and the sound energy level in each band is

or its m-location form (Eq. 20). The reference source is measured time-averaged, over 30 s (7.6), exactly as for a steady source.

Parameters

Name Description
event_levels Measured (uncorrected) octave-band single event levels L'Ei,q(ST) as (n, N, bands), or L'Ei,N(ST) of one measurement encompassing n_events events as (n, bands), in decibels.
reference_levels Time-averaged levels of the reference sound source, (n, bands) or (m, n, bands), as in sound_power_in_situ.
reference_sound_power_levels Calibrated sound power level of the reference source, (bands,) or (m, bands), in decibels, or its ReferenceSourceCalibration, as for sound_power_in_situ.
frequencies Nominal octave mid-band frequencies, one per band.
n_events The number N of events a 2D event_levels contains (Eq. 17); must be None with the 3D form, which counts them.
background_levels Octave-band time-averaged background levels Lpi(B), (n, bands) or (bands,), in decibels; None applies no correction, warns, and leaves background_requirement_met False in every band (7.5, 8.1).
reference_background_levels Background for the reference-source measurement; None reuses background_levels (7.5).
integration_time The integration time T of the event measurement, in seconds. None applies Eq. (14) as printed, subtracting the time-averaged background from the single event level; a value carries the background to the same interval first, with T0 = 1 s (3.4, NOTE 1), so that the margin compares like with like. The two coincide at T = 1 s.
temperature_c Air temperature at the test, in degrees Celsius.
static_pressure_kpa Static pressure at the test, in kilopascals, as for sound_power_in_situ; Annex C itself prints pascals.
conditions The GradeConditions of the determination, as for sound_power_in_situ.
sigma_omc_db Operating-and-mounting standard deviation, in decibels.
coverage_factor k of Eq. (23), 2 by default.

Returns: InSituSoundPowerResult with quantity='energy'.

Raises

Exception When
ValueError if event_levels is not a finite 2D or 3D array, n_events is given with the 3D form or missing or not a positive integer with the 2D form, integration_time is not positive, or any of the refusals of sound_power_in_situ applies.
TypeError if integration_time is not a single number, or n_events is a flag, a text or an array where a count goes, or background_levels or event_levels holds a text or a value that is not a real number.
sound_power_in_situ(
levels: NumericArrayLike,
reference_levels: NumericArrayLike,
reference_sound_power_levels: NumericArrayLike | ReferenceSourceCalibration,
*,
frequencies: NumericArrayLike,
background_levels: NumericArrayLike | None = None,
reference_background_levels: NumericArrayLike | None = None,
temperature_c: float = 23.0,
static_pressure_kpa: float = 101.325,
conditions: GradeConditions | None = None,
sigma_omc_db: float | None = None,
coverage_factor: float = 2.0,
) -> InSituSoundPowerResult

Sound power level of a steady or non-steady source in situ, by comparison with a reference sound source (ISO 3747:2010, clause 8.3).

The time-averaged octave-band levels of the source under test at the n microphone positions are corrected for background noise position by position (Eq. 7 with the rules of 8.1) and energy-averaged (Eq. 8); the reference source’s levels at the same positions are treated the same way (Eq. 9), or per location and then energy-averaged over the m locations together with its calibrated powers (Eq. 10, 12). The sound power level in each band is then

at the meteorological conditions of the test; the returned c2 and the sound_power_level_at_reference_conditions property carry it to the reference conditions of Annex C, and sound_power_level_a is the Annex D total.

Parameters

Name Description
levels Measured (uncorrected) octave-band time-averaged levels L'pi(ST) of the source under test, (n, bands), one row per microphone position, in decibels.
reference_levels The same for the reference sound source, L'pi(RSS) already corrected for speed, temperature and static pressure per its manufacturer but not for background: (n, bands) for one location, or (m, n, bands) for m locations (Eq. 10).
reference_sound_power_levels Calibrated octave-band sound power level LW(RSS) of the reference source, (bands,), or (m, bands) when each location was calibrated in its own similar position (Eq. 12), in decibels; or the ReferenceSourceCalibration of ISO 6926, whose one-third octave bands are summed into the octaves at frequencies. It is read as calibrated: Eq. (9) corrects the measured levels of the reference source for speed, temperature and static pressure by the manufacturer’s specifications instead.
frequencies Nominal octave mid-band frequencies, one per band, from 63 Hz to 8 kHz (Table D.1), in hertz.
background_levels Octave-band time-averaged background levels Lpi(B), (n, bands) or one (bands,) spectrum for every position, in decibels; None applies no correction, warns, and leaves background_requirement_met False in every band, since 7.5 has the background measured at each position and 8.1 needs the margin to declare the measurement valid.
reference_background_levels Background for the reference-source measurement, same shapes; None reuses background_levels, since the procedure takes one background reading (7.5).
temperature_c Air temperature at the test, in degrees Celsius.
static_pressure_kpa Static pressure at the test, in kilopascals (see static_pressure_from_altitude). Annex C prints this quantity in pascals, with = 1.013 25 x 10^5 Pa, and is alone in its family in doing so: ISO 3741:2010, ISO 3744:2010 and ISO 3745:2012 all print kilopascals. This argument follows the three, so that one unit serves the whole ISO 3740 family; C2 carries a pressure term and a temperature term, and the pressure enters only as the ratio , so converting both together cannot move a result.
conditions The GradeConditions Table 2 reads to decide the accuracy grade: the excess of sound pressure level at each microphone position (Annex A) and the range of the directivity survey of the source (7.2). None, or either condition left out, leaves the determination at survey grade.
sigma_omc_db Standard deviation of the operating and mounting conditions of the source (9.2, E.3), in decibels; None leaves sigma_tot and the expanded uncertainty NaN.
coverage_factor k of Eq. (23): 2 for the two-sided 95 % interval (default), 1.6 for a one-sided comparison with a limit.

Returns: InSituSoundPowerResult with quantity='power'.

Raises

Exception When
ValueError if levels is not a finite (n, bands) array, reference_levels, reference_sound_power_levels or either background does not match it, frequencies are not the octave centres of Table D.1, temperature_c or static_pressure_kpa is out of range, conditions.excess_levels is supplied and is not one finite value per position, conditions.directivity_range or sigma_omc_db is supplied and is negative, or coverage_factor is not positive.
TypeError if background_levels or levels holds a text or a value that is not a real number.
static_pressure_from_altitude(altitude: float) -> float

Static pressure at the altitude of the test site (ISO 3747:2010 Annex C, Eq. C.2).

Annex C prints = 1.013 25 x 10^5 Pa and states the quantity in pascals. The result here is in kilopascals so that it feeds static_pressure_kpa of sound_power_in_situ directly, matching ISO 3741, ISO 3744 and ISO 3745, which do print kilopascals. The pressure reaches C2 only as , so the two unit conventions give the same correction. A site below sea level is admissible (the base exceeds one); the formula stops meaning anything where the base reaches zero, some 44 km up, and that is refused.

Parameters

Name Description
altitude Altitude of the test site Ha, in metres, one site at a time.

Returns: The static pressure ps, in kilopascals.

Raises

Exception When
TypeError if altitude is an array: one site at a time.
ValueError if altitude is not a finite number or 1 - a Ha is not positive.