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

acoular/__init__.py

@@ -4,15 +4,21 @@
 
 """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 .version import __author__, __date__, __version__
-
-if config.have_sounddevice:
-    from .sdinput import SoundDeviceSamplesGenerator
 
 from . import demo, tools
+from .base import (
+    Generator,
+    InOut,
+    SamplesGenerator,
+    SpectraGenerator,
+    SpectraOut,
+    TimeInOut,
+    TimeOut,
+)
 from .calib import Calib
 from .environments import (
     Environment,
@@ -46,6 +52,7 @@ from .fbeamform import (
     SteeringVector,
     integrate,
 )
+from .fprocess import IRFFT, RFFT, AutoPowerSpectra, CrossPowerSpectra, FFTSpectra
 from .grids import (
     CircSector,
     ConvexSector,
@@ -62,6 +69,8 @@ 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,
@@ -84,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,
@@ -106,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,
@@ -126,3 +131,4 @@ from .tprocess import (
     WriteWAV,
 )
 from .trajectory import Trajectory
+from .version import __author__, __date__, __version__

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):
@@ -70,9 +70,9 @@ class Config(HasStrictTraits):
     --------
         For using Acoular with h5py package and overwrite existing cache:
 
-        >>>    import acoular
-        >>>    acoular.config.h5library = "h5py"
-        >>>    acoular.config.global_caching = "overwrite"
+        >>> import acoular
+        >>> acoular.config.h5library = 'h5py'
+        >>> acoular.config.global_caching = 'overwrite'
 
     """
 
@@ -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,
@@ -134,25 +134,28 @@ class Config(HasStrictTraits):
     #: Boolean Flag that determines whether sounddevice is installed.
     have_sounddevice = Property()
 
+    #: Boolean Flag that determines whether the package is installed.
+    have_traitsui = Property()
+
     def _get_global_caching(self):
         return self._global_caching
 
-    def _set_global_caching(self, globalCachingValue):
-        self._global_caching = globalCachingValue
+    def _set_global_caching(self, value):
+        self._global_caching = value
 
     def _get_h5library(self):
         return self._h5library
 
-    def _set_h5library(self, libraryName):
-        self._h5library = libraryName
+    def _set_h5library(self, name):
+        self._h5library = name
 
     def _get_use_traitsui(self):
         return self._use_traitsui
 
     def _set_use_traitsui(self, use_tui):
-        if use_tui:
-            from . import traitsviews
-            # If user tries to use traitsuis and it's not installed, this will throw an error.
+        if use_tui and not self.have_traitsui:
+            error_msg = 'TraitsUI package is not installed!'
+            raise ImportError(error_msg)
         self._use_traitsui = use_tui
 
     def _assert_h5library(self):
@@ -205,6 +208,10 @@ class Config(HasStrictTraits):
     def _get_have_h5py(self):
         return self._have_module('h5py')
 
+    @cached_property
+    def _get_have_traitsui(self):
+        return self._have_module('traitsui')
+
 
 config = Config()
 """
@@ -232,7 +239,7 @@ Note: this is independent from the GUI tools implemented in the spectAcoular pac
 Example:
     For using Acoular with h5py package and overwrite existing cache:
 
-    >>>    import acoular
-    >>>    acoular.config.h5library = "h5py"
-    >>>    acoular.config.global_caching = "overwrite"
+    >>> import acoular
+    >>> acoular.config.h5library = "h5py"
+    >>> acoular.config.global_caching = "overwrite"
 """

acoular/demo/acoular_demo.py

@@ -19,10 +19,10 @@ The simulation generates the sound pressure at 64 microphones that are
 arrangend in the 'array64' geometry, which is part of the package. The sound
 pressure signals are sampled at 51200 Hz for a duration of 1 second.
 
-Source location (relative to array center) and levels:
+Source location (relative to array center) and RMS in 1 m distance:
 
 ====== =============== ======
-Source Location        Level
+Source Location        RMS
 ====== =============== ======
 1      (-0.1,-0.1,0.3) 1.0 Pa
 2      (0.15,0,0.3)    0.7 Pa
@@ -36,58 +36,45 @@ def run():
     """Run the Acoular demo."""
     from pathlib import Path
 
-    from acoular import (
-        BeamformerBase,
-        L_p,
-        MicGeom,
-        Mixer,
-        PointSource,
-        PowerSpectra,
-        RectGrid,
-        SteeringVector,
-        TimeSamples,
-        WNoiseGenerator,
-        WriteH5,
-        config,
-    )
-    from acoular import __file__ as bpath
+    import acoular as ac
+
+    ac.config.global_caching = 'none'
 
     # set up the parameters
     sfreq = 51200
     duration = 1
     nsamples = duration * sfreq
-    micgeofile = Path(bpath).parent / 'xml' / 'array_64.xml'
+    micgeofile = Path(ac.__file__).parent / 'xml' / 'array_64.xml'
     h5savefile = 'three_sources.h5'
 
     # generate test data, in real life this would come from an array measurement
-    mg = MicGeom(from_file=micgeofile)
-    n1 = WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=1)
-    n2 = WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=2, rms=0.7)
-    n3 = WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=3, rms=0.5)
-    p1 = PointSource(signal=n1, mics=mg, loc=(-0.1, -0.1, 0.3))
-    p2 = PointSource(signal=n2, mics=mg, loc=(0.15, 0, 0.3))
-    p3 = PointSource(signal=n3, mics=mg, loc=(0, 0.1, 0.3))
-    pa = Mixer(source=p1, sources=[p2, p3])
-    wh5 = WriteH5(source=pa, name=h5savefile)
+    mg = ac.MicGeom(from_file=micgeofile)
+    n1 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=1)
+    n2 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=2, rms=0.7)
+    n3 = ac.WNoiseGenerator(sample_freq=sfreq, numsamples=nsamples, seed=3, rms=0.5)
+    p1 = ac.PointSource(signal=n1, mics=mg, loc=(-0.1, -0.1, 0.3))
+    p2 = ac.PointSource(signal=n2, mics=mg, loc=(0.15, 0, 0.3))
+    p3 = ac.PointSource(signal=n3, mics=mg, loc=(0, 0.1, 0.3))
+    pa = ac.Mixer(source=p1, sources=[p2, p3])
+    wh5 = ac.WriteH5(source=pa, name=h5savefile)
     wh5.save()
 
     # analyze the data and generate map
 
-    ts = TimeSamples(name=h5savefile)
-    ps = PowerSpectra(time_data=ts, block_size=128, window='Hanning')
+    ps = ac.PowerSpectra(source=pa, block_size=128, window='Hanning')
 
-    rg = RectGrid(x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, increment=0.01)
-    st = SteeringVector(grid=rg, mics=mg)
+    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)
 
-    bb = BeamformerBase(freq_data=ps, steer=st)
+    bb = ac.BeamformerBase(freq_data=ps, steer=st)
     pm = bb.synthetic(8000, 3)
-    Lm = L_p(pm)
+    spl = ac.L_p(pm)
 
-    if config.have_matplotlib:
+    if ac.config.have_matplotlib:
         from pylab import axis, colorbar, figure, imshow, plot, show
 
         # show map
-        imshow(Lm.T, origin='lower', vmin=Lm.max() - 10, extent=rg.extend(), interpolation='bicubic')
+        imshow(spl.T, origin='lower', vmin=spl.max() - 10, extent=rg.extend(), interpolation='bicubic')
         colorbar()
 
         # plot microphone geometry
@@ -99,6 +86,12 @@ def run():
 
     else:
         print('Matplotlib not found! Please install matplotlib if you want to plot the results.')
+        print('For consolation we do an ASCII map plot of the results here.')
+        grayscale = '@%#*+=-:. '[::-1]
+        ind = ((spl.T - spl.max() + 9).clip(0, 9)).astype(int)[::-1]
+        print(78 * '-')
+        print('|\n'.join([' '.join(['|'] + [grayscale[i] for i in row[2:-1]]) for row in ind]) + '|')
+        print(7 * '-', ''.join([f'{grayscale[i]}={int(spl.max())-9+i}dB ' for i in range(1, 10)]), 6 * '-')
 
 
 if __name__ == '__main__':