acoular 24.7__py3-none-any.whl → 24.10__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
+
+# config must be imported before any submodules containing numpy, see #322.
+from .configuration import config
 
 from . import demo, tools
+from .base import (
+    Generator,
+    InOut,
+    SamplesGenerator,
+    SpectraGenerator,
+    SpectraOut,
+    TimeInOut,
+    TimeOut,
+)
 from .calib import Calib
-from .configuration import config
 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,6 +69,7 @@ from .grids import (
     Sector,
 )
 from .microphones import MicGeom
+from .process import Average, Cache, SampleSplitter, TimeAverage, TimeCache
 from .sdinput import SoundDeviceSamplesGenerator
 from .signals import (
     FiltWNoiseGenerator,
@@ -80,7 +93,7 @@ from .sources import (
     TimeSamples,
     UncorrelatedNoiseSource,
 )
-from .spectra import BaseSpectra, FFTSpectra, PowerSpectra, PowerSpectraImport, synthetic
+from .spectra import BaseSpectra, PowerSpectra, PowerSpectraImport, synthetic
 from .spectra import PowerSpectra as EigSpectra
 from .tbeamform import (
     BeamformerCleant,
@@ -102,19 +115,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/base.py

@@ -0,0 +1,312 @@
+# ------------------------------------------------------------------------------
+# 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 traits.api import (
+    CArray,
+    CLong,
+    Delegate,
+    Float,
+    HasPrivateTraits,
+    Instance,
+    Property,
+    cached_property,
+)
+
+from acoular.internal import digest
+
+
+class Generator(HasPrivateTraits):
+    """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`) and the number of samples (:attr:`numsamples`).
+    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
+    numsamples = CLong
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'numsamples'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    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.
+    """
+
+    #: Number of channels
+    numchannels = CLong
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'numchannels', 'numsamples'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    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, numchannels).
+        """
+
+
+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 channels
+    numchannels = CLong
+
+    #: Number of frequencies
+    numfreqs = CLong
+
+    #: 1-D array of frequencies
+    freqs = CArray
+
+    #: The length of the block used to calculate the spectra
+    block_size = CLong
+
+    # internal identifier
+    digest = Property(depends_on=['sample_freq', 'numchannels', 'numsamples', 'numfreqs', 'block_size'])
+
+    def _get_digest(self):
+        return digest(self)
+
+    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, numchannels*numfreqs).
+        """
+
+
+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`.
+    numchannels = Delegate('source')
+
+    #: Number of samples in output, as given by :attr:`source`.
+    numsamples = Delegate('source')
+
+    # internal identifier
+    digest = Property(depends_on=['source.digest'])
+
+    @cached_property
+    def _get_digest(self):
+        return digest(self)
+
+    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, numchannels)
+        """
+        yield from self.source.result(num)
+
+
+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`.
+    numchannels = Delegate('source')
+
+    #: Number of snapshots in output, as given by :attr:`source`.
+    numsamples = Delegate('source')
+
+    #: Number of frequencies in output, as given by :attr:`source`.
+    numfreqs = 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)
+
+    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, numchannels*numfreqs).
+        """
+        yield from self.source.result(num)
+
+
+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`.
+    numchannels = Delegate('source')
+
+    #: Number of samples / snapshots in output, as given by :attr:`source`.
+    numsamples = Delegate('source')
+
+    # internal identifier
+    digest = Property(depends_on=['source.digest'])
+
+    @cached_property
+    def _get_digest(self):
+        return digest(self)
+
+    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, ...)
+        """
+        yield from self.source.result(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,
+        )

acoular/configuration.py

@@ -35,7 +35,7 @@ if 'numpy' in sys.modules:
     np.show_config()
     sys.stdout = orig_stdout
     # check if it uses OpenBLAS or another library
-    if 'openblas' in temp_stdout.getvalue().lower():
+    if 'openblas' in temp_stdout.getvalue().lower() and environ.get('OPENBLAS_NUM_THREADS') != '1':
         # it's OpenBLAS, set numba threads=1 to avoid overcommittment
         import numba
 
@@ -54,7 +54,7 @@ else:
     environ['OPENBLAS_NUM_THREADS'] = '1'
 
 # this loads numpy, so we have to defer loading until OpenBLAS check is done
-from traits.api import Bool, Either, HasStrictTraits, Property, Str, Trait, cached_property
+from traits.api import Bool, Enum, HasStrictTraits, Property, Str, Trait, cached_property
 
 
 class Config(HasStrictTraits):
@@ -97,7 +97,7 @@ class Config(HasStrictTraits):
     #: If 'pytables' can not be imported, 'h5py' is used.
     h5library = Property()
 
-    _h5library = Either('pytables', 'tables', 'h5py', default='pytables')
+    _h5library = Enum('pytables', 'tables', 'h5py')
 
     #: Defines the path to the directory containing Acoulars cache files.
     #: If the specified :attr:`cache_dir` directory does not exist,

acoular/demo/acoular_demo.py

@@ -61,7 +61,7 @@ def run():
 
     # analyze the data and generate map
 
-    ps = ac.PowerSpectra(time_data=pa, block_size=128, window='Hanning')
+    ps = ac.PowerSpectra(source=pa, block_size=128, window='Hanning')
 
     rg = ac.RectGrid(x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, increment=0.01)
     st = ac.SteeringVector(grid=rg, mics=mg)

acoular/environments.py

@@ -43,9 +43,9 @@ from numpy import (
     vstack,
     zeros_like,
 )
-from numpy.linalg.linalg import norm
 from scipy.integrate import ode
 from scipy.interpolate import LinearNDInterpolator
+from scipy.linalg import norm
 from scipy.spatial import ConvexHull
 from traits.api import CArray, Dict, Float, HasPrivateTraits, Int, Property, Trait, cached_property
 
@@ -283,8 +283,9 @@ class FlowField(HasPrivateTraits):
 
 
 class SlotJet(FlowField):
-    """Provides an analytical approximation of the flow field of a slot jet,
-    see :ref:`Albertson et al., 1950<Albertson1950>`.
+    """Provides an analytical approximation of the flow field of a slot jet.
+
+    See :cite:`Albertson1950` for details.
     """
 
     #: Exit velocity at jet origin, i.e. the nozzle. Defaults to 0.
@@ -364,8 +365,9 @@ class SlotJet(FlowField):
 
 
 class OpenJet(FlowField):
-    """Provides an analytical approximation of the flow field of an open jet,
-    see :ref:`Albertson et al., 1950<Albertson1950>`.
+    """Provides an analytical approximation of the flow field of an open jet.
+
+    See :cite:`Albertson1950` for details.
 
     Notes
     -----