environmental.air_absorption

Atmospheric absorption of sound: ISO 9613-1:1993.

The attenuation of a pure tone propagating through the atmosphere is governed by a pure-tone attenuation coefficient alpha (in dB/m) that depends on frequency, temperature, humidity and pressure through the vibrational relaxation of the oxygen and nitrogen molecules plus classical and rotational losses (ISO 9613-1:1993, clause 6).

The attenuation coefficient (ISO 9613-1:1993, Eq. (5)):

alpha = 8,686 * f^2 * {
          1,84e-11 * (pa/pr)^-1 * (T/T0)^(1/2)
        + (T/T0)^(-5/2) * [
              0,012 75 * exp(-2239,1/T) * (frO + f^2/frO)^-1
            + 0,106 8  * exp(-3352,0/T) * (frN + f^2/frN)^-1
          ]
      }

in decibels per metre, with the oxygen and nitrogen relaxation frequencies (ISO 9613-1:1993, Eq. (3) and Eq. (4)):

frO = (pa/pr) * [24 + 4,04e4 * h * (0,02 + h)/(0,391 + h)]
frN = (pa/pr) * (T/T0)^(-1/2)
      * [9 + 280 * h * exp{-4,170 * [(T/T0)^(-1/3) - 1]}]

Here T is the ambient temperature (K), T0 = 293,15 K and pr = 101,325 kPa are the reference conditions (ISO 9613-1:1993, clause 4.2), pa is the ambient pressure (kPa) and h is the molar concentration of water vapour as a percentage, obtained from the relative humidity by the psychrometric conversion (ISO 9613-1:1993, clause 6.4 / Annex B):

h = hr * (psat/pr) / (pa/pr)
psat/pr = 10 ^ (-6,8346 * (T01/T)^1,261 + 4,6151),  T01 = 273,16 K

with hr the relative humidity (%) and T01 the triple-point temperature of water.

Table 1 of ISO 9613-1:1993 tabulates alpha (in dB/km) at the reference pressure for a grid of temperature, relative humidity and one-third-octave frequency; its rows are labelled with the ISO 266 preferred frequencies but the coefficients are computed at the exact midband frequencies (Note 5) fm = 1000 * 10^(k/10), k integer. Pass exact_midband=True to snap the requested frequencies onto that grid and reproduce Table 1 exactly.

This module closes the loop with phonometry.sound_absorption (ISO 354), whose air power-attenuation coefficient m (1/m) is defined only through the ISO 9613-1 alpha via m = alpha / (10 * lg e). air_attenuation_m returns that m directly.

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

air_attenuation

air_attenuation(
    frequencies: ArrayLike,
    temperature: float = 20.0,
    relative_humidity: float = 50.0,
    pressure: float = 101.325,
    *,
    exact_midband: bool = False,
) -> NDArray[np.float64]

Pure-tone atmospheric attenuation coefficient (ISO 9613-1:1993, Eq. (5)).

Evaluates alpha in decibels per metre from the oxygen and nitrogen relaxation frequencies (Eq. (3)/(4)) and the classical, rotational and vibrational absorption terms (Eq. (5)). Fully vectorized over frequencies; temperature, relative_humidity and pressure are scalars.

Parameters

Name	Description
frequencies	Frequency or frequencies f, in hertz (array-like).
temperature	Ambient air temperature, in degrees Celsius (default 20 degC, i.e. the reference T0). A value outside the -20..+50 degC tabulated range emits an AtmosphericAbsorptionWarning; a value at or below absolute zero raises ValueError.
relative_humidity	Relative humidity, in percent, with respect to saturation over liquid water (default 50 %). Outside 10..100 % emits an AtmosphericAbsorptionWarning; outside [0, 100] % raises ValueError.
pressure	Ambient atmospheric pressure pa, in kilopascals (default 101,325 kPa = one standard atmosphere = pr). Above 200 kPa emits an AtmosphericAbsorptionWarning; non-positive raises ValueError.
exact_midband	When True, each requested frequency is snapped to the nearest exact one-third-octave midband fm = 1000*10^(k/10) (Eq. (6)) before evaluation, reproducing the frequencies used for Table 1 (Note 5). Default False (use frequencies verbatim).

Returns: Attenuation coefficient alpha, in dB/m, with the shape of frequencies.

Note

ISO 354:2003 defers its air power-attenuation coefficient m (1/m) entirely to this alpha via m = alpha / (10 * lg e). Use air_attenuation_m to obtain that m for phonometry.sound_absorption.absorption_area / absorption_coefficient.

air_attenuation_m

air_attenuation_m(
    frequencies: ArrayLike,
    temperature: float = 20.0,
    relative_humidity: float = 50.0,
    pressure: float = 101.325,
    *,
    exact_midband: bool = False,
) -> NDArray[np.float64]

ISO 354 air power-attenuation coefficient m (1/m) from conditions.

Convenience composition of air_attenuation (ISO 9613-1 alpha in dB/m) with the ISO 354:2003 (8.1.2.1) conversion m = alpha / (10 * lg e) (via phonometry.sound_absorption.attenuation_from_alpha). It lets an ISO 354 caller feed real atmospheric conditions into absorption_area / absorption_coefficient instead of hand-entering m.

Parameters

Name	Description
frequencies	Frequency or frequencies f, in hertz (array-like).
temperature	Ambient air temperature, in degrees Celsius (default 20).
relative_humidity	Relative humidity, in percent (default 50).
pressure	Ambient atmospheric pressure, in kilopascals (default 101,325).
exact_midband	Snap frequencies to exact midbands; see air_attenuation.

Returns: Power attenuation coefficient m, in 1/m, with the shape of frequencies.

atmospheric_attenuation

atmospheric_attenuation(
    frequencies: ArrayLike,
    temperature: float = 20.0,
    relative_humidity: float = 50.0,
    pressure: float = 101.325,
    *,
    exact_midband: bool = False,
    distance: float | None = None,
) -> AtmosphericAttenuation

Build a plottable ISO 9613-1 atmospheric-attenuation curve.

Evaluates air_attenuation at frequencies for the given atmospheric conditions and bundles the result into an AtmosphericAttenuation that exposes .plot(). The maths is unchanged; this is a thin, plottable wrapper around the existing function (the same warnings and the same ValueError cases apply).

Parameters

Name	Description
frequencies	Frequency or frequencies f, in hertz (array-like).
temperature	Ambient air temperature, in degrees Celsius (default 20).
relative_humidity	Relative humidity, in percent (default 50).
pressure	Ambient atmospheric pressure, in kilopascals (default 101.325 kPa, one standard atmosphere).
exact_midband	Snap the frequencies to the exact one-third-octave midbands fm = 1000*10^(k/10) (Eq. (6)) before evaluation; see air_attenuation. When True the stored frequencies are the snapped midbands the coefficient was computed at.
distance	Optional propagation distance d, in metres. When given, the result’s total_attenuation returns the total attenuation A = alpha * d over that distance (ISO 9613-2 Eq. (8)). Must be finite and non-negative.

Returns: A frozen AtmosphericAttenuation.

Raises

Exception	When
ValueError	If distance is negative or non-finite (NaN/inf); the check lives on AtmosphericAttenuation so it also guards direct construction.

AtmosphericAbsorptionWarning

Advisory for ISO 9613-1 inputs outside the tabulated/validity ranges.

AtmosphericAttenuation

AtmosphericAttenuation(
    frequencies: NDArray[np.float64],
    attenuation_coefficient: NDArray[np.float64],
    temperature: float,
    relative_humidity: float,
    pressure: float,
    distance: float | None = None,
)

A pure-tone atmospheric attenuation curve (ISO 9613-1:1993).

Bundles the ISO 9613-1 attenuation coefficient alpha (Eq. (5)) over a frequency grid with the atmospheric conditions it was evaluated for, so the classic alpha versus frequency curve can be drawn with plot. Build it with atmospheric_attenuation; the frozen instance is a thin, plottable wrapper and re-runs none of the maths.

Attributes

Name	Description
frequencies	Frequencies f the coefficient is evaluated at, in Hz (the exact one-third-octave midbands when exact_midband was used).
attenuation_coefficient	Pure-tone attenuation coefficient alpha, per frequency, in decibels per metre (Table 1 prints dB/km, i.e. x 1000).
temperature	Ambient air temperature, in degrees Celsius.
relative_humidity	Relative humidity, in percent.
pressure	Ambient atmospheric pressure pa, in kilopascals.
distance	Propagation distance d, in metres, or None when the result carries only the coefficient. When given, total_attenuation returns the total attenuation A = alpha * d over that distance.

AtmosphericAttenuation.plot()

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

Plot the attenuation coefficient alpha versus frequency.

Draws alpha (in dB/km, as Table 1 tabulates it) on a logarithmic frequency axis, the classic ISO 9613-1 curve for the stored atmospheric conditions. Requires matplotlib (pip install phonometry[plot]); returns the Axes and never calls plt.show.

Parameters

Name	Description
ax	Existing axes, or None to create a figure.
language	"en" (default) or "es".
kwargs	Forwarded to the alpha curve plot call.

Returns: The axes.

AtmosphericAttenuation.total_attenuation

property

Total atmospheric attenuation A = alpha * d over distance.

The pure-tone attenuation alpha (dB/m) accumulated over the propagation distance d (m), per frequency, in decibels; this is the ISO 9613-2:1996 Aatm (Eq. (8)) form. None when no distance was supplied.