environment.propagation.air_absorption
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.
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
Section titled “air_attenuation”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
Section titled “air_power_attenuation_per_m”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
Section titled “atmospheric_attenuation”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,) -> AtmosphericAttenuationBuild 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. |
AtmosphericAbsorptionWarning
Section titled “AtmosphericAbsorptionWarning”Advisory for ISO 9613-1 inputs outside the tabulated/validity ranges.
AtmosphericAttenuation
Section titled “AtmosphericAttenuation”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()
Section titled “AtmosphericAttenuation.plot()”AtmosphericAttenuation.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot 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.
AtmosphericAttenuation.total_attenuation
Section titled “AtmosphericAttenuation.total_attenuation”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.