acoular 25.3.post1__py3-none-any.whl → 25.7__py3-none-any.whl

acoular/internal.py

@@ -2,10 +2,13 @@
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
 
+"""Implements a digest function for caching of traits based on a unique identifier."""
+
 from hashlib import md5
 
 
 def digest(obj, name='digest'):
+    """Generate a unique digest for the given object based on its traits."""
     str_ = [str(obj.__class__).encode('UTF-8')]
     for do_ in obj.trait(name).depends_on:
         vobj = obj
@@ -19,6 +22,7 @@ def digest(obj, name='digest'):
 
 
 def ldigest(obj_list):
+    """Generate a unique digest for a list of objects based on their traits."""
     str_ = []
     for i in obj_list:
         str_.append(str(i.digest).encode('UTF-8'))

acoular/microphones.py

@@ -22,6 +22,7 @@ from traits.api import (
     HasStrictTraits,
     List,
     Property,
+    Union,
     cached_property,
     on_trait_change,
 )
@@ -31,7 +32,9 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'])
+@deprecated_alias(
+    {'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'], removal_version='25.10'
+)
 class MicGeom(HasStrictTraits):
     """
     Provide the geometric arrangement of microphones in an array.
@@ -46,6 +49,17 @@ class MicGeom(HasStrictTraits):
       attribute is updated.
     - Small numerical values in the computed :attr:`center` are set to zero for numerical stability.
 
+    .. _units_note_microphones:
+
+    Unit System
+    -----------
+    The source code is agnostic to the unit of length. The microphone positions' coordinates are
+    assumed to be in meters. This is consistent with the standard
+    :class:`~acoular.environments.Environment` class which uses the speed of sound at 20°C at sea
+    level under standard atmosphere pressure in m/s. If the microphone positions' coordinates are
+    provided in a unit other than meter, it is advisable to change the
+    :attr:`~acoular.environments.Environment.c` attribute to match the given unit.
+
     Examples
     --------
     To set a microphone geomerty for ``n`` programmatically, first a ``(3,n)`` array is needed. In
@@ -128,15 +142,17 @@ class MicGeom(HasStrictTraits):
 
     #: Path to the XML file containing microphone positions. The XML file should have elements with
     #: the tag ``pos`` and attributes ``Name``, ``x``, ``y``, and ``z``.
-    file = File(filter=['*.xml'], exists=True, desc='name of the xml file to import')
+    file = Union(None, File(filter=['*.xml'], exists=True), desc='name of the xml file to import')
 
     #: Array containing the ``x, y, z`` positions of all microphones, including invalid ones, shape
     #: ``(3,`` :attr:`num_mics` ``)``. This is set automatically when :attr:`file` changes or
-    #: explicitly by assigning an array of floats.
+    #: explicitly by assigning an array of floats. All coordinates are in meters by default (see
+    #: :ref:`notes <units_note_micophones>`).
     pos_total = CArray(dtype=float, shape=(3, None), desc='x, y, z position of all microphones')
 
     #: Array containing the ``x, y, z`` positions of valid microphones (i.e., excluding those in
     #: :attr:`invalid_channels`), shape ``(3,`` :attr:`num_mics` ``)``. (read-only)
+    #: All coordinates are in meters by default (see :ref:`notes <units_note>`).
     pos = Property(depends_on=['pos_total', 'invalid_channels'], desc='x, y, z position of used microphones')
 
     #: List of indices indicating microphones to be excluded from calculations and results.
@@ -250,6 +266,8 @@ class MicGeom(HasStrictTraits):
           index of the microphone.
         - This method only exports the positions of the valid microphones (those not listed in
           :attr:`invalid_channels`).
+        - All coordinates (x, y, z) are exported in meters by default (see
+          :ref:`notes <units_note_micophones>`).
         """
         filepath = Path(filename)
         basename = filepath.stem

acoular/process.py

@@ -10,8 +10,6 @@ General purpose blockwise processing methods independent of the domain (time or
     Average
     Cache
     SampleSplitter
-    TimeAverage
-    TimeCache
     SamplesBuffer
 """
 
@@ -65,7 +63,9 @@ class LockedGenerator:
             return self.it.__next__()
 
 
-@deprecated_alias({'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'])
+@deprecated_alias(
+    {'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'], removal_version='25.10'
+)
 class Average(InOut):
     """
     Calculate the average across consecutive time samples or frequency snapshots.
@@ -675,48 +675,6 @@ class SampleSplitter(InOut):
             raise OSError(msg)
 
 
-class TimeAverage(Average):
-    """
-    Calculate the average of the signal.
-
-    .. deprecated:: 24.10
-        The use of :class:`~acoular.process.TimeAverage` is deprecated
-        and will be removed in Acoular version 25.07.
-        Please use :class:`~acoular.process.Average` instead for future compatibility.
-
-    Alias for :class:`~acoular.process.Average`.
-    """
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        warn(
-            'Using TimeAverage is deprecated and will be removed in Acoular version 25.07. Use Average instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
-class TimeCache(Cache):
-    """
-    Cache source signals in cache file.
-
-    .. deprecated:: 24.10
-        The use of :class:`~acoular.process.TimeCache` is deprecated
-        and will be removed in Acoular version 25.07.
-        Please use :class:`~acoular.process.Cache` instead for future compatibility.
-
-    Alias for :class:`~acoular.process.Cache`.
-    """
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        warn(
-            'Using TimeCache is deprecated and will be removed in Acoular version 25.07. Use Cache instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
 class SamplesBuffer(InOut):
     """
     Handle buffering of samples from a source.

acoular/sdinput.py

@@ -21,7 +21,10 @@ if config.have_sounddevice:
     import sounddevice as sd
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples', 'collectsamples': 'collect_samples'})
+@deprecated_alias(
+    {'numchannels': 'num_channels', 'numsamples': 'num_samples', 'collectsamples': 'collect_samples'},
+    removal_version='25.10',
+)
 class SoundDeviceSamplesGenerator(SamplesGenerator):
     """Controller for sound card hardware using sounddevice library.
 
@@ -87,15 +90,20 @@ class SoundDeviceSamplesGenerator(SamplesGenerator):
         self._sample_freq = f
 
     def device_properties(self):
-        """Returns
+        """
+        Display the properties of the sounddevice input device.
+
+        Returns
         -------
         Dictionary of device properties according to sounddevice
         """
         return sd.query_devices(self.device)
 
     def result(self, num):
-        """Python generator that yields the output block-wise. Use at least a
-        block-size of one ring cache block.
+        """
+        Python generator that yields the output block-wise.
+
+        Use at least a block-size of one ring cache block.
 
         Parameters
         ----------

acoular/signals.py

@@ -43,7 +43,7 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'numsamples': 'num_samples'})
+@deprecated_alias({'numsamples': 'num_samples'}, removal_version='25.10')
 class SignalGenerator(ABCHasStrictTraits):
     """
     ABC for a simple one-channel signal generator.
@@ -556,7 +556,7 @@ class SineGenerator(PeriodicSignalGenerator):
         return self.amplitude * sin(2 * pi * self.freq * t + self.phase)
 
 
-@deprecated_alias({'rms': 'amplitude'})
+@deprecated_alias({'rms': 'amplitude'}, removal_version='25.10')
 class GenericSignalGenerator(SignalGenerator):
     """
     Generate signals from a :class:`~acoular.base.SamplesGenerator` or derived object.

acoular/sources.py

@@ -45,6 +45,7 @@ from numpy import (
     mod,
     newaxis,
     ones,
+    ones_like,
     pi,
     real,
     repeat,
@@ -317,7 +318,7 @@ def get_modes(lOrder, direction, mpos, sourceposition=None):  # noqa: N803
     return modes
 
 
-@deprecated_alias({'name': 'file'})
+@deprecated_alias({'name': 'file'}, removal_version='25.10')
 class TimeSamples(SamplesGenerator):
     """
     Container for processing time data in ``*.h5`` or NumPy array format.
@@ -369,7 +370,7 @@ class TimeSamples(SamplesGenerator):
     """
 
     #: Full path to the ``.h5`` file containing time-domain data.
-    file = File(filter=['*.h5'], exists=True, desc='name of data file')
+    file = Union(None, File(filter=['*.h5'], exists=True), desc='name of data file')
 
     #: Basename of the ``.h5`` file, set automatically from the :attr:`file` attribute.
     basename = Property(depends_on=['file'], desc='basename of data file')
@@ -746,7 +747,7 @@ class MaskedTimeSamples(TimeSamples):
             i += num
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class PointSource(SamplesGenerator):
     """
     Define a fixed point source emitting a signal, intended for simulations.
@@ -1164,46 +1165,48 @@ class MovingPointSource(PointSource):
         # from the end of the calculated signal.
 
         signal = self.signal.usignal(self.up)
-        out = empty((num, self.num_channels))
         # shortcuts and initial values
-        m = self.mics
-        t = self.start * ones(m.num_mics)
-        i = 0
+        num_mics = self.num_channels
+        mpos = self.mics.pos[:, :, newaxis]
+        t = self.start + ones(num_mics)[:, newaxis] * arange(num) / self.sample_freq
         epslim = 0.1 / self.up / self.sample_freq
         c0 = self.env.c
         tr = self.trajectory
         n = self.num_samples
-        while n:
-            n -= 1
-            eps = ones(m.num_mics)
+        while n > 0:
+            eps = ones_like(t)  # init discrepancy in time
             te = t.copy()  # init emission time = receiving time
             j = 0
             # Newton-Rhapson iteration
             while abs(eps).max() > epslim and j < 100:
-                loc = array(tr.location(te))
-                rm = loc - m.pos  # distance vectors to microphones
+                loc = array(tr.location(te.flatten())).reshape((3, num_mics, -1))
+                rm = loc - mpos  # distance vectors to microphones
                 rm = sqrt((rm * rm).sum(0))  # absolute distance
                 loc /= sqrt((loc * loc).sum(0))  # distance unit vector
-                der = array(tr.location(te, der=1))
+                der = array(tr.location(te.flatten(), der=1)).reshape((3, num_mics, -1))
                 Mr = (der * loc).sum(0) / c0  # radial Mach number
-                eps = (te + rm / c0 - t) / (1 + Mr)  # discrepancy in time
+                eps[:] = (te + rm / c0 - t) / (1 + Mr)  # discrepancy in time
                 te -= eps
                 j += 1  # iteration count
-            t += 1.0 / self.sample_freq
+            t += num / self.sample_freq
             # emission time relative to start time
             ind = (te - self.start_t + self.start) * self.sample_freq
             if self.conv_amp:
                 rm *= (1 - Mr) ** 2
             try:
-                out[i] = signal[array(0.5 + ind * self.up, dtype=int64)] / rm
-                i += 1
-                if i == num:
-                    yield out
-                    i = 0
-            except IndexError:  # if no more samples available from the source
+                ind = array(0.5 + ind * self.up, dtype=int64)
+                out = (signal[ind] / rm).T
+                yield out[:n]
+            except IndexError:  # last incomplete frame
+                signal_length = signal.shape[0]
+                # Filter ind to exclude columns containing values greater than signal_length
+                mask = (ind < signal_length).all(axis=0)
+                out = (signal[ind[:, mask]] / rm[:, mask]).T
+                # If out is not empty, yield it
+                if out.size > 0:
+                    yield out[:n]
                 break
-        if i > 0:  # if there are still samples to yield
-            yield out[:i]
+            n -= num
 
 
 class PointSourceDipole(PointSource):
@@ -1947,7 +1950,7 @@ class MovingLineSource(LineSource, MovingPointSource):
         yield out[:i]
 
 
-@deprecated_alias({'numchannels': 'num_channels'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels'}, read_only=True, removal_version='25.10')
 class UncorrelatedNoiseSource(SamplesGenerator):
     """
     Simulate uncorrelated white or pink noise signals at multiple channels.
@@ -2111,7 +2114,7 @@ class UncorrelatedNoiseSource(SamplesGenerator):
                 return
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class SourceMixer(SamplesGenerator):
     """
     Combine signals from multiple sources by mixing their outputs.

acoular/spectra.py

@@ -12,7 +12,6 @@
 """
 
 from abc import abstractmethod
-from warnings import warn
 
 from numpy import (
     arange,
@@ -62,8 +61,9 @@ from .internal import digest
 from .tools.utils import find_basename
 
 
-@deprecated_alias({'numchannels': 'num_channels'}, read_only=True)
-@deprecated_alias({'time_data': 'source'}, read_only=False)
+@deprecated_alias(
+    {'numchannels': 'num_channels', 'time_data': 'source'}, read_only=['numchannels'], removal_version='25.10'
+)
 class BaseSpectra(ABCHasStrictTraits):
     """
     Base class for handling spectral data in Acoular.
@@ -298,9 +298,10 @@ class PowerSpectra(BaseSpectra):
         return None
 
     def _set_freq_range(self, freq_range):  # by setting this the user sets _freqlc and _freqhc
-        self._index_set_last = False
-        self._freqlc = freq_range[0]
-        self._freqhc = freq_range[1]
+        if freq_range is not None:
+            self._index_set_last = False
+            self._freqlc = freq_range[0]
+            self._freqhc = freq_range[1]
 
     @property_depends_on(['source.sample_freq', 'block_size', '_ind_low', '_freqlc'])
     def _get_ind_low(self):
@@ -309,7 +310,7 @@ class PowerSpectra(BaseSpectra):
             if self._index_set_last:
                 return min(self._ind_low, fftfreq.shape[0] - 1)
             return searchsorted(fftfreq[:-1], self._freqlc)
-        return None
+        return 0
 
     @property_depends_on(['source.sample_freq', 'block_size', '_ind_high', '_freqhc'])
     def _get_ind_high(self):
@@ -631,7 +632,7 @@ class PowerSpectraImport(PowerSpectra):
 
     #: The frequencies included in the CSM in ascending order. Accepts list, array, or a single
     #: float value.
-    frequencies = Union(CArray, Float, desc='frequencies included in the cross-spectral matrix')
+    frequencies = Union(None, CArray, Float, desc='frequencies included in the cross-spectral matrix')
 
     #: Number of time data channels, inferred from the shape of the CSM.
     num_channels = Property(depends_on=['digest'])
@@ -670,7 +671,7 @@ class PowerSpectraImport(PowerSpectra):
     basename = Property(depends_on=['digest'], desc='basename for cache file')
 
     # Shadow trait for storing the CSM, for internal use only.
-    _csm = CArray()
+    _csm = Union(None, CArray(shape=(None, None, None)), desc='cross spectral matrix')
 
     # Checksum for the CSM to trigger digest calculation, for internal use only.
     _csmsum = Float()
@@ -689,12 +690,13 @@ class PowerSpectraImport(PowerSpectra):
         return self._csm
 
     def _set_csm(self, csm):
-        if (len(csm.shape) != 3) or (csm.shape[1] != csm.shape[2]):
-            msg = 'The cross spectral matrix must have the following shape: \
-            (number of frequencies, num_channels, num_channels)!'
-            raise ValueError(msg)
-        self._csmsum = real(self._csm).sum() + (imag(self._csm) ** 2).sum()  # to trigger new digest creation
-        self._csm = csm
+        if csm is not None:
+            if csm.shape[1] != csm.shape[2]:
+                msg = 'The cross spectral matrix must have the following shape: \
+                (number of frequencies, num_channels, num_channels)!'
+                raise ValueError(msg)
+            self._csm = csm
+            self._csmsum = real(self._csm).sum() + (imag(self._csm) ** 2).sum()  # to trigger new digest creation
 
     @property_depends_on(['digest'])
     def _get_eva(self):
@@ -720,6 +722,4 @@ class PowerSpectraImport(PowerSpectra):
             return array([self.frequencies])
         if isinstance(self.frequencies, ndarray):
             return self.frequencies
-        if self.frequencies is None:
-            warn('No frequencies defined for PowerSpectraImport object!', stacklevel=1)
         return self.frequencies

acoular/tbeamform.py

@@ -174,6 +174,9 @@ class BeamformerTime(TimeOut):
             p_res *= weights
             if p_res.shape[0] < buffer.result_num:  # last block shorter
                 num = p_res.shape[0] - max_sample_delay
+                # exit loop if there is not enough data left to be processed
+                if num <= 0:
+                    break
                 n_index = arange(0, num + 1)[:, newaxis]
             # init step
             Phi, autopow = self._delay_and_sum(num, p_res, d_interp2, d_index, amp)

acoular/tools/helpers.py

@@ -11,8 +11,10 @@
     barspectrum
     bardata
     c_air
+    get_data_file
 """
 
+from pathlib import Path
 from warnings import warn
 
 from numpy import (
@@ -401,3 +403,28 @@ def c_air(t, h, p=101325, co2=0.04):
         + a14 * x_c**2
         + a15 * x_w * p * x_c
     )
+
+
+def get_data_file(file):
+    """
+    Ensures a file is available locally.
+
+    If the file does not exist in ``'../data/'`` or the current directory,
+    it is downloaded from the Acoular GitHub repository.
+
+    Returns
+    -------
+    :class:`pathlib.Path`
+        Path to the file.
+    """
+    data_file = Path('../data') / file
+    if not data_file.exists():
+        data_file = Path().cwd() / file
+        if not data_file.exists():
+            import urllib.request
+
+            url = 'https://github.com/acoular/acoular/raw/master/examples/data/' + file
+            urllib.request.urlretrieve(url, data_file)
+        print(f'Calibration file location: {data_file}')
+
+    return data_file

acoular/tools/utils.py

@@ -26,8 +26,7 @@ def get_file_basename(file, alternative_basename='void'):
     str
         Basename of the file.
     """
-    basename = Path(file).stem
-    return basename if basename else alternative_basename
+    return Path(file).stem if file else alternative_basename
 
 
 def find_basename(source, alternative_basename='void'):