acoular 24.5__py3-none-any.whl → 24.10__py3-none-any.whl

acoular/tfastfuncs.py

@@ -6,9 +6,6 @@
 import numba as nb
 import numpy as np
 
-cachedOption = True  # if True: saves the numba func as compiled func in sub directory
-fastOption = True  # fastmath options
-
 
 @nb.njit(
     [
@@ -46,11 +43,11 @@ def _delayandsum4(data, offsets, ifactor2, steeramp, out, autopower):
     """
     gridsize, numchannels = offsets.shape
     num = out.shape[0]
-    ZERO = data.dtype.type(0.0)
+    zero_constant = data.dtype.type(0.0)
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
-            out[n, gi] = ZERO
-            autopower[n, gi] = ZERO
+            out[n, gi] = zero_constant
+            autopower[n, gi] = zero_constant
             for mi in range(numchannels):
                 ind = (gi, mi)
                 r = (
@@ -105,14 +102,16 @@ def _delayandsum5(data, offsets, ifactor2, steeramp, out, autopower):
     num, gridsize, numchannels = offsets.shape
     num = out.shape[0]
     # ZERO = data.dtype.type(0.)
-    ONE = data.dtype.type(1.0)
+    one_constant = data.dtype.type(1.0)
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             out[n, gi] = 0
             autopower[n, gi] = 0
             for mi in range(numchannels):
                 ind = offsets[n, gi, mi] + n
-                r = (data[ind, mi] * (ONE - ifactor2[n, gi, mi]) + data[ind + 1, mi] * ifactor2[n, gi, mi]) * steeramp[
+                r = (
+                    data[ind, mi] * (one_constant - ifactor2[n, gi, mi]) + data[ind + 1, mi] * ifactor2[n, gi, mi]
+                ) * steeramp[
                     n,
                     gi,
                     mi,
@@ -130,14 +129,14 @@ def _delayandsum5(data, offsets, ifactor2, steeramp, out, autopower):
     parallel=True,
     fastmath=True,
 )
-def _steer_I(rm, r0, amp):  # noqa: ARG001
+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
-    Nr = amp[0, 0, 0]
+    nr = amp[0, 0, 0]
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
             for mi in nb.prange(numchannels):
-                amp[n, gi, mi] = Nr
+                amp[n, gi, mi] = nr
 
 
 @nb.njit(
@@ -149,13 +148,13 @@ def _steer_I(rm, r0, amp):  # noqa: ARG001
     parallel=True,
     fastmath=True,
 )
-def _steer_II(rm, r0, amp):
+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
-    Nr = amp[0, 0, 0]
+    nr = amp[0, 0, 0]
     for n in nb.prange(num):
         for gi in nb.prange(gridsize):
-            rm2 = np.divide(Nr, r0[n, gi])
+            rm2 = np.divide(nr, r0[n, gi])
             for mi in nb.prange(numchannels):
                 amp[n, gi, mi] = rm[n, gi, mi] * rm2
 
@@ -169,7 +168,7 @@ def _steer_II(rm, r0, amp):
     parallel=True,
     fastmath=True,
 )
-def _steer_III(rm, r0, amp):
+def _steer_III(rm, r0, amp):  # noqa: N802
     num, gridsize, numchannels = 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]
@@ -192,10 +191,10 @@ def _steer_III(rm, r0, amp):
     parallel=True,
     fastmath=True,
 )
-def _steer_IV(rm, r0, amp):  # noqa: ARG001
+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
-    Nr = amp[0, 0, 0]
+    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):
@@ -205,7 +204,7 @@ def _steer_IV(rm, r0, amp):  # noqa: ARG001
                 rm2 += np.divide(rm1, np.square(rm[n, gi, mi]))
             rm2 = np.sqrt(rm2)
             for mi in nb.prange(numchannels):
-                amp[n, gi, mi] = np.divide(Nr, rm[n, gi, mi] * rm2)
+                amp[n, gi, mi] = np.divide(nr, rm[n, gi, mi] * rm2)
 
 
 @nb.njit(

acoular/tools/__init__.py

@@ -9,6 +9,7 @@
     aiaa
     helpers
     metrics
+    utils
 """
 
 from .aiaa import (
@@ -23,3 +24,4 @@ from .helpers import (
     return_result,
 )
 from .metrics import MetricEvaluator
+from .utils import SamplesBuffer

acoular/tools/aiaa.py

@@ -12,8 +12,8 @@ the framework.
 
 Examples
 --------
->>> micgeom = MicAIAABenchmark(name='some_benchmarkdata.h5')
->>> timedata = TimeSamplesAIAABenchmark(name='some_benchmarkdata.h5')
+>>> micgeom = MicAIAABenchmark(name='some_benchmarkdata.h5')  # doctest: +SKIP
+>>> timedata = TimeSamplesAIAABenchmark(name='some_benchmarkdata.h5')  # doctest: +SKIP
 
 
 .. autosummary::
@@ -25,6 +25,7 @@ Examples
     MicAIAABenchmark
 """
 
+import contextlib
 from os import path
 
 from numpy import array
@@ -53,13 +54,13 @@ class TimeSamplesAIAABenchmark(TimeSamples):
     objects.
     """
 
-    def load_timedata(self):
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('MicrophoneData/microphoneDataPa')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sampleRateHz')
         (self.numsamples, self.numchannels) = self.data.shape
 
-    def load_metadata(self):
+    def _load_metadata(self):
         """Loads metadata from .h5 file. Only for internal use."""
         self.metadata = {}
         if '/MetaData' in self.h5f:
@@ -75,7 +76,7 @@ class TriggerAIAABenchmark(TimeSamplesAIAABenchmark):
     and and provides information about this data.
     """
 
-    def load_timedata(self):
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('TachoData/tachoDataV')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sampleRateHz')
@@ -118,10 +119,8 @@ class CsmAIAABenchmark(PowerSpectraImport):
             # no file there
             raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
-            try:
+            with contextlib.suppress(OSError):
                 self.h5f.close()
-            except OSError:
-                pass
         file = _get_h5file_class()
         self.h5f = file(self.name)
 

acoular/tools/helpers.py

@@ -24,13 +24,13 @@ from acoular.spectra import synthetic
 
 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

acoular/tools/metrics.py

@@ -28,7 +28,7 @@ class MetricEvaluator(HasPrivateTraits):
     """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

acoular/tools/utils.py

@@ -0,0 +1,210 @@
+"""Utility classes intended for internal use in Acoular.
+
+.. autosummary::
+    :toctree: generated/
+
+    SamplesBuffer
+"""
+
+import numpy as np
+from traits.api import Any, Array, Bool, Enum, Int, Property, Union
+
+from acoular.process import InOut
+
+
+class SamplesBuffer(InOut):
+    """Handles buffering of samples from a source.
+
+    This class is used to buffer samples from a source and provide them in blocks
+    of a specified size. There are several usecases for this class, as demonstrated in
+    the following.
+
+    Examples
+    --------
+    Let us assume we want to draw blocks of 16 samples from our source, but we want to make sure
+    that we always have twice the number of samples in the buffer. We can achieve this simple behaviour
+    by using the following code:
+
+    >>> import acoular as ac
+    >>> import numpy as np
+    >>> # create a white noise source with 512 samples
+    >>> source = ac.TimeSamples(
+    ...     data=ac.WNoiseGenerator(
+    ...         sample_freq=64,
+    ...         numsamples=512,
+    ...     ).signal()[:, np.newaxis],
+    ...     sample_freq=64,
+    ... )
+    >>> # create a buffer with a size of 32 samples
+    >>> buffer = ac.tools.SamplesBuffer(source=source, length=32)
+    >>> # get the first block of 16 samples
+    >>> block = next(buffer.result(num=16))
+    >>> np.testing.assert_array_equal(block, source.data[:16])
+
+    Here, on the first call to the result method, the buffer will fill up by collecting blocks with same size
+    from the source. The buffer will then return the first block of 16 samples. On the next call to the result
+    method, the buffer will be filled again and returns the next block of 16 samples.
+
+    In some cases, we might want to draw a different number of samples from the source than we want to return.
+    This can be achieved by setting the `source_num` trait of the buffer. A special case is the return of a variable
+    number of samples. This is the case, for example, in the class :class:`~acoular.tbeamform.BeamformerTimeTraj`,
+    in which a different number of time samples is required from the buffer for further delay-and-sum processing
+    depending on the expected delay, which can be vary for moving sources. At the same time, however, only 'num'
+    samples should be written to and removed from the buffer. This behavior can be achieved by setting the
+    `shift_index_by` trait to 'num' and by setting the `result_num` trait to the number of samples that should be
+    returned by the result function.
+
+    >>> buffer = ac.tools.SamplesBuffer(source=source, length=32, result_num=20, shift_index_by='num')
+    >>> block_sizes = []
+    >>> block_sizes.append(
+    ...     next(buffer.result(num=16)).shape[0]
+    ... )  # this time, the buffer will return 20 samples, but the buffer will only forget the first 16 samples
+    >>> buffer.result_num = 24
+    >>> block_sizes.append(
+    ...     next(buffer.result(num=16)).shape[0]
+    ... )  # this time, the buffer will return 24 samples, but the buffer will only forget the first 16 samples
+    >>> np.testing.assert_array_equal(block_sizes, [20, 24])
+    """
+
+    #: number of samples that fit in the buffer
+    length = Int(desc='number of samples that fit in the buffer')
+
+    #: number of samples per block to obtain from the source. If 'None', use 'num' argument of result method
+    source_num = Union(
+        None,
+        Int(),
+        default_value=None,
+        desc='number of samples to return from the source. If "None", use "num" argument of result method',
+    )
+
+    #: number of samples to return from the buffer. If 'None', use 'num' argument of result method
+    result_num = Union(
+        None,
+        Int(),
+        default_value=None,
+        desc="number of samples to return from the buffer. If 'None', use 'num' argument of result method",
+    )
+
+    #: index shift value for the buffer. If "result_num", buffer will return and forget 'result_num' samples.
+    #: If "num", buffer will return 'result_num' samples but will forget 'num' samples
+    shift_index_by = Enum(
+        ('result_num', 'num'),
+        desc=(
+            'index shift value for the buffer. If "result_num", use "result_num" trait.'
+            ' If "num", use "num" argument of result method'
+        ),
+    )
+
+    #: current filling level of buffer
+    level = Property(desc='current filling level of buffer')
+
+    #: data type of the buffer elements
+    dtype = Any(desc='data type of the buffer')
+
+    # flag to indicate that the source is empty, for internal use
+    _empty_source = Bool(False, desc='flag to indicate that the source is empty')
+
+    # the buffer for processing
+    _buffer = Array(shape=(None, None), desc='buffer for block processing')
+
+    # current index in buffer
+    _index = Int(desc='current index in buffer')
+
+    def _get_level(self):
+        return self._buffer.shape[0] - self._index
+
+    def _create_new_buffer(self):
+        self._buffer = np.zeros((self.length, self.numchannels), dtype=self.dtype)
+        self._index = self.length
+        self._empty_source = False
+
+    def _write_to_buffer(self, data):
+        ns = data.shape[0]
+        self._buffer[0 : (self.length - ns)] = self._buffer[-(self.length - ns) :]
+        self._buffer[-ns:, :] = data.astype(self.dtype)
+        self._index -= ns
+
+    def increase_buffer(self, num):
+        """Increase the buffer by 'num' samples.
+
+        Returns
+        -------
+        None
+        """
+        ar = np.zeros((num, self.numchannels), dtype=self._buffer.dtype)
+        self._buffer = np.concatenate((ar, self._buffer), axis=0)
+        self._index += num
+        self.length += num
+
+    def read_from_buffer(self, num):
+        """Read samples from the buffer.
+
+        Parameters
+        ----------
+        num : int
+            number of samples to read from the buffer.
+
+        Returns
+        -------
+        numpy.ndarray
+            block of samples from the buffer
+
+        """
+        rnum = num if self.result_num is None else self.result_num
+        rnum = rnum if self.level >= rnum else self.level
+        data = self._buffer[self._index : self._index + rnum]
+        if self.shift_index_by == 'result_num':
+            self._index += rnum
+        else:
+            self._index += num
+        return data
+
+    def fill_buffer(self, snum):
+        """Fill the buffer with samples from the source.
+
+        Parameters
+        ----------
+        snum : int
+            number of samples to return from the source.
+
+        Yields
+        ------
+        None
+        """
+        source_generator = self.source.result(snum)
+        while not self._empty_source:
+            while self._index >= snum:
+                if self.result_num is not None:
+                    while self.result_num > self.length:
+                        self.increase_buffer(snum)
+                try:
+                    self._write_to_buffer(next(source_generator))
+                except StopIteration:
+                    self._empty_source = True
+                    break
+            yield
+
+    def result(self, num):
+        """Return blocks of samples from the buffer.
+
+        Parameters
+        ----------
+        num : int
+            number of samples to return.
+
+        Yields
+        ------
+        numpy.ndarray
+            block of samples from the buffer
+        """
+        self._create_new_buffer()
+        snum = num
+        if self.source_num is not None:
+            snum = self.source_num
+        for _ in self.fill_buffer(snum):
+            if self.level > 0:
+                yield self.read_from_buffer(num)
+            else:
+                break
+        while self.level > 0:
+            yield self.read_from_buffer(num)