acoular 24.5__tar.gz → 24.10__tar.gz

{acoular-24.5 → acoular-24.10}/.gitignore

@@ -1,14 +1,7 @@
 # files and file types to ignore
 *.pyc
-*.pyd
 *.so
 *~
-examples/three_sources.h5
-examples/all_bf.sav
-examples/benchmark/results/
-MANIFEST
-
-# ignore the build directories
 *.egg-info/
 .eggs/
 build/
@@ -23,7 +16,14 @@ __pycache__/
 *.nbc
 *.nbi
 *.pyd
-docs/source/api_ref/generated/
 .vscode/
+.venv*
 
-acoular/demo/three_sources.h5
+MANIFEST
+
+examples/all_bf.sav
+examples/benchmark/results/
+**/three_sources.h5
+docs/source/sg_execution_times.rst
+docs/source/api_ref/generated/
+docs/source/auto_examples/**/*

{acoular-24.5 → acoular-24.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: acoular
-Version: 24.5
+Version: 24.10
 Summary: Python library for acoustic beamforming
 Project-URL: homepage, https://acoular.org
 Project-URL: documentation, https://acoular.org
@@ -42,23 +42,58 @@ Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
 Classifier: License :: OSI Approved :: BSD License
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering :: Physics
-Requires-Python: <=12,>=3.8
+Requires-Python: <=12,>=3.10
 Requires-Dist: numba
 Requires-Dist: numpy
 Requires-Dist: scikit-learn
 Requires-Dist: scipy>=1.1.0
-Requires-Dist: tables>=3.4.4
+Requires-Dist: tables
 Requires-Dist: traits>=6.0
+Provides-Extra: dev
+Requires-Dist: graphviz; extra == 'dev'
+Requires-Dist: h5py; extra == 'dev'
+Requires-Dist: hatch; extra == 'dev'
+Requires-Dist: ipython; extra == 'dev'
+Requires-Dist: matplotlib; extra == 'dev'
+Requires-Dist: numpydoc; extra == 'dev'
+Requires-Dist: pickleshare; extra == 'dev'
+Requires-Dist: pylops; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: ruff==0.4.1; extra == 'dev'
+Requires-Dist: setuptools; extra == 'dev'
+Requires-Dist: sounddevice; extra == 'dev'
+Requires-Dist: sphinx; extra == 'dev'
+Requires-Dist: sphinx-gallery; extra == 'dev'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'dev'
+Requires-Dist: traitsui; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: graphviz; extra == 'docs'
+Requires-Dist: ipython; extra == 'docs'
+Requires-Dist: matplotlib; extra == 'docs'
+Requires-Dist: numpydoc; extra == 'docs'
+Requires-Dist: pickleshare; extra == 'docs'
+Requires-Dist: setuptools; extra == 'docs'
+Requires-Dist: sounddevice; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-gallery; extra == 'docs'
+Requires-Dist: sphinxcontrib-bibtex; extra == 'docs'
 Provides-Extra: full
 Requires-Dist: matplotlib; extra == 'full'
 Requires-Dist: pylops; extra == 'full'
 Requires-Dist: sounddevice; extra == 'full'
+Provides-Extra: tests
+Requires-Dist: h5py; extra == 'tests'
+Requires-Dist: pytest; extra == 'tests'
+Requires-Dist: pytest-cov; extra == 'tests'
+Requires-Dist: pyyaml; extra == 'tests'
+Requires-Dist: sounddevice; extra == 'tests'
+Requires-Dist: traitsui; extra == 'tests'
 Description-Content-Type: text/markdown
 
 ![Acoular Logo](https://github.com/acoular/acoular/blob/master/docs/source/_static/Acoular_logo.png?raw=true)
@@ -135,12 +170,17 @@ For more detailed installation instructions, see the [documentation](https://aco
 # Documentation and help
 Documentation is available [here](https://acoular.org) with a
 [getting started](https://acoular.org/get_started/index.html) section and
-[examples](https://acoular.org/examples/index.html).
+[examples](https://acoular.org/auto_examples/index.html).
 
 The Acoular [blog](https://acoular.github.io/blog/) contains some tutorials.
 
 If you discover problems with the Acoular software, please report them using the [issue tracker](https://github.com/acoular/acoular/issues) on GitHub. Please use the [Acoular discussions forum](https://github.com/acoular/acoular/discussions) for practical questions, discussions, and demos.
 
+# Contributing
+
+We are always happy to welcome new contributors to the project. 
+If you are interested in contributing, have a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
 # Example
 This reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band:
 
@@ -156,7 +196,7 @@ mg = acoular.MicGeom( from_file=micgeofile )
 # set up object managing the microphone array data (usually from measurement)
 ts = acoular.TimeSamples( name='three_sources.h5' )
 # set up object managing the cross spectral matrix computation
-ps = acoular.PowerSpectra( time_data=ts, block_size=128, window='Hanning' )
+ps = acoular.PowerSpectra( source=ts, block_size=128, window='Hanning' )
 # set up object managing the mapping grid
 rg = acoular.RectGrid( x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, \
 increment=0.01 )
@@ -176,5 +216,6 @@ interpolation='bicubic')
 colorbar()
 ```
 
-
 ![result](https://github.com/acoular/acoular/blob/master/docs/source/get_started/three_source_py3_colormap.png?raw=true)
+
+

{acoular-24.5 → acoular-24.10}/README.md

@@ -72,12 +72,17 @@ For more detailed installation instructions, see the [documentation](https://aco
 # Documentation and help
 Documentation is available [here](https://acoular.org) with a
 [getting started](https://acoular.org/get_started/index.html) section and
-[examples](https://acoular.org/examples/index.html).
+[examples](https://acoular.org/auto_examples/index.html).
 
 The Acoular [blog](https://acoular.github.io/blog/) contains some tutorials.
 
 If you discover problems with the Acoular software, please report them using the [issue tracker](https://github.com/acoular/acoular/issues) on GitHub. Please use the [Acoular discussions forum](https://github.com/acoular/acoular/discussions) for practical questions, discussions, and demos.
 
+# Contributing
+
+We are always happy to welcome new contributors to the project. 
+If you are interested in contributing, have a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file.
+
 # Example
 This reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band:
 
@@ -93,7 +98,7 @@ mg = acoular.MicGeom( from_file=micgeofile )
 # set up object managing the microphone array data (usually from measurement)
 ts = acoular.TimeSamples( name='three_sources.h5' )
 # set up object managing the cross spectral matrix computation
-ps = acoular.PowerSpectra( time_data=ts, block_size=128, window='Hanning' )
+ps = acoular.PowerSpectra( source=ts, block_size=128, window='Hanning' )
 # set up object managing the mapping grid
 rg = acoular.RectGrid( x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=0.3, \
 increment=0.01 )
@@ -113,5 +118,6 @@ interpolation='bicubic')
 colorbar()
 ```
 
-
 ![result](https://github.com/acoular/acoular/blob/master/docs/source/get_started/three_source_py3_colormap.png?raw=true)
+
+

{acoular-24.5 → acoular-24.10}/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-24.10/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-24.5 → acoular-24.10}/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"
 """