Skip to content

environment.propagation.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, in decibels per metre (ISO 9613-1:1993):

with the oxygen and nitrogen relaxation frequencies (ISO 9613-1:1993):

Here T is the ambient temperature (K), K and 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):

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) , 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 sound_absorption (ISO 354), whose air power-attenuation coefficient m (1/m) is defined only through the ISO 9613-1 alpha via . air_power_attenuation_per_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(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> float
air_attenuation(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> NDArray[np.float64]
air_attenuation(
frequencies: NumericArrayLike,
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> float | NDArray[np.float64]

Pure-tone atmospheric attenuation coefficient (ISO 9613-1, 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_c, relative_humidity_percent and static_pressure_kpa are scalars.

Parameters

Name Description
frequencies Frequency or frequencies f, in hertz (array-like).
temperature_c 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_percent Relative humidity, in percent, with respect to saturation over liquid water (default 50 %). Outside 10..100 % emits an AtmosphericAbsorptionWarning; outside [0, 100] % raises ValueError.
static_pressure_kpa 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 (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. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

Raises

Exception When
TypeError if relative_humidity_percent, static_pressure_kpa or temperature_c is not a single number, or frequencies holds a text or a value that is not a real number.
air_power_attenuation_per_m(
frequencies: float | np.floating[Any] | np.integer[Any],
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> float
air_power_attenuation_per_m(
frequencies: Sequence[float] | Sequence[np.floating[Any]] | Sequence[np.integer[Any]] | NDArray[np.bool_ | np.integer[Any] | np.floating[Any]],
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> NDArray[np.float64]
air_power_attenuation_per_m(
frequencies: NumericArrayLike,
*,
temperature_c: float = ...,
relative_humidity_percent: float = ...,
static_pressure_kpa: float = ...,
exact_midband: bool = ...,
) -> float | 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 (via power_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_c Ambient air temperature, in degrees Celsius (default 20).
relative_humidity_percent Relative humidity, in percent (default 50).
static_pressure_kpa 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. A float for a number, an array for a sequence or an array, a zero-dimensional one included.

atmospheric_attenuation(
frequencies: NumericArrayLike,
*,
temperature_c: float = 20.0,
relative_humidity_percent: float = 50.0,
static_pressure_kpa: 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_c Ambient air temperature, in degrees Celsius (default 20).
relative_humidity_percent Relative humidity, in percent (default 50).
static_pressure_kpa Ambient atmospheric pressure, in kilopascals (default 101.325 kPa, one standard atmosphere).
exact_midband Snap the frequencies to the exact one-third-octave midbands (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 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.
TypeError if frequencies holds a text or a value that is not a real number. distance is refused the same way when it is not one real number.

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

AtmosphericAttenuation(
frequencies: NumericArrayLike,
attenuation_db_per_m: NumericArrayLike,
temperature_c: float,
relative_humidity_percent: float,
static_pressure_kpa: 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_db_per_m Pure-tone attenuation coefficient alpha, per frequency, in decibels per metre (Table 1 prints dB/km, i.e. ).
temperature_c Ambient air temperature, in degrees Celsius.
relative_humidity_percent Relative humidity, in percent.
static_pressure_kpa 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 over that distance.
AtmosphericAttenuation.plot(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = '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 (the [plot] extra); 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.

property

Total attenuation 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.