acoular 24.7__py3-none-any.whl → 25.1__py3-none-any.whl

acoular/tfastfuncs.py

@@ -41,14 +41,14 @@ def _delayandsum4(data, offsets, ifactor2, steeramp, out, autopower):
     None : as the inputs out and autopower get overwritten.
 
     """
-    gridsize, numchannels = offsets.shape
+    gridsize, num_channels = offsets.shape
     num = out.shape[0]
     zero_constant = data.dtype.type(0.0)
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             out[n, gi] = zero_constant
             autopower[n, gi] = zero_constant
-            for mi in range(numchannels):
+            for mi in range(num_channels):
                 ind = (gi, mi)
                 r = (
                     data[offsets[ind] + n, mi] * (1.0 - ifactor2[ind]) + data[offsets[ind] + n + 1, mi] * ifactor2[ind]
@@ -99,7 +99,7 @@ def _delayandsum5(data, offsets, ifactor2, steeramp, out, autopower):
     None : as the inputs out and autopower get overwritten.
 
     """
-    num, gridsize, numchannels = offsets.shape
+    num, gridsize, num_channels = offsets.shape
     num = out.shape[0]
     # ZERO = data.dtype.type(0.)
     one_constant = data.dtype.type(1.0)
@@ -107,7 +107,7 @@ def _delayandsum5(data, offsets, ifactor2, steeramp, out, autopower):
         for gi in nb.prange(gridsize):
             out[n, gi] = 0
             autopower[n, gi] = 0
-            for mi in range(numchannels):
+            for mi in range(num_channels):
                 ind = offsets[n, gi, mi] + n
                 r = (
                     data[ind, mi] * (one_constant - ifactor2[n, gi, mi]) + data[ind + 1, mi] * ifactor2[n, gi, mi]
@@ -130,12 +130,12 @@ def _delayandsum5(data, offsets, ifactor2, steeramp, out, autopower):
     fastmath=True,
 )
 def _steer_I(rm, r0, amp):  # noqa: ARG001, N802
-    num, gridsize, numchannels = rm.shape
-    amp[0, 0, 0] = 1.0 / numchannels  # to get the same type for rm2 as for rm
+    num, gridsize, num_channels = rm.shape
+    amp[0, 0, 0] = 1.0 / num_channels  # to get the same type for rm2 as for rm
     nr = amp[0, 0, 0]
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 amp[n, gi, mi] = nr
 
 
@@ -149,13 +149,13 @@ def _steer_I(rm, r0, amp):  # noqa: ARG001, N802
     fastmath=True,
 )
 def _steer_II(rm, r0, amp):  # noqa: N802
-    num, gridsize, numchannels = rm.shape
-    amp[0, 0, 0] = 1.0 / numchannels  # to get the same type for rm2 as for rm
+    num, gridsize, num_channels = rm.shape
+    amp[0, 0, 0] = 1.0 / num_channels  # to get the same type for rm2 as for rm
     nr = amp[0, 0, 0]
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             rm2 = np.divide(nr, r0[n, gi])
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 amp[n, gi, mi] = rm[n, gi, mi] * rm2
 
 
@@ -169,16 +169,16 @@ def _steer_II(rm, r0, amp):  # noqa: N802
     fastmath=True,
 )
 def _steer_III(rm, r0, amp):  # noqa: N802
-    num, gridsize, numchannels = rm.shape
+    num, gridsize, num_channels = rm.shape
     rm20 = rm[0, 0, 0] - rm[0, 0, 0]  # to get the same type for rm2 as for rm
     rm1 = rm[0, 0, 0] / rm[0, 0, 0]
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             rm2 = rm20
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 rm2 += np.divide(rm1, np.square(rm[n, gi, mi]))
             rm2 *= r0[n, gi]
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 amp[n, gi, mi] = np.divide(rm1, rm[n, gi, mi] * rm2)
 
 
@@ -192,18 +192,18 @@ def _steer_III(rm, r0, amp):  # noqa: N802
     fastmath=True,
 )
 def _steer_IV(rm, r0, amp):  # noqa: ARG001, N802
-    num, gridsize, numchannels = rm.shape
-    amp[0, 0, 0] = np.sqrt(1.0 / numchannels)  # to get the same type for rm2 as for rm
+    num, gridsize, num_channels = rm.shape
+    amp[0, 0, 0] = np.sqrt(1.0 / num_channels)  # to get the same type for rm2 as for rm
     nr = amp[0, 0, 0]
     rm1 = rm[0, 0, 0] / rm[0, 0, 0]
     rm20 = rm[0, 0, 0] - rm[0, 0, 0]  # to get the same type for rm2 as for rm
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             rm2 = rm20
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 rm2 += np.divide(rm1, np.square(rm[n, gi, mi]))
             rm2 = np.sqrt(rm2)
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 amp[n, gi, mi] = np.divide(nr, rm[n, gi, mi] * rm2)
 
 
@@ -217,12 +217,12 @@ def _steer_IV(rm, r0, amp):  # noqa: ARG001, N802
     fastmath=True,
 )
 def _delays(rm, c, interp2, index):
-    num, gridsize, numchannels = rm.shape
+    num, gridsize, num_channels = rm.shape
     invc = 1 / c
     intt = index.dtype.type
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 delays = invc * rm[n, gi, mi]
                 index[n, gi, mi] = intt(delays)
                 interp2[n, gi, mi] = delays - nb.int64(delays)
@@ -238,10 +238,10 @@ def _delays(rm, c, interp2, index):
     fastmath=True,
 )
 def _modf(delays, interp2, index):
-    num, gridsize, numchannels = delays.shape
+    num, gridsize, num_channels = delays.shape
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
-            for mi in nb.prange(numchannels):
+            for mi in nb.prange(num_channels):
                 index[n, gi, mi] = int(delays[n, gi, mi])
                 interp2[n, gi, mi] = delays[n, gi, mi] - index[n, gi, mi]
 

acoular/tools/__init__.py

@@ -6,20 +6,16 @@
 .. autosummary::
     :toctree: generated/
 
-    aiaa
     helpers
     metrics
+    utils
 """
 
-from .aiaa import (
-    CsmAIAABenchmark,
-    MicAIAABenchmark,
-    TimeSamplesAIAABenchmark,
-    TriggerAIAABenchmark,
-)
 from .helpers import (
     bardata,
     barspectrum,
+    c_air,
     return_result,
 )
 from .metrics import MetricEvaluator
+from .utils import find_basename, get_file_basename

acoular/tools/helpers.py

@@ -6,31 +6,134 @@
 .. autosummary::
     :toctree: generated/
 
+    synthetic
     return_result
     barspectrum
     bardata
+    c_air
 """
 
+from warnings import warn
+
 from numpy import (
     array,
     concatenate,
+    isscalar,
     newaxis,
+    searchsorted,
+    sum,  # noqa A004
     where,
+    zeros_like,
 )
 from numpy.ma import masked_where
 
-from acoular.spectra import synthetic
+from acoular.tools.utils import mole_fraction_of_water_vapor
+
+
+def synthetic(data, freqs, f, num=3):
+    """Returns synthesized frequency band values of spectral data.
+
+    If used with :meth:`Beamformer.result()<acoular.fbeamform.BeamformerBase.result>`
+    and only one frequency band, the output is identical to the result of the intrinsic
+    :meth:`Beamformer.synthetic<acoular.fbeamform.BeamformerBase.synthetic>` method.
+    It can, however, also be used with the
+    :meth:`Beamformer.integrate<acoular.fbeamform.BeamformerBase.integrate>`
+    output and more frequency bands.
+
+    Parameters
+    ----------
+    data : array of floats
+        The spectral data (squared sound pressures in Pa^2) in an array with one value
+        per frequency line.
+        The number of entries must be identical to the number of
+        grid points.
+    freqs : array of floats
+        The frequencies that correspond to the input *data* (as yielded by
+        the :meth:`PowerSpectra.fftfreq<acoular.spectra.PowerSpectra.fftfreq>`
+        method).
+    f : float or list of floats
+        Band center frequency/frequencies for which to return the results.
+    num : integer
+        Controls the width of the frequency bands considered; defaults to
+        3 (third-octave band).
+
+        ===  =====================
+        num  frequency band width
+        ===  =====================
+        0    single frequency line
+        1    octave band
+        3    third-octave band
+        n    1/n-octave band
+        ===  =====================
+
+    Returns
+    -------
+    array of floats
+        Synthesized frequency band values of the beamforming result at
+        each grid point (the sum of all values that are contained in the band).
+        Note that the frequency resolution and therefore the bandwidth
+        represented by a single frequency line depends on
+        the :attr:`sampling frequency<acoular.base.SamplesGenerator.sample_freq>`
+        and used :attr:`FFT block size<acoular.spectra.PowerSpectra.block_size>`.
+
+    """
+    if isscalar(f):
+        f = (f,)
+    if num == 0:
+        # single frequency lines
+        res = []
+        for i in f:
+            ind = searchsorted(freqs, i)
+            if ind >= len(freqs):
+                warn(
+                    f'Queried frequency ({i:g} Hz) not in resolved frequency range. Returning zeros.',
+                    Warning,
+                    stacklevel=2,
+                )
+                h = zeros_like(data[0])
+            else:
+                if freqs[ind] != i:
+                    warn(
+                        f'Queried frequency ({i:g} Hz) not in set of '
+                        'discrete FFT sample frequencies. '
+                        f'Using frequency {freqs[ind]:g} Hz instead.',
+                        Warning,
+                        stacklevel=2,
+                    )
+                h = data[ind]
+            res += [h]
+    else:
+        # fractional octave bands
+        res = []
+        for i in f:
+            f1 = i * 2.0 ** (-0.5 / num)
+            f2 = i * 2.0 ** (+0.5 / num)
+            ind1 = searchsorted(freqs, f1)
+            ind2 = searchsorted(freqs, f2)
+            if ind1 == ind2:
+                warn(
+                    f'Queried frequency band ({f1:g} to {f2:g} Hz) does not '
+                    'include any discrete FFT sample frequencies. '
+                    'Returning zeros.',
+                    Warning,
+                    stacklevel=2,
+                )
+                h = zeros_like(data[0])
+            else:
+                h = sum(data[ind1:ind2], 0)
+            res += [h]
+    return array(res)
 
 
 def return_result(source, nmax=-1, num=128):
     """Collects the output from a
-    :meth:`SamplesGenerator.result()<acoular.tprocess.SamplesGenerator.result>`
+    :meth:`SamplesGenerator.result()<acoular.base.SamplesGenerator.result>`
     generator and returns an assembled array with all the data.
 
     Parameters
     ----------
     source: SamplesGenerator or derived object.
-        This is the  :class:`SamplesGenerator<acoular.tprocess.SamplesGenerator>` data source.
+        This is the  :class:`SamplesGenerator<acoular.base.SamplesGenerator>` data source.
     nmax: integer
         With this parameter, a maximum number of output samples can be set
         (first dimension of array). If set to -1 (default), samples are
@@ -41,7 +144,7 @@ def return_result(source, nmax=-1, num=128):
 
     Returns
     -------
-    array of floats (number of samples, source.numchannels)
+    array of floats (number of samples, source.num_channels)
         Array that holds all the data.
 
     """
@@ -187,3 +290,114 @@ def bardata(data, fc, num=3, bar=True, xoffset=0.0, masked=-360):
     if masked > -360:
         plist = masked_where(plist <= masked, plist)
     return (flulist, plist)
+
+
+def c_air(t, h, p=101325, co2=0.04):
+    r"""
+    Calculates the speed of sound in air according to Eq.(15) in :cite:`Cramer1993`.
+
+    This function calculates the speed of sound in air based on temperature, pressure, relative
+    humidity, and CO\ :sub:`2` concentration. To calculate the mole fraction of water vapor in
+    the air, :meth:`~acoular.tools.utils.mole_fraction_of_water_vapor` uses the more recent work
+    of :cite:`Davis1992` to obtain the saturation vapor pressure.
+
+    The function is only valid over the temperature range from 0°C to 30°C (273.15 K to 303.15 K),
+    for the pressure range 60 to 110 kPa, a water vapor mole fraction up to 0.06, and CO2
+    concentrations up to 1%.
+
+    Parameters
+    ----------
+    t : float
+        Temperature in (°C).
+    h : float
+        Humidity in percent (0 to 100).
+    p : float
+        Atmospheric pressure in Pa (default is the standard pressure 101325 Pa).
+    co2 : float
+        Carbon dioxide concentration in percent (default is 0.04%).
+
+    Returns
+    -------
+    float
+        Speed of sound in air in m/s.
+
+    Raises
+    ------
+    ValueError
+        If the temperature is out of range (0°C to 30°C), the pressure is out of range
+        (60 kPa to 110 kPa), the water vapor mole fraction is out of range (up to 0.06),
+        or the CO\ :sub:`2` concentration is out of range (up to 1%).
+
+    Notes
+    -----
+    The speed of sound in air is calculated using the following equation:
+
+    .. math::
+
+        \begin{aligned}
+        c(t, p, x_w, c_{CO_2}) = & a_0 + a_1 t + a_2 t^2 + \left(a_3 + a_4 t + a_5 t^2\right) x_w \\
+        & + \left(a_6 + a_7 t + a_8 t^2\right) p + \left(a_9 + a_{10} t + a_{11} t^2\right) x_c \\
+        & + a_{12} x_w^2 + a_{13} p^2 + a_{14} x_c^2 + a_{15} x_w p x_c
+        \end{aligned}
+
+    where:
+        - :math:`t` is the temperature in c.
+        - :math:`x_w` is the water vapor mole fraction.
+        - :math:`x_c` is the carbon dioxide mole fraction (:math:`x_c = c_{CO_2} / 100`).
+        - :math:`p` is the atmospheric pressure in Pa.
+
+    Examples
+    --------
+    Code for reproducing Fig.1 from :cite:`Cramer1993`
+
+    .. plot:: plots/c_air.py
+    """
+    if t < 0 or t > 30:
+        msg = 'Temperature out of range (0°C to 30°C)'
+        raise ValueError(msg)
+    if p < 60000 or p > 110000:
+        msg = 'Pressure out of range (60 kPa to 110 kPa)'
+        raise ValueError(msg)
+
+    # Calculate water vapor mole fraction
+    x_w = mole_fraction_of_water_vapor(h / 100, t + 273.15, p)
+    if x_w > 0.06:
+        msg = 'Water vapor mole fraction out of range (up to 0.06)'
+        raise ValueError(msg)
+
+    if co2 > 1.0:
+        msg = 'CO2 concentration out of range (up to 1%)'
+        raise ValueError(msg)
+
+    # Convert CO2 concentration from percent to mole fraction
+    x_c = co2 / 100
+
+    # Coefficients from Eq.(15)
+    a0 = 331.5024
+    a1 = 0.603055
+    a2 = -0.000528
+    a3 = 51.471935
+    a4 = 0.1495874
+    a5 = -0.000782
+    a6 = -1.82 * 10**-7
+    a7 = 3.73 * 10**-8
+    a8 = -2.93 * 10**-10
+    a9 = -85.20931
+    a10 = -0.228525
+    a11 = 5.91 * 10**-5
+    a12 = -2.835149
+    a13 = -2.15 * 10**-13
+    a14 = 29.179762
+    a15 = 0.000486
+    return (
+        a0
+        + a1 * t
+        + a2 * t**2
+        + (a3 + a4 * t + a5 * t**2) * x_w
+        + (a6 + a7 * t + a8 * t**2) * p
+        + (a9 + a10 * t + a11 * t**2) * x_c
+        + a12 * x_w**2
+        + a13 * p**2
+        + a14 * x_c**2
+        + a15 * x_w * p * x_c
+    )

acoular/tools/metrics.py

@@ -18,17 +18,17 @@ from numpy import (
     ones,
 )
 from scipy.spatial.distance import cdist
-from traits.api import Bool, CArray, HasPrivateTraits, Instance, Property
+from traits.api import Bool, CArray, HasStrictTraits, Instance, Property
 
 from acoular.fbeamform import L_p, integrate
 from acoular.grids import CircSector, Grid
 
 
-class MetricEvaluator(HasPrivateTraits):
+class MetricEvaluator(HasStrictTraits):
     """Evaluate the reconstruction performance of source mapping methods.
 
     This class can be used to calculate the following performance metrics
-    according to Herold and Sarradj (2017):
+    according :cite:`Herold2017`:
     * Specific level error
     * Overall level error
     * Inverse level error
@@ -84,7 +84,7 @@ class MetricEvaluator(HasPrivateTraits):
         ns = self.target_data.shape[1]
         radii = ones(ns) * self.sector.r
         if self.adaptive_sector_size:
-            locs = self.target_grid.gpos.T
+            locs = self.target_grid.pos.T
             intersrcdist = cdist(locs, locs)
             intersrcdist[intersrcdist == 0] = inf
             intersrcdist = intersrcdist.min(0) / 2
@@ -97,7 +97,7 @@ class MetricEvaluator(HasPrivateTraits):
         ns = self.target_data.shape[1]
         sectors = []
         for i in range(ns):
-            loc = self.target_grid.gpos[:, i]
+            loc = self.target_grid.pos[:, i]
             sector = copy(self.sector)
             sector.r = r[i]
             sector.x = loc[0]

acoular/tools/utils.py

@@ -0,0 +1,116 @@
+"""Utility classes intended for internal use in Acoular.
+
+.. autosummary::
+    :toctree: generated/
+
+    get_file_basename
+    find_basename
+    mole_fraction_of_water_vapor
+"""
+
+from pathlib import Path
+
+import numpy as np
+
+
+def get_file_basename(file, alternative_basename='void'):
+    """Return the basename of the file.
+
+    Parameters
+    ----------
+    file : str
+        File path.
+
+    Returns
+    -------
+    str
+        Basename of the file.
+    """
+    basename = Path(file).stem
+    return basename if basename else alternative_basename
+
+
+def find_basename(source, alternative_basename='void'):
+    """Return the basename of the original source.
+
+    Traverses the source chain of the object and returns the basename of the original source.
+    If the source object does not have a basename, uses the alternative basename.
+
+    Parameters
+    ----------
+    source : instance
+        :class:`~acoular.base.Generator` derived object
+    alternative_basename : str
+        Alternative basename to use if the source object does not have a basename.
+
+
+    Returns
+    -------
+    str
+        Basename of the original source.
+    """
+    while source:
+        basename = getattr(source, 'basename', None)
+        if basename is not None:
+            return basename
+        source = getattr(source, 'source', None)
+    return alternative_basename
+
+
+def mole_fraction_of_water_vapor(h, t, p=101325):
+    r"""Mole fraction of water vapor in the air for real gases.
+
+    Calculates the mole fraction of water vapor in air from the relative humidity,
+    based on the equations provided in the appendix of :cite:`Cramer1993` and
+    the enhancement factors from :cite:`Davis1992`.
+
+    Parameters
+    ----------
+    h : float
+        Relative humidity as a fraction [0,1].
+    t : float
+        Thermodynamic temperature in K.
+    p : float
+        Atmospheric pressure in Pa (default is the standard pressure 101325 Pa).
+
+    Returns
+    -------
+    float
+        Mole fraction of water vapor.
+
+    Notes
+    -----
+    The mole fraction is calculated as:
+
+    .. math::
+        x_w = h \cdot f \cdot \frac{p_{sv}}{p},
+
+    where:
+      - :math:`h` is the relative humidity as a fraction [0,1].
+      - :math:`f` is the enhancement factor:
+
+        .. math::
+            f = 1.00062 + 3.14 \times 10^{-8} \cdot p + 5.6 \times 10^{-7} \cdot t^2.
+
+      - :math:`p_{sv}` is the saturation vapor pressure of water vapor in air:
+
+        .. math::
+            p_{sv} = \exp(A \cdot t^2 + B \cdot t + C + \frac{D}{t}),
+
+        with the updated coefficients from :cite:`Davis1992`:
+
+        .. math::
+            A = 1.2378847 \times 10^{-5}, \\
+            B = -1.9121316 \times 10^{-2}, \\
+            C = 33.93711047, \\
+            D = -6.3431645 \times 10^3.
+
+    """
+    f = 1.00062 + 3.14 * 10 ** (-8) * p + 5.6 * 10 ** (-7) * t**2  # enhancement factor
+    # Saturation vapor pressure using updated coefficients from Davis (1992)
+    A = 1.2378847 * 10 ** (-5)  # noqa: N806
+    B = -1.9121316 * 10 ** (-2)  # noqa: N806
+    C = 33.93711047  # noqa: N806
+    D = -6.3431645 * 10**3  # noqa: N806
+    p_sv = np.exp(A * t**2 + B * t + C + D / t)  # p_sv in Pa
+    return h * f * p_sv / p