Descriptors

The descriptors module offers all kinds of acoustics related descriptors.

Descriptors from ISO/TR 25417:2007.

ATTRIBUTE	DESCRIPTION
REFERENCE_PRESSURE	Reference pressure for sound pressure level calculations.
REFERENCE_SOUND_EXPOSURE	Reference sound exposure for sound exposure level calculations.
REFERENCE_POWER	Reference power for sound power level calculations.
REFERENCE_ENERGY	Reference energy for sound energy level calculations.
REFERENCE_INTENSITY	Reference intensity for sound intensity level calculations.

FUNCTION	DESCRIPTION
sound_pressure_level	Calculate sound pressure level.
equivalent_sound_pressure_level	Calculate equivalent sound pressure level.
peak_sound_pressure	Calculate peak sound pressure.
peak_sound_pressure_level	Calculate peak sound pressure level.
sound_exposure	Calculate sound exposure.
sound_exposure_level	Calculate sound exposure level.
sound_power_level	Calculate sound power level.
sound_energy	Calculate sound energy.
sound_energy_level	Calculate sound energy level.
sound_intensity	Calculate sound intensity.
time_averaged_sound_intensity	Calculate time-averaged sound intensity.
time_averaged_sound_intensity_level	Calculate time-averaged sound intensity level.
normal_time_averaged_sound_intensity	Calculate normal time-averaged sound intensity.
normal_time_averaged_sound_intensity_level	Calculate normal time-averaged sound intensity level.

Other descriptors

---

Attributes

REFERENCE_PRESSURE module-attribute

REFERENCE_PRESSURE = 2e-05

Reference value of the sound pressure \(p_0\) is \(2 \cdot 10^{-5}\) Pa.

REFERENCE_SOUND_EXPOSURE module-attribute

REFERENCE_SOUND_EXPOSURE = 4e-10

Reference value of the sound exposure \(E_0\) is \(4 \cdot 10^{-12} \mathrm{Pa}^2\mathrm{s}\).

REFERENCE_POWER module-attribute

REFERENCE_POWER = 1e-12

Reference value of the sound power \(P_0\) is 1 pW.

REFERENCE_ENERGY module-attribute

REFERENCE_ENERGY = 1e-12

Reference value of the sound energy \(J_0\) is 1 pJ.

REFERENCE_INTENSITY module-attribute

REFERENCE_INTENSITY = 1e-12

Reference value of the sound intensity \(I_0\) is \(\mathrm{1 pW/m^2}\).

Functions

sound_pressure_level

sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE
) -> float | ndarray

Sound pressure level \(L_p\) in dB.

The sound pressure level is calculated as: $$ L_p = 10 \log_{10}{ \left( \frac{p^2}{p_0^2} \right)} $$

See section 2.2 of the standard.

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
reference_pressure	Reference value \(p_0\). DEFAULT: REFERENCE_PRESSURE

RETURNS	DESCRIPTION
float | ndarray	Sound pressure level

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE
) -> float | np.ndarray:
    r"""Sound pressure level $L_p$ in dB.

    The sound pressure level is calculated as:
    $$
    L_p = 10 \log_{10}{ \left( \frac{p^2}{p_0^2} \right)}
    $$

    See section 2.2 of the standard.

    Args:
        pressure: Instantaneous sound pressure $p$.
        reference_pressure: Reference value $p_0$.

    Returns:
        Sound pressure level
    """
    return 10.0 * np.log10(pressure**2.0 / reference_pressure**2.0)

equivalent_sound_pressure_level

equivalent_sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE, axis=-1
) -> float | ndarray

Time-averaged sound pressure level \(L_{p,T}\) or equivalent-continious sound pressure level \(L_{p,eqT}\) in dB.

The time-averaged sound pressure level is calculated as: $$ L_{p,T} = L_{p,eqT} = 10.0 \log_{10}{ \left( \frac{\frac{1}{T} \int_{t_1}^{t_2} p^2 (t) \mathrm{d} t }{p_0^2} \right)} $$

See section 2.3 of the standard.

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
reference_pressure	Reference value \(p_0\). DEFAULT: REFERENCE_PRESSURE
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Time-averaged sound pressure level

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def equivalent_sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE, axis=-1
) -> float | np.ndarray:
    r"""Time-averaged sound pressure level $L_{p,T}$ or equivalent-continious sound pressure level $L_{p,eqT}$ in dB.

    The time-averaged sound pressure level is calculated as:
    $$
    L_{p,T} = L_{p,eqT} = 10.0 \log_{10}{ \left( \frac{\frac{1}{T} \int_{t_1}^{t_2} p^2 (t) \mathrm{d} t  }{p_0^2} \right)}
    $$

    See section 2.3 of the standard.

    Args:
        pressure: Instantaneous sound pressure $p$.
        reference_pressure: Reference value $p_0$.
        axis: Axis

    Returns:
        Time-averaged sound pressure level
    """
    return 10.0 * np.log10((pressure**2.0).mean(axis=axis) / reference_pressure**2.0)

peak_sound_pressure

peak_sound_pressure(pressure, axis=-1) -> float | ndarray

Peak sound pressure \(p_{peak}\) is the greatest absolute sound pressure during a certain time interval.

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Peak sound pressure \(p_{peak} = \mathrm{max}(|p|)\)

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def peak_sound_pressure(pressure, axis=-1) -> float | np.ndarray:
    r"""Peak sound pressure $p_{peak}$ is the greatest absolute sound pressure during a certain time interval.

    Args:
        pressure: Instantaneous sound pressure $p$.
        axis: Axis

    Returns:
        Peak sound pressure $p_{peak} = \mathrm{max}(|p|)$
    """
    return np.abs(pressure).max(axis=axis)

peak_sound_pressure_level

peak_sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE, axis=-1
) -> float | ndarray

Peak sound pressure level \(L_{p,peak}\) in dB.

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
reference_pressure	Reference value \(p_0\). DEFAULT: REFERENCE_PRESSURE
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Peak sound pressure level $$ L_{p,peak} = 10.0 \log \frac{p_{peak}^2.0}{p_0^2} $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def peak_sound_pressure_level(
    pressure, reference_pressure=REFERENCE_PRESSURE, axis=-1
) -> float | np.ndarray:
    r"""Peak sound pressure level $L_{p,peak}$ in dB.

    Args:
        pressure: Instantaneous sound pressure $p$.
        reference_pressure: Reference value $p_0$.
        axis: Axis

    Returns:
        Peak sound pressure level
            $$
            L_{p,peak} = 10.0 \log \frac{p_{peak}^2.0}{p_0^2}
            $$
    """
    return 10.0 * np.log10(
        peak_sound_pressure(pressure, axis=axis) ** 2.0 / reference_pressure**2.0
    )

sound_exposure

sound_exposure(pressure, fs, axis=-1) -> float | ndarray

Calculate sound exposure \(E_T\).

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
fs	Sample frequency \(f_s\).
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Sound exposure $$ E_T = \int_{t_1}^{t_2} p^2(t) \mathrm{d}t $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_exposure(pressure, fs, axis=-1) -> float | np.ndarray:
    r"""Calculate sound exposure $E_T$.

    Args:
        pressure: Instantaneous sound pressure $p$.
        fs: Sample frequency $f_s$.
        axis: Axis

    Returns:
        Sound exposure
            $$
            E_T = \int_{t_1}^{t_2} p^2(t) \mathrm{d}t
            $$
    """
    return (pressure**2.0 / fs).sum(axis=axis)

sound_exposure_level

sound_exposure_level(
    pressure,
    fs,
    reference_sound_exposure=REFERENCE_SOUND_EXPOSURE,
    axis=-1,
) -> float | ndarray

Sound exposure level \(L_{E,T}\) in dB.

PARAMETER	DESCRIPTION
pressure	Instantaneous sound pressure \(p\).
fs	Sample frequency \(f_s\).
reference_sound_exposure	Reference sound exposure \(E_T\). DEFAULT: REFERENCE_SOUND_EXPOSURE
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Sound exposure level $$ L_{E,T} = 10 \log_{10}{ \frac{E_T}{E_0} } $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_exposure_level(
    pressure, fs, reference_sound_exposure=REFERENCE_SOUND_EXPOSURE, axis=-1
) -> float | np.ndarray:
    r"""Sound exposure level $L_{E,T}$ in dB.

    Args:
        pressure: Instantaneous sound pressure $p$.
        fs: Sample frequency $f_s$.
        reference_sound_exposure: Reference sound exposure $E_T$.
        axis: Axis

    Returns:
        Sound exposure level
            $$
            L_{E,T} = 10 \log_{10}{ \frac{E_T}{E_0}  }
            $$
    """
    return 10.0 * np.log10(
        sound_exposure(pressure, fs, axis=axis) / reference_sound_exposure
    )

sound_power_level

sound_power_level(
    power, reference_power=REFERENCE_POWER
) -> float | ndarray

Sound power level \(L_W\).

PARAMETER	DESCRIPTION
power	Sound power \(P\).
reference_power	Reference sound power \(P_0\). DEFAULT: REFERENCE_POWER

RETURNS	DESCRIPTION
float | ndarray	Sound power level calculated as: $$ 10 \log_{10}{ \frac{P}{P_0} } $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_power_level(power, reference_power=REFERENCE_POWER) -> float | np.ndarray:
    r"""Sound power level $L_W$.

    Args:
        power: Sound power $P$.
        reference_power: Reference sound power $P_0$.

    Returns:
        Sound power level calculated as:
            $$
            10 \log_{10}{ \frac{P}{P_0}  }
            $$
    """
    return 10.0 * np.log10(power / reference_power)

sound_energy

sound_energy(power, axis=-1) -> float | ndarray

Sound energy \(J\).

PARAMETER	DESCRIPTION
power	Sound power \(P\).
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float | ndarray	Sound energy $$ J = \int_{t_1}^{t_2} P(t) \mathrm{d} t $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_energy(power, axis=-1) -> float | np.ndarray:
    r"""Sound energy $J$.

    Args:
        power: Sound power $P$.
        axis: Axis

    Returns:
        Sound energy
            $$
            J = \int_{t_1}^{t_2} P(t) \mathrm{d} t
            $$
    """
    return power.sum(axis=axis)

sound_energy_level

sound_energy_level(
    energy, reference_energy=REFERENCE_ENERGY
) -> ndarray

Sound energy level \(L_J\) in dB.

PARAMETER	DESCRIPTION
energy	Sound energy \(J\).
reference_energy	Reference sound energy \(J_0\). DEFAULT: REFERENCE_ENERGY

RETURNS	DESCRIPTION
ndarray	Sound energy level $$ L_{J} = 10 \log_{10}{ \frac{J}{J_0} } $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_energy_level(energy, reference_energy=REFERENCE_ENERGY) -> np.ndarray:
    r"""Sound energy level $L_J$ in dB.

    Args:
        energy: Sound energy $J$.
        reference_energy: Reference sound energy $J_0$.

    Returns:
        Sound energy level
            $$
            L_{J} = 10 \log_{10}{ \frac{J}{J_0} }
            $$
    """
    return np.log10(energy / reference_energy)

sound_intensity

sound_intensity(pressure, velocity) -> ndarray

Sound intensity \(\mathbf{i}\).

PARAMETER	DESCRIPTION
pressure	Sound pressure \(p(t)\).
velocity	Particle velocity \(\mathbf{u}(t)\).

RETURNS	DESCRIPTION
ndarray	Sound intensity $$ \mathbf{i} = p(t) \cdot \mathbf{u}(t) $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def sound_intensity(pressure, velocity) -> np.ndarray:
    r"""Sound intensity $\mathbf{i}$.

    Args:
        pressure: Sound pressure $p(t)$.
        velocity: Particle velocity $\mathbf{u}(t)$.

    Returns:
        Sound intensity
            $$
            \mathbf{i} = p(t) \cdot \mathbf{u}(t)
            $$
    """
    return pressure * velocity

time_averaged_sound_intensity

time_averaged_sound_intensity(intensity, axis=-1) -> float

Time-averaged sound intensity \(\mathbf{I}_T\).

PARAMETER	DESCRIPTION
intensity	Sound intensity \(\mathbf{i}\).
axis	Axis DEFAULT: -1

RETURNS	DESCRIPTION
float	Time-averaged sound intensity $$ I_T = \frac{1}{T} \int_{t_1}^{t_2} \mathbf{i}(t) $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def time_averaged_sound_intensity(intensity, axis=-1) -> float:
    r"""Time-averaged sound intensity $\mathbf{I}_T$.

    Args:
        intensity: Sound intensity $\mathbf{i}$.
        axis: Axis

    Returns:
        Time-averaged sound intensity
            $$
            I_T = \frac{1}{T} \int_{t_1}^{t_2} \mathbf{i}(t)
            $$
    """
    return intensity.mean(axis=axis)

time_averaged_sound_intensity_level

time_averaged_sound_intensity_level(
    time_averaged_sound_intensity,
    reference_intensity=REFERENCE_INTENSITY,
    axis=-1,
) -> float

Time-averaged sound intensity level \(L_{I,T}\).

PARAMETER	DESCRIPTION
time_averaged_sound_intensity	Time-averaged sound intensity \(\mathbf{I}_T\).
reference_intensity	Reference sound intensity \(I_0\). DEFAULT: REFERENCE_INTENSITY
axis	Axis along which to calculate norm. DEFAULT: -1

RETURNS	DESCRIPTION
float	Time-averaged sound intensity level calculated as: $$ L_{I,T} = 10 \log_{10} { \frac{|\mathbf{I}_T|}{I_0} } $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def time_averaged_sound_intensity_level(
    time_averaged_sound_intensity, reference_intensity=REFERENCE_INTENSITY, axis=-1
) -> float:
    r"""Time-averaged sound intensity level $L_{I,T}$.

    Args:
        time_averaged_sound_intensity: Time-averaged sound intensity $\mathbf{I}_T$.
        reference_intensity: Reference sound intensity $I_0$.
        axis: Axis along which to calculate norm.

    Returns:
        Time-averaged sound intensity level calculated as:
            $$
            L_{I,T} = 10 \log_{10} { \frac{|\mathbf{I}_T|}{I_0} }
            $$
    """
    return 10.0 * np.log10(
        np.linalg.norm(time_averaged_sound_intensity, axis=axis) / reference_intensity
    )

normal_time_averaged_sound_intensity

normal_time_averaged_sound_intensity(
    time_averaged_sound_intensity, unit_normal_vector
) -> float

Normal time-averaged sound intensity \(\mathbf{I}_{n,T}\).

PARAMETER	DESCRIPTION
time_averaged_sound_intensity	Time-averaged sound intensity \(\mathbf{I}_T\).
unit_normal_vector	Unit normal vector \(\mathbf{n}\).

RETURNS	DESCRIPTION
float	Normal time-averaged sound intensity $$ I_{n,T} = \mathbf{I}_T \cdot \mathbf{n} $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def normal_time_averaged_sound_intensity(
    time_averaged_sound_intensity, unit_normal_vector
) -> float:
    r"""Normal time-averaged sound intensity $\mathbf{I}_{n,T}$.

    Args:
        time_averaged_sound_intensity: Time-averaged sound intensity $\mathbf{I}_T$.
        unit_normal_vector: Unit normal vector $\mathbf{n}$.

    Returns:
        Normal time-averaged sound intensity
            $$
            I_{n,T} = \mathbf{I}_T \cdot \mathbf{n}
            $$
    """
    return time_averaged_sound_intensity.dot(unit_normal_vector)

normal_time_averaged_sound_intensity_level

normal_time_averaged_sound_intensity_level(
    normal_time_averaged_sound_intensity,
    reference_intensity=REFERENCE_INTENSITY,
) -> float

Normal time-averaged sound intensity level \(L_{I_{n,T}}\) in dB.

PARAMETER	DESCRIPTION
normal_time_averaged_sound_intensity	Normal time-averaged sound intensity \(I_{n,T}\).
reference_intensity	Reference sound intensity \(I_0\). DEFAULT: REFERENCE_INTENSITY

RETURNS	DESCRIPTION
float	Normal time-averaged sound intensity level calculated as: $$ I_{n,T} = 10 \log_{10} { \frac{|I_{n,T}|}{I_0}} $$

Source code in acoustic_toolbox/standards/iso_tr_25417_2007.py

def normal_time_averaged_sound_intensity_level(
    normal_time_averaged_sound_intensity, reference_intensity=REFERENCE_INTENSITY
) -> float:
    r"""Normal time-averaged sound intensity level $L_{I_{n,T}}$ in dB.

    Args:
        normal_time_averaged_sound_intensity: Normal time-averaged sound intensity $I_{n,T}$.
        reference_intensity: Reference sound intensity $I_0$.

    Returns:
        Normal time-averaged sound intensity level calculated as:
            $$
            I_{n,T} = 10 \log_{10} { \frac{|I_{n,T}|}{I_0}}
            $$
    """
    return 10.0 * np.log10(
        np.abs(normal_time_averaged_sound_intensity / reference_intensity)
    )

leq

leq(levels, int_time=1.0) -> float

Equivalent level \(L_{eq}\).

PARAMETER	DESCRIPTION
levels	Levels as function of time.
int_time	Integration time in seconds. DEFAULT: 1.0

RETURNS	DESCRIPTION
float	Equivalent level \(L_{eq}\).

Source code in acoustic_toolbox/descriptors.py

def leq(levels, int_time=1.0) -> float:
    """Equivalent level $L_{eq}$.

    Args:
      levels: Levels as function of time.
      int_time: Integration time in seconds.

    Returns:
      Equivalent level $L_{eq}$.
    """
    levels = np.asarray(levels)
    time = levels.size * int_time
    return _leq(levels, time)

sel

sel(levels: ndarray) -> float

Sound Exposure Level from levels.

Source code in acoustic_toolbox/descriptors.py

def sel(levels: np.ndarray) -> float:
    """Sound Exposure Level from ``levels``."""
    levels = np.asarray(levels)
    return _leq(levels, 1.0)

lw

lw(W, Wref=1e-12) -> float

Sound power level \(L_{w}\) for sound power \(W\) and reference power \(W_{ref}\).

PARAMETER	DESCRIPTION
W	Sound power \(W\).
Wref	Reference power \(W_{ref}\). Default value is \(10^{12}\) watt. DEFAULT: 1e-12

RETURNS	DESCRIPTION
float	Sound power level \(L_{w}\).

Source code in acoustic_toolbox/descriptors.py

def lw(W, Wref=1.0e-12) -> float:
    """Sound power level $L_{w}$ for sound power $W$ and reference power $W_{ref}$.

    Args:
      W: Sound power $W$.
      Wref: Reference power $W_{ref}$. Default value is $10^{12}$ watt.

    Returns:
      Sound power level $L_{w}$.
    """
    W = np.asarray(W)
    return 10.0 * np.log10(W / Wref)

lden

lden(
    lday,
    levening,
    lnight,
    hours: tuple[float, float, float] = (12.0, 4.0, 8.0),
    adjustment: tuple[float, float, float] = (
        0.0,
        5.0,
        10.0,
    ),
) -> float

Calculate \(L_{den}\) from \(L_{day}\), \(L_{evening}\) and \(L_{night}\).

PARAMETER	DESCRIPTION
lday	Equivalent level during day period \(L_{day}\).
levening	Equivalent level during evening period \(L_{evening}\).
lnight	Equivalent level during night period \(L_{night}\).
hours	Hours per period. TYPE: tuple[float, float, float] DEFAULT: (12.0, 4.0, 8.0)
adjustment	Correction factor per period. TYPE: tuple[float, float, float] DEFAULT: (0.0, 5.0, 10.0)

RETURNS	DESCRIPTION
float	\(L_{den}\)

See Also

composite_rating_level

Source code in acoustic_toolbox/descriptors.py

def lden(
    lday,
    levening,
    lnight,
    hours: tuple[float, float, float] = (12.0, 4.0, 8.0),
    adjustment: tuple[float, float, float] = (0.0, 5.0, 10.0),
) -> float:
    """Calculate $L_{den}$ from $L_{day}$, $L_{evening}$ and $L_{night}$.

    Args:
      lday: Equivalent level during day period $L_{day}$.
      levening: Equivalent level during evening period $L_{evening}$.
      lnight: Equivalent level during night period $L_{night}$.
      hours: Hours per period.
      adjustment: Correction factor per period.

    Returns:
      $L_{den}$

    See Also:
      [composite_rating_level][acoustic_toolbox.standards.iso_1996_1_2003.composite_rating_level]

    """
    lday = np.asarray(lday)
    levening = np.asarray(levening)
    lnight = np.asarray(lnight)
    return composite_rating_level(
        np.vstack((lday, levening, lnight)).T, hours, adjustment
    )

ldn

ldn(
    lday,
    lnight,
    hours: tuple[float, float] = (15.0, 9.0),
    adjustment: tuple[float, float] = (0.0, 10.0),
) -> float

Calculate \(L_{dn}\) from \(L_{day}\) and \(L_{night}\).

PARAMETER	DESCRIPTION
lday	Equivalent level during day period \(L_{day}\).
lnight	Equivalent level during night period \(L_{night}\).
hours	Hours per period. TYPE: tuple[float, float] DEFAULT: (15.0, 9.0)
adjustment	Correction factor per period. TYPE: tuple[float, float] DEFAULT: (0.0, 10.0)

RETURNS	DESCRIPTION
float	\(L_{dn}\)

See Also

composite_rating_level

Source code in acoustic_toolbox/descriptors.py

def ldn(
    lday,
    lnight,
    hours: tuple[float, float] = (15.0, 9.0),
    adjustment: tuple[float, float] = (0.0, 10.0),
) -> float:
    """Calculate $L_{dn}$ from $L_{day}$ and $L_{night}$.

    Args:
      lday: Equivalent level during day period $L_{day}$.
      lnight: Equivalent level during night period $L_{night}$.
      hours: Hours per period.
      adjustment: Correction factor per period.

    Returns:
      $L_{dn}$

    See Also:
      [composite_rating_level][acoustic_toolbox.standards.iso_1996_1_2003.composite_rating_level]
    """
    lday = np.asarray(lday)
    lnight = np.asarray(lnight)
    return composite_rating_level(np.vstack((lday, lnight)).T, hours, adjustment)

:::