pyfar.constants

Module for constants and physical properties of air.

Constants:

pyfar.constants.absolute_zero_celsius: Final[float] = -273.15

Absolute zero temperature \(\mathrm{t_0}\) in degree Celsius [1].

\[t_0 = -273.15 \text{°C}\]

Returns:

t_0 – Absolute zero temperature in degree Celsius.

Return type:

float

References

[1]

https://en.wikipedia.org/wiki/Absolute_zero

pyfar.constants.reference_air_density: Final[float] = 1.204

Reference air density in \(\text{kg}/\text{m}^3\) at reference atmospheric pressure and 20°C [2].

\[\rho_\text{atm} = 1.204 \, \frac{\text{kg}}{\text{m}^3}\]

Returns:

Reference air density in \(\text{kg}/\text{m}^3\).

Return type:

float

References

[2]

https://en.wikipedia.org/wiki/Density_of_air

pyfar.constants.reference_air_impedance: Final[float] = 413.21279999999996

Reference air impedance \(Z_\text{ref}\) in Pa s/m is calculated based on reference_speed_of_sound and standard_air_density.

\[Z_\text{ref} = \rho_\text{atm} \cdot c_\text{ref} \approx 413.2 \, \text{Pa s/m}\]

Returns:

Z_ref – Reference air impedance in Pa s/m.

Return type:

float

pyfar.constants.reference_air_temperature_celsius: Final[float] = 20

Reference air temperature \(t_\text{ref}\) in degree Celsius [3].

\[t_\text{ref} = 20 \text{°C}\]

Returns:

t_ref – Reference air temperature in degree Celsius.

Return type:

float

References

[3]

ISO 9613-1:1993, Acoustics – Attenuation of sound during propagation outdoors – Part 1: Calculation of the absorption of sound by the atmosphere.

pyfar.constants.reference_atmospheric_pressure: Final[float] = 101325.0

Reference atmospheric pressure \(P_\text{atm}\) in Pascal [4].

\[P_\text{atm} = 101325 \, \text{Pa}\]

Returns:

Reference atmospheric pressure in Pascal.

Return type:

float

References

[4]

https://en.wikipedia.org/wiki/Atmospheric_pressure

pyfar.constants.reference_sound_power: Final[float] = 1e-12

Reference sound power \(P_\text{ref}\) in Watt [5].

\[P_\text{ref} = 1 \, \text{pW} = 10^{-12} \, \text{W}\]

Returns:

P_ref – Reference sound power in Watt.

Return type:

float

References

[5]

https://asastandards.org/terms/sound-power-level/

pyfar.constants.reference_sound_pressure: Final[float] = 2e-05

Reference sound pressure \(p_\text{ref}\) in Pascal [6].

\[p_\text{ref} = 20 \, \mathrm{\mu Pa}\]

Returns:

p_ref – Reference sound pressure in Pascal.

Return type:

float

References

[6]

https://asastandards.org/terms/reference-value-for-sound-pressure-2/

pyfar.constants.reference_speed_of_sound: Final[float] = 343.2

Reference speed of sound \(c_\text{ref}\) in m/s for 20°C and dry air [7].

\[c_\text{ref} = 343.2 \, \text{m/s}\]

Returns:

c_ref – Reference speed of sound in m/s.

Return type:

float

References

[7]

ISO 9613-1:1993, Acoustics – Attenuation of sound during propagation outdoors – Part 1: Calculation of the absorption of sound by the atmosphere.

Functions:

air_attenuation(temperature, frequencies, ...)	Calculate the pure tone attenuation of sound in air according to ISO 9613-1.
density_of_air(temperature, relative_humidity)	Calculate the density of air in kg/m³ based on the temperature, relative humidity, and atmospheric pressure.
fractional_octave_filter_tolerance(...)	Calculate the tolerance limits for fractional octave band filters.
saturation_vapor_pressure_magnus(temperature)	Calculate the saturation vapor pressure of water in Pascal using the Magnus formula.
speed_of_sound_cramer(temperature, ...[, ...])	Calculate the speed of sound in air based on temperature, atmospheric pressure, humidity and CO2 concentration.
speed_of_sound_ideal_gas(temperature, ...[, ...])	Calculate speed of sound in air using the ideal gas law.
speed_of_sound_simple(temperature)	Calculate the speed of sound in air using a simplified version of the ideal gas law based on the temperature.

pyfar.constants.air_attenuation(temperature, frequencies, relative_humidity, atmospheric_pressure=None)

Calculate the pure tone attenuation of sound in air according to ISO 9613-1.

Calculation is in accordance with ISO 9613-1 [8]. The shape of the outputs is broadcasted from the shapes of the temperature, relative_humidity, and atmospheric_pressure. The frequency bins represents the last dimension.

Parameters:

• temperature (float, array_like) – Temperature in degree Celsius. Must be in the range of -20°C to 50°C for accuracy of +/-10% or must be greater than -70°C for accuracy of +/-50%.

• frequencies (float, array_like) – Frequency in Hz. Must be greater than 50 Hz. Just one dimensional array is allowed.

• relative_humidity (float, array_like) – Relative humidity in the range from 0 to 1.

• atmospheric_pressure (float, array_like, optional) – Atmospheric pressure in Pascal, by default reference_atmospheric_pressure.

Returns:

• alpha (np.ndarray[float]) – Pure tone air attenuation coefficient in decibels per meter for atmospheric absorption.

• m (FrequencyData) – Pure tone air attenuation coefficient per meter for atmospheric absorption. The parameter m is calculated as \(m = \alpha / (10 \cdot \log_{10}(e))\).

• accuracy (FrequencyData) – accuracy of the results according to the standard:

  10, +/- 10% accuracy

  • molar concentration of water vapour: 0.05% to 5 %.

  • air temperature: 253.15 K to 323.15 (-20 °C to +50°C)

  • atmospheric pressure: less than 200 000 Pa (2 atm)

  • frequency-to-pressure ratio: 0.0004 Hz/Pa to 10 Hz/Pa.

  20, +/- 20% accuracy

  • molar concentration of water vapour: 0.005 % to 0.05 %, and greater than 5%

  • air temperature: 253.15 K to 323.15 (-20 °C to +50°C)

  • atmospheric pressure: less than 200 000 Pa (2 atm)

  • frequency-to-pressure ratio: 0.0004 Hz/Pa to 10 Hz/Pa.

  50, +/- 50% accuracy

  • molar concentration of water vapour: less than 0.005%

  • air temperature: greater than 200 K (- 73 °C)

  • atmospheric pressure: less than 200 000 Pa (2 atm)

  • frequency-to-pressure ratio: 0.0004 Hz/Pa to 10 Hz/Pa.

  -1, no valid result

  else.

References

[8]

ISO 9613-1:1993, Acoustics – Attenuation of sound during propagation outdoors – Part 1: Calculation of the absorption of sound by the atmosphere.

pyfar.constants.density_of_air(temperature, relative_humidity, atmospheric_pressure=None, saturation_vapor_pressure=None)

Calculate the density of air in kg/m³ based on the temperature, relative humidity, and atmospheric pressure.

The density of air is calculated based on chapter 6.3 in [9]. All input parameters must be broadcastable to the same shape.

Parameters:

• temperature (float, array_like) – Temperature in degrees Celsius (°C).

• relative_humidity (float, array_like) – Relative humidity in the range from 0 to 1.

• atmospheric_pressure (float, array_like, optional) – Atmospheric pressure in Pascal (Pa), by default reference_atmospheric_pressure.

• saturation_vapor_pressure (float, array_like, optional) – Saturation vapor pressure in Pascal (Pa). The default uses the value and valid temperature range from saturation_vapor_pressure_magnus.

Returns:

density – Density of air in kg/m³.

Return type:

float, array_like

References

[9]

V. E. Ostashev and D. K. Wilson, Acoustics in Moving Inhomogeneous Media, 2nd ed. London: CRC Press, 2015. doi: 10.1201/b18922.

pyfar.constants.fractional_octave_filter_tolerance(exact_center_frequency: float, num_fractions: Literal[1, 3], tolerance_class: Literal[1, 2])

Calculate the tolerance limits for fractional octave band filters.

Calculation is in accordance with IEC 61260-1:2014 [10] (Section 5.10 and Table 1).

Note

The standard defines some lower tolerance limits as \(-\infty\), which is inconvenient for plotting. The returned tolerance is -60000 dB in these cases, which is below the smallest possible value of 20*np.log10(np.finfo(float).tiny \(\approx\)-6000 dB.

Parameters:

• exact_center_frequency (float) – The exact center frequency of the band filter in Hz (see fractional_octave_frequencies).

• num_fractions (Literal[1, 3]) – The number of bands an octave is divided into. 1 for octave bands and 3 for third octave bands.

• tolerance_class (Literal[1, 2]) – The tolerance class as defined in the standard. Must be 1 or 2.

Returns:

• lower_tolerance (numpy array) – Lower tolerance limits in dB of shape (19, ).

• upper_tolerance (numpy array) – Upper tolerance limits in dB of shape (19, ).

• frequencies (numpy array) – The frequencies in Hz at which the tolerance is given of shape (19, ).

References

[10]

IEC61260-1:2014 Octave-band and fractional-octave-band filters. Part 1: Specifications.

Examples

Class 1 tolerance region and filter for the 1000 Hz octave band.

>>> import pyfar as pf
>>> import matplotlib.pyplot as plt
>>>
>>> lower, upper, frequencies = \
...     pf.constants.fractional_octave_filter_tolerance(
...         exact_center_frequency=1000, num_fractions=1,
...         tolerance_class=1)
>>>
>>> octave_filter = pf.dsp.filter.fractional_octave_bands(
...     pf.signals.impulse(2**12), num_fractions=1,
...     frequency_range=(1000, 1000))
>>>
>>> ax = pf.plot.freq(octave_filter, color='k', label='Octave filter')
>>> plt.fill_between(
...     frequencies, lower, upper,
...     facecolor='g', alpha=.25, label='Class 1 Tolerance')
>>> ax.set_ylim(-70, 5)
>>> ax.set_xlim(63, 15_850)
>>> ax.legend()

(Source code, png, hires.png, pdf)

pyfar.constants.saturation_vapor_pressure_magnus(temperature)

Calculate the saturation vapor pressure of water in Pascal using the Magnus formula.

The Magnus formula is valid for temperatures between -45°C and 60°C [11].

\[e_s = 610.94 \cdot \exp\left(\frac{17.625 \cdot T}{T + 243.04}\right)\]

Parameters:

temperature (float, array_like) – Temperature in degrees Celsius (°C).

Returns:

p_sat – Saturation vapor pressure in Pa.

Return type:

float, array_like

References

[11]

O. A. Alduchov and R. E. Eskridge, “Improved Magnus Form Approximation of Saturation Vapor Pressure,” Journal of Applied Meteorology and Climatology, vol. 35, no. 4, pp. 60-609, Apr. 1996

pyfar.constants.speed_of_sound_cramer(temperature, relative_humidity, co2_ppm=425.19, atmospheric_pressure=None)

Calculate the speed of sound in air based on temperature, atmospheric pressure, humidity and CO₂ concentration.

This implements Cramers method described in [12].

Parameters:

• temperature (float, array_like) – Temperature in degree Celsius from 0°C to 30°C.

• relative_humidity (float, array_like) – Relative humidity in the range of 0 to 1.

• co2_ppm (float, array_like, optional) – CO₂ concentration in parts per million. The default is 425.19 ppm, based on [13]. Value must be below 10 000 ppm (1%).

• atmospheric_pressure (float, array_like, optional) – Atmospheric pressure in Pascal, by default reference_atmospheric_pressure. Value must be between 75 000 Pa to 102000 Pa.

Returns:

speed_of_sound – Speed of sound in air in m/s.

Return type:

float, array_like

References

[12]

O. Cramer, “The variation of the specific heat ratio and the speed of sound in air with temperature, pressure, humidity, and CO₂ concentration,” The Journal of the Acoustical Society of America, vol. 93, no. 5, pp. 2510-2516, May 1993, doi: 10.1121/1.405827.

[13]

Lan, X., Tans, P. and K.W. Thoning: Trends in globally-averaged CO2 determined from NOAA Global Monitoring Laboratory measurements. Version Friday, 14-Mar-2025 11:33:44 MDT https://doi.org/10.15138/9N0H-ZH07

pyfar.constants.speed_of_sound_ideal_gas(temperature, relative_humidity, atmospheric_pressure=None, saturation_vapor_pressure=None)

Calculate speed of sound in air using the ideal gas law.

The speed of sound in air can be calculated based on chapter 6.3 in [14]. All input parameters must be broadcastable to the same shape.

Parameters:

• temperature (float, array_like) – Temperature in degree Celsius.

• relative_humidity (float, array_like) – Relative humidity in the range of 0 to 1.

• atmospheric_pressure (float, array_like, optional) – Atmospheric pressure in Pascal, by default reference_atmospheric_pressure.

• saturation_vapor_pressure (float, array_like, optional) – Saturation vapor pressure in Pascal. If not given, the function saturation_vapor_pressure_magnus is used. Note that the valid temperature range therefore also depends on saturation_vapor_pressure_magnus.

Returns:

speed_of_sound – Speed of sound in air in m/s.

Return type:

float, array_like

References

[14]

V. E. Ostashev and D. K. Wilson, Acoustics in Moving Inhomogeneous Media, 2nd ed. London: CRC Press, 2015. doi: 10.1201/b18922.

pyfar.constants.speed_of_sound_simple(temperature)

Calculate the speed of sound in air using a simplified version of the ideal gas law based on the temperature.

The calculation follows ISO 9613-1 [15] (Formula A.5).

\[c(t) = c_\text{ref} \cdot \sqrt{\frac{t - t_0}{t_\text{ref} - t_0}}\]

where:

• \(t\) is the air temperature (°C)

• \(t_\text{ref}=20\mathrm{°C}\) is the reference air temperature (°C), see reference_air_temperature_celsius

• \(t_0=-273.15\) °C is the absolute zero temperature (°C), see absolute_zero_celsius

• \(c=343.2\) m/s is the speed of sound at the reference temperature, see reference_speed_of_sound

Parameters:

temperature (float, array_like) – Temperature in degree Celsius from -20°C to +50°C.

Returns:

speed_of_sound – Speed of sound in air in (m/s).

Return type:

float, array_like

References

[15]

ISO 9613-1:1993, Acoustics – Attenuation of sound during propagation outdoors – Part 1: Calculation of the absorption of sound by the atmosphere.