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

acoular/__init__.py

@@ -4,11 +4,22 @@
 
 """The Acoular library: several classes for the implementation of acoustic beamforming."""
 
-import os
+import os  # noqa: I001
 
-from . import demo, tools
-from .calib import Calib
+# config must be imported before any submodules containing numpy, see #322.
 from .configuration import config
+
+from . import demo, tools, aiaa
+from .base import (
+    Generator,
+    InOut,
+    SamplesGenerator,
+    SpectraGenerator,
+    SpectraOut,
+    TimeInOut,
+    TimeOut,
+)
+from .calib import Calib
 from .environments import (
     Environment,
     FlowField,
@@ -41,6 +52,7 @@ from .fbeamform import (
     SteeringVector,
     integrate,
 )
+from .fprocess import IRFFT, RFFT, AutoPowerSpectra, CrossPowerSpectra, FFTSpectra
 from .grids import (
     CircSector,
     ConvexSector,
@@ -57,10 +69,13 @@ from .grids import (
     Sector,
 )
 from .microphones import MicGeom
+from .process import Average, Cache, SampleSplitter, TimeAverage, TimeCache
 from .sdinput import SoundDeviceSamplesGenerator
 from .signals import (
     FiltWNoiseGenerator,
     GenericSignalGenerator,
+    NoiseGenerator,
+    PeriodicSignalGenerator,
     PNoiseGenerator,
     SignalGenerator,
     SineGenerator,
@@ -80,7 +95,8 @@ from .sources import (
     TimeSamples,
     UncorrelatedNoiseSource,
 )
-from .spectra import BaseSpectra, FFTSpectra, PowerSpectra, PowerSpectraImport, synthetic
+from .tools.helpers import synthetic
+from .spectra import BaseSpectra, PowerSpectra, PowerSpectraImport
 from .spectra import PowerSpectra as EigSpectra
 from .tbeamform import (
     BeamformerCleant,
@@ -102,19 +118,15 @@ from .tprocess import (
     FiltFreqWeight,
     FiltOctave,
     MaskedTimeInOut,
+    MaskedTimeOut,
     Mixer,
     OctaveFilterBank,
-    SamplesGenerator,
-    SampleSplitter,
     SpatialInterpolator,
     SpatialInterpolatorConstantRotation,
     SpatialInterpolatorRotation,
-    TimeAverage,
-    TimeCache,
     TimeConvolve,
     TimeCumAverage,
     TimeExpAverage,
-    TimeInOut,
     TimePower,
     TimeReverse,
     Trigger,

acoular/aiaa/__init__.py

@@ -0,0 +1,12 @@
+# ------------------------------------------------------------------------------
+# Copyright (c) Acoular Development Team.
+# ------------------------------------------------------------------------------
+"""Provides classes for importing AIAA Array Benchmarks.
+
+.. autosummary::
+    :toctree: generated/
+
+    aiaa
+"""
+
+from .aiaa import CsmAIAABenchmark, MicAIAABenchmark, TimeSamplesAIAABenchmark, TriggerAIAABenchmark

acoular/{tools → aiaa}/aiaa.py

@@ -1,8 +1,8 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Classes for importing AIAA Array Benchmarks
-from . import aiaa
+"""Classes for importing AIAA Array Benchmarks.
+
 These classes allow importing data from HDF5 files following the specifications of
 the AIAA microphone array methods benchmarking effort:
 https://www-docs.b-tu.de/fg-akustik/public/veroeffentlichungen/ArrayMethodsFileFormatsR2P4Release.pdf .
@@ -12,8 +12,8 @@ the framework.
 
 Examples
 --------
->>> micgeom = MicAIAABenchmark(name='some_benchmarkdata.h5')  # doctest: +SKIP
->>> timedata = TimeSamplesAIAABenchmark(name='some_benchmarkdata.h5')  # doctest: +SKIP
+>>> micgeom = MicAIAABenchmark(file='some_benchmarkdata.h5')  # doctest: +SKIP
+>>> timedata = TimeSamplesAIAABenchmark(file='some_benchmarkdata.h5')  # doctest: +SKIP
 
 
 .. autosummary::
@@ -23,10 +23,9 @@ Examples
     TriggerAIAABenchmark
     CsmAIAABenchmark
     MicAIAABenchmark
-"""
+"""  # noqa: W505
 
 import contextlib
-from os import path
 
 from numpy import array
 from traits.api import (
@@ -38,11 +37,13 @@ from traits.api import (
     property_depends_on,
 )
 
+from acoular.deprecation import deprecated_alias
 from acoular.h5files import H5FileBase, _get_h5file_class
 from acoular.internal import digest
 from acoular.microphones import MicGeom
 from acoular.sources import TimeSamples
 from acoular.spectra import PowerSpectraImport
+from acoular.tools.utils import get_file_basename
 
 
 class TimeSamplesAIAABenchmark(TimeSamples):
@@ -54,13 +55,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
+        (self.num_samples, self.num_channels) = 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:
@@ -76,27 +77,28 @@ 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')
-        (self.numsamples, self.numchannels) = self.data.shape
+        (self.num_samples, self.num_channels) = self.data.shape
 
 
+@deprecated_alias({'name': 'file'})
 class CsmAIAABenchmark(PowerSpectraImport):
     """Class to load the CSM that is stored in AIAA Benchmark HDF5 file."""
 
     #: Full name of the .h5 file with data
-    name = File(filter=['*.h5'], desc='name of data file')
+    file = File(filter=['*.h5'], exists=True, desc='name of data file')
 
     #: Basename of the .h5 file with data, is set automatically.
     basename = Property(
-        depends_on='name',
+        depends_on=['file'],
         desc='basename of data file',
     )
 
     #: number of channels
-    numchannels = Property()
+    num_channels = Property()
 
     #: HDF5 file object
     h5f = Instance(H5FileBase, transient=True)
@@ -110,19 +112,16 @@ class CsmAIAABenchmark(PowerSpectraImport):
 
     @cached_property
     def _get_basename(self):
-        return path.splitext(path.basename(self.name))[0]
+        return get_file_basename(self.file)
 
     @on_trait_change('basename')
     def load_data(self):
         """Open the .h5 file and set attributes."""
-        if not path.isfile(self.name):
-            # no file there
-            raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
             with contextlib.suppress(OSError):
                 self.h5f.close()
         file = _get_h5file_class()
-        self.h5f = file(self.name)
+        self.h5f = file(self.file)
 
     # @property_depends_on( 'block_size, ind_low, ind_high' )
     def _get_indices(self):
@@ -131,15 +130,15 @@ class CsmAIAABenchmark(PowerSpectraImport):
         except IndexError:
             return range(0)
 
-    @property_depends_on('digest')
-    def _get_numchannels(self):
+    @property_depends_on(['digest'])
+    def _get_num_channels(self):
         try:
             attrs = self.h5f.get_data_by_reference('MetaData/ArrayAttributes')
             return self.h5f.get_node_attribute(attrs, 'microphoneCount')
         except IndexError:
             return 0
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_csm(self):
         """Loads cross spectral matrix from file."""
         csmre = self.h5f.get_data_by_reference('/CsmData/csmReal')[:].transpose((2, 0, 1))
@@ -167,19 +166,15 @@ class MicAIAABenchmark(MicGeom):
     file containing the measurement data.
     """
 
-    #: Name of the .h5-file from wich to read the data.
-    from_file = File(filter=['*.h5'], desc='name of the h5 file containing the microphone geometry')
+    #: Name of the .h5-file from which to read the data.
+    file = File(filter=['*.h5'], exists=True, desc='name of the h5 file containing the microphone geometry')
 
-    @on_trait_change('basename')
+    @on_trait_change('file')
     def import_mpos(self):
         """Import the microphone positions from .h5 file.
         Called when :attr:`basename` changes.
         """
-        if not path.isfile(self.from_file):
-            # no file there
-            raise OSError('No such file: %s' % self.from_file)
-
         file = _get_h5file_class()
-        h5f = file(self.from_file, mode='r')
-        self.mpos_tot = h5f.get_data_by_reference('MetaData/ArrayAttributes/microphonePositionsM')[:].swapaxes(0, 1)
+        h5f = file(self.file, mode='r')
+        self.pos_total = h5f.get_data_by_reference('MetaData/ArrayAttributes/microphonePositionsM')[:].swapaxes(0, 1)
         h5f.close()

acoular/base.py

@@ -0,0 +1,332 @@
+# ------------------------------------------------------------------------------
+# Copyright (c) Acoular Development Team.
+# ------------------------------------------------------------------------------
+"""Implements base classes for signal processing blocks in Acoular.
+
+The classes in this module are abstract base classes that provide a common interface for all classes
+that generate an output via the generator :meth:`result` in block-wise manner. They are not intended
+to be used directly, but to be subclassed by classes that implement the actual signal processing.
+
+.. autosummary::
+    :toctree: generated/
+
+    Generator
+    SamplesGenerator
+    SpectraGenerator
+    InOut
+    TimeOut
+    SpectraOut
+    TimeInOut
+"""
+
+from abc import abstractmethod
+
+from traits.api import (
+    ABCHasStrictTraits,
+    CArray,
+    CInt,
+    Delegate,
+    Float,
+    Instance,
+    Property,
+    cached_property,
+)
+
+# acoular imports
+from .deprecation import deprecated_alias
+from .internal import digest
+
+
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'})
+class Generator(ABCHasStrictTraits):
+    """Interface for any generating signal processing block.
+
+    It provides a common interface for all classes, which generate an output via the generator
+    :meth:`result` in block-wise manner. It has a common set of traits that are used by all classes
+    that implement this interface. This includes the sampling frequency of the signal
+    (:attr:`sample_freq`), the number of samples (:attr:`num_samples`), and the number of channels
+    (:attr:`num_channels`). A private trait :attr:`digest` is used to store the internal identifier
+    of the object, which is a hash of the object's attributes.
+    This is used to check if the object's internal state has changed.
+
+    """
+
+    #: Sampling frequency of the signal, defaults to 1.0
+    sample_freq = Float(1.0, desc='sampling frequency')
+
+    #: Number of signal samples
+    num_samples = CInt
+
+    #: Number of channels
+    num_channels = CInt
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num):
+        """Python generator that yields the output block-wise.
+
+        This method needs to be implemented by the derived classes.
+
+        Parameters
+        ----------
+        num : int
+            The size of the first dimension of the blocks to be yielded
+
+        Yields
+        ------
+        numpy.ndarray
+            Two-dimensional output data block of shape (num, ...)
+        """
+
+
+class SamplesGenerator(Generator):
+    """Interface for any generating multi-channel time domain signal processing block.
+
+    It provides a common interface for all SamplesGenerator classes, which generate an output via
+    the generator :meth:`result` in block-wise manner. This class has no real functionality on its
+    own and should not be used directly.
+
+    """
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num):
+        """Python generator that yields the output block-wise.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block)
+
+        Yields
+        ------
+        numpy.ndarray
+            The two-dimensional time-data block of shape (num, num_channels).
+        """
+
+
+class SpectraGenerator(Generator):
+    """Interface for any generating multi-channel signal frequency domain processing block.
+
+    It provides a common interface for all SpectraGenerator classes, which generate an output via
+    the generator :meth:`result` in block-wise manner. This class has no real functionality on its
+    own and should not be used directly.
+
+    """
+
+    #: Number of frequencies
+    num_freqs = CInt
+
+    #: 1-D array of frequencies
+    freqs = CArray
+
+    #: The length of the block used to calculate the spectra
+    block_size = CInt
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels', 'num_freqs', 'block_size'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num=1):
+        """Python generator that yields the output block-wise.
+
+        Parameters
+        ----------
+        num : integer
+            This parameter defines the size of the number of snapshots to be yielded.
+            Defaults to 1.
+
+        Yields
+        ------
+        numpy.ndarray
+            A two-dimensional block of shape (num, num_channels * num_freqs).
+        """
+
+
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+class TimeOut(SamplesGenerator):
+    """Abstract base class for any signal processing block that receives data from any
+    :attr:`source` domain and returns time domain signals.
+
+    It provides a base class that can be used to create signal processing blocks that receive data
+    from any generating :attr:`source` and generates a time signal output via the generator
+    :meth:`result` in block-wise manner.
+    """
+
+    #: Data source; :class:`~acoular.base.Generator` or derived object.
+    source = Instance(Generator)
+
+    #: Sampling frequency of output signal, as given by :attr:`source`.
+    sample_freq = Delegate('source')
+
+    #: Number of channels in output, as given by :attr:`source`.
+    num_channels = Delegate('source')
+
+    #: Number of samples in output, as given by :attr:`source`.
+    num_samples = Delegate('source')
+
+    # internal identifier
+    digest = Property(depends_on=['source.digest'])
+
+    @cached_property
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num):
+        """Python generator that processes the source data and yields the time-signal block-wise.
+
+        This method needs to be implemented by the derived classes.
+
+        Parameters
+        ----------
+        num : int
+            This parameter defines the size of the blocks to be yielded
+            (i.e. the number of samples per block)
+
+        Yields
+        ------
+        numpy.ndarray
+            Two-dimensional output data block of shape (num, num_channels)
+        """
+
+
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples', 'numfreqs': 'num_freqs'}, read_only=True)
+class SpectraOut(SpectraGenerator):
+    """Abstract base class for any signal processing block that receives data from any
+    :attr:`source` domain and returns frequency domain signals.
+
+    It provides a base class that can be used to create signal processing blocks that receive data
+    from any generating :attr:`source` domain and generates a frequency domain output via the
+    generator :meth:`result` in block-wise manner.
+    """
+
+    #: Data source; :class:`~acoular.base.Generator` or derived object.
+    source = Instance(Generator)
+
+    #: Sampling frequency of output signal, as given by :attr:`source`.
+    sample_freq = Delegate('source')
+
+    #: Number of channels in output, as given by :attr:`source`.
+    num_channels = Delegate('source')
+
+    #: Number of snapshots in output, as given by :attr:`source`.
+    num_samples = Delegate('source')
+
+    #: Number of frequencies in output, as given by :attr:`source`.
+    num_freqs = Delegate('source')
+
+    #: 1-D array of frequencies, as given by :attr:`source`.
+    freqs = Delegate('source')
+
+    #: The size of the block used to calculate the spectra
+    block_size = Delegate('source')
+
+    # internal identifier
+    digest = Property(depends_on=['source.digest'])
+
+    @cached_property
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num=1):
+        """Python generator that processes the source data and yields the output block-wise.
+
+        This method needs to be implemented by the derived classes.
+
+        num : integer
+            This parameter defines the the number of snapshots to be yielded.
+            Defaults to 1.
+
+        Yields
+        ------
+        numpy.ndarray
+            A two-dimensional block of shape (num, num_channels * num_freqs).
+        """
+
+
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+class InOut(SamplesGenerator, SpectraGenerator):
+    """Abstract base class for any signal processing block that receives data from any
+    :attr:`source` domain and returns signals in the same domain.
+
+    It provides a base class that can be used to create signal processing blocks that receive data
+    from any generating :attr:`source` and generates an output via the generator :meth:`result` in
+    block-wise manner.
+    """
+
+    #: Data source; :class:`~acoular.base.Generator` or derived object.
+    source = Instance(Generator)
+
+    #: Sampling frequency of output signal, as given by :attr:`source`.
+    sample_freq = Delegate('source')
+
+    #: Number of channels in output, as given by :attr:`source`.
+    num_channels = Delegate('source')
+
+    #: Number of frequencies in output, as given by :attr:`source`.
+    num_freqs = Delegate('source')
+
+    #: Number of samples / snapshots in output, as given by :attr:`source`.
+    num_samples = Delegate('source')
+
+    # internal identifier
+    digest = Property(depends_on=['source.digest'])
+
+    @cached_property
+    def _get_digest(self):
+        return digest(self)
+
+    @abstractmethod
+    def result(self, num):
+        """Python generator that processes the source data and yields the output block-wise.
+
+        This method needs to be implemented by the derived classes.
+
+        Parameters
+        ----------
+        num : int
+            The size of the first dimension of the blocks to be yielded
+
+        Yields
+        ------
+        numpy.ndarray
+            Two-dimensional output data block of shape (num, ...)
+        """
+
+
+class TimeInOut(TimeOut):
+    """Deprecated alias for :class:`~acoular.base.TimeOut`.
+
+    .. deprecated:: 24.10
+        Using :class:`~acoular.base.TimeInOut` is deprecated and will be removed in Acoular 25.07.
+        Use :class:`~acoular.base.TimeOut` instead.
+    """
+
+    #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
+    source = Instance(SamplesGenerator)
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        import warnings
+
+        warnings.warn(
+            'TimeInOut is deprecated and will be removed in Acoular 25.07. Use TimeOut instead.',
+            DeprecationWarning,
+            stacklevel=2,
+        )