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

acoular/process.py

@@ -1,7 +1,7 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Implements general purpose blockwise processing methods independent of the domain (time or frequency).
+"""General purpose blockwise processing methods independent of the domain (time or frequency).
 
 .. autosummary::
     :toctree: generated/
@@ -11,6 +11,7 @@
     SampleSplitter
     TimeAverage
     TimeCache
+    SamplesBuffer
 """
 
 import threading
@@ -18,13 +19,17 @@ from collections import deque
 from inspect import currentframe
 from warnings import warn
 
-from traits.api import Bool, Dict, Instance, Int, Property, Trait, cached_property, on_trait_change
+import numpy as np
+from traits.api import Any, Array, Bool, Dict, Enum, Instance, Int, Property, Union, cached_property, on_trait_change
 
+# acoular imports
 from .base import Generator, InOut
 from .configuration import config
+from .deprecation import deprecated_alias
 from .h5cache import H5cache
 from .h5files import H5CacheFileBase
 from .internal import digest
+from .tools.utils import find_basename
 
 
 class LockedGenerator:
@@ -42,40 +47,45 @@ class LockedGenerator:
             return self.it.__next__()
 
 
+@deprecated_alias({'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'])
 class Average(InOut):
     """Calculates the average across consecutive time samples or frequency snapshots.
 
     The average operation is performed differently depending on the source type.
-    If the source is a time domain source (e.g. derived from :class:`~acoular.base.SamplesGenerator`),
-    the average is calculated over a certain number of time samples given by :attr:`naverage`.
-    If the source is a frequency domain source (e.g. derived from :class:`~acoular.base.SpectraGenerator`),
-    the average is calculated over a certain number of snapshots given by :attr:`naverage`.
+    If the source is a time domain source
+    (e.g. derived from :class:`~acoular.base.SamplesGenerator`), the average is
+    calculated over a certain number of time samples given by :attr:`num_per_average`.
+    If the source is a frequency domain source (e.g. derived from
+    :class:`~acoular.base.SpectraGenerator`), the average is calculated over a certain
+    number of snapshots given by :attr:`num_per_average`.
 
     Examples
     --------
-        For estimate the RMS of a white noise (time-domain) signal, the average of the squared signal can be calculated:
+        For estimate the RMS of a white noise (time-domain) signal, the average of the squared
+        signal can be calculated:
 
         >>> import acoular as ac
         >>> import numpy as np
         >>>
-        >>> signal = ac.WNoiseGenerator(sample_freq=51200, numsamples=51200, rms=2.0).signal()
+        >>> signal = ac.WNoiseGenerator(sample_freq=51200, num_samples=51200, rms=2.0).signal()
         >>> ts = ac.TimeSamples(data=signal[:, np.newaxis], sample_freq=51200)
         >>> tp = ac.TimePower(source=ts)
-        >>> avg = ac.Average(source=tp, naverage=512)
+        >>> avg = ac.Average(source=tp, num_per_average=512)
         >>> mean_squared_value = next(avg.result(num=1))
         >>> rms = np.sqrt(mean_squared_value)[0, 0]
         >>> print(rms)
         1.9985200025816718
 
-        Here, each evaluation of the generator created by the :meth:`result` method of the :class:`Average` object
-        via the :meth:`next` function returns :code:`num=1` average across a snapshot of 512 samples.
+        Here, each evaluation of the generator created by the :meth:`result` method of the
+        :class:`Average` object via the :meth:`next` function returns :code:`num=1` average across a
+        snapshot of 512 samples.
 
-        If the source is a frequency domain source, the average is calculated over a certain number of
-        snapshots, defined by :attr:`naverage`.
+        If the source is a frequency domain source, the average is calculated over a certain number
+        of snapshots, defined by :attr:`num_per_average`.
 
         >>> fft = ac.RFFT(source=ts, block_size=64)
         >>> ps = ac.AutoPowerSpectra(source=fft)
-        >>> avg = ac.Average(source=ps, naverage=16)
+        >>> avg = ac.Average(source=ps, num_per_average=16)
         >>> mean_power = next(avg.result(num=1))
         >>> print(np.sqrt(mean_power.sum()))
         2.0024960894399295
@@ -87,17 +97,17 @@ class Average(InOut):
 
     #: Number of samples (time domain source) or snapshots (frequency domain source)
     #: to average over, defaults to 64.
-    naverage = Int(64, desc='number of samples to average over')
+    num_per_average = Int(64, desc='number of samples/snapshots to average over')
 
     #: Sampling frequency of the output signal, is set automatically.
-    sample_freq = Property(depends_on='source.sample_freq, naverage')
+    sample_freq = Property(depends_on=['source.sample_freq', 'num_per_average'])
 
     #: Number of samples (time domain) or snapshots (frequency domain) of the output signal.
     #: Is set automatically.
-    numsamples = Property(depends_on='source.numsamples, naverage')
+    num_samples = Property(depends_on=['source.num_samples', 'num_per_average'])
 
     # internal identifier
-    digest = Property(depends_on=['source.digest', '__class__', 'naverage'])
+    digest = Property(depends_on=['source.digest', 'num_per_average'])
 
     @cached_property
     def _get_digest(self):
@@ -106,13 +116,13 @@ class Average(InOut):
     @cached_property
     def _get_sample_freq(self):
         if self.source:
-            return 1.0 * self.source.sample_freq / self.naverage
+            return 1.0 * self.source.sample_freq / self.num_per_average
         return None
 
     @cached_property
-    def _get_numsamples(self):
+    def _get_num_samples(self):
         if self.source:
-            return self.source.numsamples / self.naverage
+            return self.source.num_samples / self.num_per_average
         return None
 
     def result(self, num):
@@ -127,11 +137,11 @@ class Average(InOut):
         Returns
         -------
         Average of the output of source.
-            Yields samples in blocks of shape (num, numchannels).
+            Yields samples in blocks of shape (num, num_channels).
             The last block may be shorter than num.
 
         """
-        nav = self.naverage
+        nav = self.num_per_average
         for temp in self.source.result(num * nav):
             ns, nc = temp.shape
             nso = int(ns / nav)
@@ -158,7 +168,7 @@ class Cache(InOut):
     >>> cache = ac.Cache(source=fft)  # cache the output of the FFT in cache file
     >>> for block in cache.result(num=1):  # read the cached data block-wise
     ...     print(block.shape)
-    [('_cache.h5', 1)]
+    [('void_cache.h5', 1)]
     (1, 513)
 
     The caching behaviour can be controlled by the :class:`~acoular.configuration.Config` instance
@@ -172,13 +182,13 @@ class Cache(InOut):
     """
 
     # basename for cache
-    basename = Property(depends_on='digest')
+    basename = Property(depends_on=['digest'])
 
     # hdf5 cache file
     h5f = Instance(H5CacheFileBase, transient=True)
 
     # internal identifier
-    digest = Property(depends_on=['source.digest', '__class__'])
+    digest = Property(depends_on=['source.digest'])
 
     @cached_property
     def _get_digest(self):
@@ -186,17 +196,7 @@ class Cache(InOut):
 
     @cached_property
     def _get_basename(self):
-        obj = self.source  # start with source
-        basename = 'void'  # if no file source is found
-        while obj:
-            if 'basename' in obj.all_trait_names():  # at original source?
-                basename = obj.basename  # get the name
-                break
-            try:
-                obj = obj.source  # traverse down until original data source
-            except AttributeError:
-                obj = None
-        return basename
+        return find_basename(self.source)
 
     def _pass_data(self, num):
         yield from self.source.result(num)
@@ -256,10 +256,10 @@ class Cache(InOut):
 
         Returns
         -------
-        Samples in blocks of shape (num, numchannels).
+        Samples in blocks of shape (num, num_channels).
             The last block may be shorter than num.
             Echos the source output, but reads it from cache
-            when available and prevents unnecassary recalculation.
+            when available and prevents unnecessary recalculation.
 
         """
         if config.global_caching == 'none':
@@ -282,8 +282,8 @@ class Cache(InOut):
                 elif not self.h5f.get_data_by_reference(nodename).attrs['complete']:
                     if config.global_caching == 'readonly':
                         warn(
-                            "Cache file is incomplete for nodename %s. With config.global_caching='readonly', the cache file will not be used!"
-                            % str(nodename),
+                            f"Cache file is incomplete for nodename {nodename}. With config.global_caching='readonly', \
+                            the cache file will not be used!",
                             Warning,
                             stacklevel=1,
                         )
@@ -298,9 +298,74 @@ class Cache(InOut):
 
 
 class SampleSplitter(InOut):
-    """Distributes data blocks from source to several following objects.
-    A separate block buffer is created for each registered object in
-    (:attr:`block_buffer`) .
+    """
+    Distributes data from a source to several following objects in a block-wise manner.
+
+    The `SampleSplitter` class is designed to take data from a single
+    :class:`~acoular.base.Generator` derived source object and distribute it to multiple
+    :class:`~acoular.base.Generator` derived objects. For each object, the :class:`SampleSplitter`
+    holds a virtual block buffer from which the subsequently connected objects receive data in a
+    first-in-first-out (FIFO) manner. This allows for efficient data handling and processing in
+    parallel.
+
+    Examples
+    --------
+    Consider a time domain source signal stream from which the FFT spectra and the signal power
+    are calculated block-wise and in parallel by using the :class:`~acoular.fprocess.RFFT` as well
+    as the :class:`~acoular.tprocess.TimePower` and :class:`~acoular.process.Average`
+    objects. The `SampleSplitter` object is used to distribute the incoming blocks of data to the
+    `RFFT` and `TimePower` object buffers whenever one of these objects calls the :meth:`result`
+    generator.
+    For the `TimePower` object, the buffer size is set to 10 blocks. If the buffer is full, an error
+    is raised since the buffer overflow treatment is set to 'error'. For the `RFFT` object, the
+    block buffer size is set to 1 block, and the buffer overflow treatment is set to 'none'. This
+    is done to reduce latency in the FFT calculation, as the FFT calculation may take longer than
+    the signal power calculation. If new data is available and the block buffer for the `RFFT`
+    object is full, the `SampleSplitter` will drop the oldest block of data in the buffer. Thus, the
+    `RFFT` object will always receive the most recent block of data.
+
+    >>> import acoular as ac
+    >>> import numpy as np
+    >>>
+    >>> # create a time domain signal source
+    >>> ts = ac.TimeSamples(data=np.random.rand(1024, 1), sample_freq=51200)
+    >>>
+    >>> # create the sample splitter object
+    >>> ss = ac.SampleSplitter(source=ts)
+    >>>
+    >>> # create the FFT spectra and further objects that receive the data
+    >>> fft = ac.RFFT(source=ss, block_size=64)
+    >>> pow = ac.TimePower(source=ss)
+    >>> avg = ac.Average(source=pow, num_per_average=64)
+    >>>
+    >>> # register the subsequent processing block objects at the sample splitter
+    >>> ss.register_object(fft, buffer_size=1, buffer_overflow_treatment='none')
+    >>> ss.register_object(pow, buffer_size=10, buffer_overflow_treatment='error')
+
+    After object registration, the `SampleSplitter` object is ready to distribute the data to the
+    object buffers. The block buffers can be accessed via the `block_buffer` attribute of the
+    `SampleSplitter` object.
+
+    >>> ss.block_buffer.values()
+    dict_values([deque([], maxlen=1), deque([], maxlen=10)])
+
+    Calling the result method of the FFT object will start the data collection and distribution
+    process.
+
+    >>> generator = fft.result(num=1)
+    >>> fft_res = next(generator)
+
+    Although we haven't called the result method of the signal power object, one data block is
+    already available in the buffer.
+
+    >>> print(len(ss.block_buffer[pow]))
+    1
+
+    To remove registered objects from the `SampleSplitter`, use the :meth:`remove_object` method.
+
+    >>> ss.remove_object(pow)
+    >>> print(len(ss.block_buffer))
+    1
     """
 
     #: dictionary with block buffers (dict values) of registered objects (dict
@@ -308,7 +373,13 @@ class SampleSplitter(InOut):
     block_buffer = Dict(key_trait=Instance(Generator))
 
     #: max elements/blocks in block buffers.
-    buffer_size = Int(100)
+    #: Can be set individually for each registered object.
+    #: Default is 100 blocks for each registered object.
+    buffer_size = Union(
+        Int,
+        Dict(key_trait=Instance(Generator), value_trait=Int),
+        default_value=100,
+    )
 
     #: defines behaviour in case of block_buffer overflow. Can be set individually
     #: for each registered object.
@@ -318,7 +389,7 @@ class SampleSplitter(InOut):
     #: * 'none': nothing happens. Possibly leads to lost blocks of data
     buffer_overflow_treatment = Dict(
         key_trait=Instance(Generator),
-        value_trait=Trait('error', 'warning', 'none'),
+        value_trait=Enum('error', 'warning', 'none'),
         desc='defines buffer overflow behaviour.',
     )
 
@@ -330,13 +401,17 @@ class SampleSplitter(InOut):
     _buffer_overflow = Bool(False)
 
     # Helper Trait holds source generator
-    _source_generator = Trait()
+    _source_generator = Instance(LockedGenerator)
 
-    def _create_block_buffer(self, obj):
-        self.block_buffer[obj] = deque([], maxlen=self.buffer_size)
+    def _create_block_buffer(self, obj, buffer_size=None):
+        if buffer_size is None:
+            buffer_size = self.buffer_size if isinstance(self.buffer_size, int) else self.buffer_size[obj]
+        self.block_buffer[obj] = deque([], maxlen=buffer_size)
 
-    def _create_buffer_overflow_treatment(self, obj):
-        self.buffer_overflow_treatment[obj] = 'error'
+    def _create_buffer_overflow_treatment(self, obj, buffer_overflow_treatment=None):
+        if buffer_overflow_treatment is None:
+            buffer_overflow_treatment = 'error'
+        self.buffer_overflow_treatment[obj] = buffer_overflow_treatment
 
     def _clear_block_buffer(self, obj):
         self.block_buffer[obj].clear()
@@ -349,7 +424,8 @@ class SampleSplitter(InOut):
 
     def _assert_obj_registered(self, obj):
         if obj not in self.block_buffer:
-            raise OSError('calling object %s is not registered.' % obj)
+            msg = f'calling object {obj} is not registered.'
+            raise OSError(msg)
 
     def _get_objs_to_inspect(self):
         return [obj for obj in self.buffer_overflow_treatment if self.buffer_overflow_treatment[obj] != 'none']
@@ -360,7 +436,7 @@ class SampleSplitter(InOut):
                 if self.buffer_overflow_treatment[obj] == 'error':
                     self._buffer_overflow = True
                 elif self.buffer_overflow_treatment[obj] == 'warning':
-                    warn('overfilled buffer for object: %s data will get lost' % obj, UserWarning, stacklevel=1)
+                    warn(f'overfilled buffer for object: {obj} data will get lost', UserWarning, stacklevel=1)
 
     def _create_source_generator(self, num):
         for obj in self.block_buffer:
@@ -379,15 +455,45 @@ class SampleSplitter(InOut):
             self._remove_block_buffer(obj)
             self._create_block_buffer(obj)
 
-    def register_object(self, *objects_to_register):
-        """Function that can be used to register objects that receive blocks from this class."""
+    def register_object(self, *objects_to_register, buffer_size=None, buffer_overflow_treatment=None):
+        """Register one or multiple :class:`~acoular.base.Generator` objects to the SampleSplitter.
+
+        Creates a block buffer for each object and sets the buffer size and buffer
+        overflow treatment.
+
+        Parameters
+        ----------
+        objects_to_register : Generator
+            One or multiple :class:`~acoular.base.Generator` derived objects to be registered.
+        buffer_size : int, optional
+            Maximum number of elements/blocks in block buffer. If not set, the default buffer size
+            of 100 blocks is used.
+        buffer_overflow_treatment : str, optional
+            Defines the behaviour in case of reaching the buffer size.
+            Can be set individually for each object. Possible values are 'error', 'warning', and
+            'none'. If not set, the default value is 'error'.
+        """
         for obj in objects_to_register:
             if obj not in self.block_buffer:
-                self._create_block_buffer(obj)
-                self._create_buffer_overflow_treatment(obj)
+                self._create_block_buffer(obj, buffer_size)
+                self._create_buffer_overflow_treatment(obj, buffer_overflow_treatment)
+            else:
+                msg = f'object {obj} is already registered.'
+                raise OSError(msg)
 
     def remove_object(self, *objects_to_remove):
-        """Function that can be used to remove registered objects."""
+        """Function that can be used to remove registered objects.
+
+        If no objects are given, all registered objects are removed.
+
+        Parameters
+        ----------
+        objects_to_remove : list
+            One or multiple :class:`~acoular.base.Generator` derived objects to be removed.
+            If not set, all registered objects are removed.
+        """
+        if not objects_to_remove:
+            objects_to_remove = list(self.block_buffer.keys())
         for obj in objects_to_remove:
             self._remove_block_buffer(obj)
             self._remove_buffer_overflow_treatment(obj)
@@ -403,7 +509,7 @@ class SampleSplitter(InOut):
 
         Returns
         -------
-        Samples in blocks of shape (num, numchannels).
+        Samples in blocks of shape (num, num_channels).
             Delivers a block of samples to the calling object.
             The last block may be shorter than num.
 
@@ -462,3 +568,204 @@ class TimeCache(Cache):
             DeprecationWarning,
             stacklevel=2,
         )
+
+
+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,
+    ...         num_samples=512,
+    ...     ).signal()[:, np.newaxis],
+    ...     sample_freq=64,
+    ... )
+    >>> # create a buffer with a size of 32 samples
+    >>> buffer = ac.process.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.process.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])
+    """  # noqa: W505
+
+    #: 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.num_channels), 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.num_channels), 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)