acoular 25.4__py3-none-any.whl → 25.7__py3-none-any.whl

acoular/fprocess.py

@@ -11,11 +11,8 @@ Implements blockwise processing methods in the frequency domain.
     IRFFT
     AutoPowerSpectra
     CrossPowerSpectra
-    FFTSpectra
 """
 
-from warnings import warn
-
 import numpy as np
 from scipy import fft
 from traits.api import Bool, CArray, Enum, Instance, Int, Property, Union, cached_property
@@ -29,7 +26,7 @@ from .process import SamplesBuffer
 from .spectra import BaseSpectra
 
 
-@deprecated_alias({'numfreqs': 'num_freqs', 'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numfreqs': 'num_freqs', 'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class RFFT(BaseSpectra, SpectraOut):
     """
     Compute the one-sided Fast Fourier Transform (FFT) for real-valued multichannel time data.
@@ -170,7 +167,7 @@ class RFFT(BaseSpectra, SpectraOut):
             yield fftdata[: j + 1]
 
 
-@deprecated_alias({'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class IRFFT(TimeOut):
     """
     Perform the inverse Fast Fourier Transform (IFFT) for one-sided multi-channel spectra.
@@ -350,7 +347,7 @@ class AutoPowerSpectra(SpectraOut):
             yield ((temp * temp.conjugate()).real * scale).astype(self.precision)
 
 
-@deprecated_alias({'numchannels': 'num_channels'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels'}, read_only=True, removal_version='25.10')
 class CrossPowerSpectra(AutoPowerSpectra):
     """
     Compute the complex-valued auto- and cross-power spectra from frequency-domain data.
@@ -450,29 +447,3 @@ class CrossPowerSpectra(AutoPowerSpectra):
                     csm_flat[i] = csm_lower[:, :nc].reshape(-1)
                 csm_upper[...] = 0  # calcCSM adds cumulative
             yield csm_flat[: i + 1] * scale
-
-
-class FFTSpectra(RFFT):
-    """
-    Provide the one-sided Fast Fourier Transform (FFT) for multichannel time data.
-
-    .. deprecated:: 24.10
-        The :class:`~acoular.fprocess.FFTSpectra` class is deprecated and will be removed
-        in Acoular version 25.07. Please use :class:`~acoular.fprocess.RFFT` instead.
-
-    Alias for the :class:`~acoular.fprocess.RFFT` class, which computes the one-sided
-    Fast Fourier Transform (FFT) for multichannel time data.
-
-    Warnings
-    --------
-    This class remains temporarily available for backward compatibility but should not be used in
-    new implementations.
-    """
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        warn(
-            'Using FFTSpectra is deprecated and will be removed in Acoular version 25.07. Use class RFFT instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )

acoular/grids.py

@@ -28,6 +28,7 @@ Implement support for multidimensional grids and integration sectors.
 # imports from other packages
 import xml.dom.minidom
 from abc import abstractmethod
+from pathlib import Path
 
 from numpy import (
     absolute,
@@ -301,7 +302,7 @@ class Polygon:
         return mindst
 
 
-@deprecated_alias({'gpos': 'pos'})
+@deprecated_alias({'gpos': 'pos'}, removal_version='25.10')
 class Grid(ABCHasStrictTraits):
     """
     Abstract base class for grid geometries.
@@ -309,6 +310,16 @@ class Grid(ABCHasStrictTraits):
     This class defines a common interface for all grid geometries and provides tools to query grid
     properties and related data. It is intended to serve as a base class for specialized grid
     implementations and should not be instantiated directly as it lacks concrete functionality.
+
+    .. _units_note_grids:
+
+    Unit System
+    -----------
+    The source code is agnostic to the unit of length. The positions' coordinates are assumed to be
+    in meters. This is consistent with the standard :class:`~acoular.environments.Environment` class
+    which uses the speed of sound at 20°C at sea level under standard atmosphere pressure in m/s.
+    If the positions' coordinates are provided in a unit other than meter, it is advisable to change
+    the :attr:`~acoular.environments.Environment.c` attribute to match the given unit.
     """
 
     #: The total number of grid points. This property is automatically calculated based on other
@@ -321,6 +332,7 @@ class Grid(ABCHasStrictTraits):
 
     #: The grid positions represented as a (3, :attr:`size`) array of :class:`floats<float>`.
     #: (read-only)
+    #: All positions' coordinates are in meters by default (see :ref:`notes <units_note_grids>`).
     pos = Property(desc='x, y, z positions of grid points')
 
     #: A unique identifier for the grid, based on its properties. (read-only)
@@ -375,8 +387,77 @@ class Grid(ABCHasStrictTraits):
         # return indices of "True" entries
         return where(xyi)
 
+    def export_gpos(self, filename):
+        """
+        Export the grid positions to an XML file.
+
+        This method generates an XML file containing the positions of all grid points.
+        Each point is represented by a ``<pos>`` element with ``Name``, ``x``, ``y``, and ``z``
+        attributes. The generated XML is formatted to match the structure required for importing
+        into the :class:`ImportGrid` class.
+
+        Parameters
+        ----------
+        filename : :class:`str`
+            The path to the file to which the grid positions will be written. The file
+            extension must be ``.xml``.
+
+        Raises
+        ------
+        :obj:`OSError`
+            If the file cannot be written due to permissions issues or invalid file paths.
+
+        Notes
+        -----
+        - The file will be saved in UTF-8 encoding.
+        - The ``Name`` attribute for each point is set as ``"Point {i+1}"``, where ``i`` is the
+          index of the grid point.
+        - If subgrids are defined, they will be included as the ``subgrid`` attribute.
+
+        Examples
+        --------
+        Export a grid with 100 points to an XML file:
+
+        >>> import acoular as ac
+        >>> import numpy as np
+        >>> grid = ac.ImportGrid()
+        >>> # Create some grid points
+        >>> points = np.arange(9).reshape(3, 3)
+        >>> grid.pos = points
+        >>> grid.export_gpos('grid_points.xml')  # doctest: +SKIP
+
+        The generated ``grid_points.xml`` file will look like this:
+
+        .. code-block:: xml
 
-@deprecated_alias({'gpos': 'pos'}, read_only=True)
+            <?xml version="1.1" encoding="utf-8"?><Grid name="grid_points">
+              <pos Name="Point 1" x="0" y="1" z="2"/>
+              <pos Name="Point 2" x="3" y="4" z="5"/>
+              <pos Name="Point 3" x="6" y="7" z="8"/>
+            </Grid>
+        """
+        filepath = Path(filename)
+        basename = filepath.stem
+        with filepath.open('w', encoding='utf-8') as f:
+            f.write(f'<?xml version="1.1" encoding="utf-8"?><Grid name="{basename}">\n')
+            for i in range(self.pos.shape[-1]):
+                has_subgrids = hasattr(self, 'subgrids') and len(self.subgrids) > i
+                subgrid_attr = f'subgrid="{self.subgrids[i]}"' if has_subgrids else ''
+                pos_str = ' '.join(
+                    [
+                        '  <pos',
+                        f'Name="Point {i+1}"',
+                        f'x="{self.pos[0, i]}"',
+                        f'y="{self.pos[1, i]}"',
+                        f'z="{self.pos[2, i]}"',
+                        f'{subgrid_attr}/>\n',
+                    ]
+                )
+                f.write(pos_str)
+            f.write('</Grid>')
+
+
+@deprecated_alias({'gpos': 'pos'}, read_only=True, removal_version='25.10')
 class RectGrid(Grid):
     """
     Provides a 2D Cartesian grid for beamforming results.
@@ -409,6 +490,9 @@ class RectGrid(Grid):
     #: Number of grid points along y-axis. (read-only)
     nysteps = Property(desc='number of grid points along y-axis')
 
+    #: The grid's extension in :obj:`matplotlib.pyplot.imshow` compatible form. (read-only)
+    extent = Property(desc='grid extent as (x_min, x_max, y_min, y_max)')
+
     #: A unique identifier for the grid, based on its properties. (read-only)
     digest = Property(
         depends_on=['x_min', 'x_max', 'y_min', 'y_max', 'z', 'increment'],
@@ -450,6 +534,56 @@ class RectGrid(Grid):
         bpos.resize((3, self.size))
         return bpos
 
+    @property_depends_on(['x_min', 'x_max', 'y_min', 'y_max'])
+    def _get_extent(self):
+        # Return the grid's extension in :obj:`matplotlib.pyplot.imshow` compatible form.
+        #
+        # Returns
+        # -------
+        # :class:`tuple` of :class:`floats<float>`
+        #     (:attr:`x_min`, :attr:`x_max`, :attr:`y_min`, :attr:`y_max`) representing the grid's
+        #     extent.
+        #
+        # Notes
+        # -----
+        # This property is intended for use with the ``extent`` parameter of
+        # :obj:`matplotlib.pyplot.imshow`.
+        #
+        # Examples
+        # --------
+        # >>> from acoular import RectGrid
+        # >>> grid = RectGrid()
+        # >>> grid.y_min = -5
+        # >>> grid.y_max = 5
+        # >>> grid.extent
+        # (-1.0, 1.0, -5.0, 5.0)
+        return (self.x_min, self.x_max, self.y_min, self.y_max)
+
+    def extend(self):
+        """
+        Return the grid's extension in :obj:`matplotlib.pyplot.imshow` compatible form.
+
+        Returns
+        -------
+        :class:`tuple` of :class:`floats<float>`
+            (:attr:`x_min`, :attr:`x_max`, :attr:`y_min`, :attr:`y_max`) representing the grid's
+            extent.
+
+        Notes
+        -----
+        This method is deprecated. Use the :attr:`extent` property instead.
+        """
+        import warnings
+
+        msg = ' '.join(
+            [
+                "Deprecated use of 'extend' method (will be removed in version 26.04).",
+                "Please use the 'extent' trait instead.",
+            ]
+        )
+        warnings.warn(msg, DeprecationWarning, stacklevel=2)
+        return self.extent
+
     def index(self, x, y):
         """
         Find the indices of a grid point near a given coordinate.
@@ -539,34 +673,6 @@ class RectGrid(Grid):
         return array(xis), array(yis)
         # return arange(self.size)[inds]
 
-    def extend(self):
-        """
-        Return the grid's extension in :obj:`matplotlib.pyplot.imshow` compatible form.
-
-        Returns
-        -------
-        :class:`tuple` of :class:`floats<float>`
-            (:attr:`x_min`, :attr:`x_max`, :attr:`y_min`, :attr:`y_max`) representing the grid's
-            extent.
-
-        Notes
-        -----
-        - ``pylab.imhow`` is the same as :obj:`matplotlib.pyplot.imshow`. It's only using a
-          different namespace.
-        - The return of the method is ment for the ``extent`` parameter of
-          :obj:`matplotlib.pyplot.imshow`.
-
-        Examples
-        --------
-        >>> from acoular import RectGrid
-        >>> grid = RectGrid()
-        >>> grid.y_min = -5
-        >>> grid.y_max = 5
-        >>> grid.extend()
-        (-1.0, 1.0, -5.0, 5.0)
-        """
-        return (self.x_min, self.x_max, self.y_min, self.y_max)
-
 
 class RectGrid3D(RectGrid):
     """
@@ -575,10 +681,10 @@ class RectGrid3D(RectGrid):
     The grid has cubic or nearly cubic cells. It is defined by lower and upper x-, y- and  z-limits.
     """
 
-    #: The lower z-limit that defines the grid. Default is ``-1``.
+    #: The lower z-limit that defines the grid. Default is ``-1.0``.
     z_min = Float(-1.0, desc='minimum  z-value')
 
-    #: The upper z-limit that defines the grid. Default is ``1``.
+    #: The upper z-limit that defines the grid. Default is ``1.0``.
     z_max = Float(1.0, desc='maximum  z-value')
 
     #: Number of grid points along x-axis. (read-only)
@@ -760,7 +866,7 @@ class RectGrid3D(RectGrid):
         return s_[xi1 : xi2 + 1], s_[yi1 : yi2 + 1], s_[zi1 : zi2 + 1]
 
 
-@deprecated_alias({'from_file': 'file', 'gpos_file': 'pos'})
+@deprecated_alias({'from_file': 'file', 'gpos_file': 'pos'}, removal_version='25.10')
 class ImportGrid(Grid):
     """
     Load a 3D grid from an XML file.
@@ -928,7 +1034,7 @@ class ImportGrid(Grid):
         self.subgrids = array(names)
 
 
-@deprecated_alias({'gpos': 'pos', 'numpoints': 'num_points'}, read_only=['gpos'])
+@deprecated_alias({'gpos': 'pos', 'numpoints': 'num_points'}, read_only=['gpos'], removal_version='25.10')
 class LineGrid(Grid):
     """
     Define a 3D grid for a line geometry.
@@ -976,8 +1082,9 @@ class LineGrid(Grid):
     #: are set. (read-only)
     size = Property(desc='overall number of grid points')
 
-    #: A (3, :attr:`size`) array containing the x, y, and z positions
-    #: of the grid points. (read-only)
+    #: A (3, :attr:`size`) array containing the x, y, and z positions of the grid points.
+    #: (read-only)
+    #: All positions' coordinates are in meters by default (see :ref:`notes <units_note_grids>`).
     pos = Property(desc='x, y, z positions of grid points')
 
     #: A unique identifier for the grid, based on its properties. (read-only)
@@ -1008,7 +1115,7 @@ class LineGrid(Grid):
         return pos.T
 
 
-@deprecated_alias({'gpos': 'pos'}, read_only=True)
+@deprecated_alias({'gpos': 'pos'}, read_only=True, removal_version='25.10')
 class MergeGrid(Grid):
     """
     Base class for merging multiple grid geometries.

acoular/h5cache.py

@@ -2,7 +2,8 @@
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
 
-# imports from other packages
+"""Implements a cache for HDF5 files used in Acoular."""
+
 import gc
 from pathlib import Path
 from weakref import WeakValueDictionary
@@ -92,10 +93,11 @@ class HDF5Cache(HasStrictTraits):
             return  # cachefile is not created in readonly mode
 
         if isinstance(obj.h5f, file_cls):
-            if Path(obj.h5f.filename).resolve() == filename:
+            h5filename = Path(obj.h5f.filename).resolve()
+            if h5filename == filename:
                 self.busy = False
                 return
-            self._decrease_file_reference_counter(obj.h5f.filename)
+            self._decrease_file_reference_counter(h5filename)
 
         if filename not in self.open_files:  # or tables.file._open_files.filenames
             if config.global_caching == 'readonly':

acoular/h5files.py

@@ -2,6 +2,8 @@
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
 
+"""Implements base classes for handling HDF5 files."""
+
 from .configuration import config
 
 
@@ -57,6 +59,8 @@ if config.have_tables:
     }
 
     class H5FileTables(H5FileBase, tables.File):
+        """Hdf5 File based on PyTables."""
+
         def create_extendable_array(self, nodename, shape, precision, group=None):
             if not group:
                 group = self.root
@@ -106,6 +110,8 @@ if config.have_tables:
             return result
 
     class H5CacheFileTables(H5FileTables, H5CacheFileBase):
+        """Hdf5 Cache File based on PyTables."""
+
         compression_filter = tables.Filters(complevel=5, complib='blosc')
 
         def is_cached(self, nodename, group=None):
@@ -124,6 +130,8 @@ if config.have_h5py:
     import h5py
 
     class H5FileH5py(H5FileBase, h5py.File):
+        """Hdf5 File based on h5py."""
+
         def _get_in_file_path(self, nodename, group=None):
             if not group:
                 return '/' + nodename
@@ -182,6 +190,8 @@ if config.have_h5py:
             return result
 
     class H5CacheFileH5py(H5CacheFileBase, H5FileH5py):
+        """Hdf5 Cache File based on h5py."""
+
         compression_filter = 'lzf'
         #        compression_filter = 'blosc' # unavailable...
 

acoular/internal.py

@@ -2,10 +2,13 @@
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
 
+"""Implements a digest function for caching of traits based on a unique identifier."""
+
 from hashlib import md5
 
 
 def digest(obj, name='digest'):
+    """Generate a unique digest for the given object based on its traits."""
     str_ = [str(obj.__class__).encode('UTF-8')]
     for do_ in obj.trait(name).depends_on:
         vobj = obj
@@ -19,6 +22,7 @@ def digest(obj, name='digest'):
 
 
 def ldigest(obj_list):
+    """Generate a unique digest for a list of objects based on their traits."""
     str_ = []
     for i in obj_list:
         str_.append(str(i.digest).encode('UTF-8'))

acoular/microphones.py

@@ -32,7 +32,9 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'])
+@deprecated_alias(
+    {'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'], removal_version='25.10'
+)
 class MicGeom(HasStrictTraits):
     """
     Provide the geometric arrangement of microphones in an array.
@@ -47,6 +49,17 @@ class MicGeom(HasStrictTraits):
       attribute is updated.
     - Small numerical values in the computed :attr:`center` are set to zero for numerical stability.
 
+    .. _units_note_microphones:
+
+    Unit System
+    -----------
+    The source code is agnostic to the unit of length. The microphone positions' coordinates are
+    assumed to be in meters. This is consistent with the standard
+    :class:`~acoular.environments.Environment` class which uses the speed of sound at 20°C at sea
+    level under standard atmosphere pressure in m/s. If the microphone positions' coordinates are
+    provided in a unit other than meter, it is advisable to change the
+    :attr:`~acoular.environments.Environment.c` attribute to match the given unit.
+
     Examples
     --------
     To set a microphone geomerty for ``n`` programmatically, first a ``(3,n)`` array is needed. In
@@ -133,11 +146,13 @@ class MicGeom(HasStrictTraits):
 
     #: Array containing the ``x, y, z`` positions of all microphones, including invalid ones, shape
     #: ``(3,`` :attr:`num_mics` ``)``. This is set automatically when :attr:`file` changes or
-    #: explicitly by assigning an array of floats.
+    #: explicitly by assigning an array of floats. All coordinates are in meters by default (see
+    #: :ref:`notes <units_note_micophones>`).
     pos_total = CArray(dtype=float, shape=(3, None), desc='x, y, z position of all microphones')
 
     #: Array containing the ``x, y, z`` positions of valid microphones (i.e., excluding those in
     #: :attr:`invalid_channels`), shape ``(3,`` :attr:`num_mics` ``)``. (read-only)
+    #: All coordinates are in meters by default (see :ref:`notes <units_note>`).
     pos = Property(depends_on=['pos_total', 'invalid_channels'], desc='x, y, z position of used microphones')
 
     #: List of indices indicating microphones to be excluded from calculations and results.
@@ -251,6 +266,8 @@ class MicGeom(HasStrictTraits):
           index of the microphone.
         - This method only exports the positions of the valid microphones (those not listed in
           :attr:`invalid_channels`).
+        - All coordinates (x, y, z) are exported in meters by default (see
+          :ref:`notes <units_note_micophones>`).
         """
         filepath = Path(filename)
         basename = filepath.stem

acoular/process.py

@@ -10,8 +10,6 @@ General purpose blockwise processing methods independent of the domain (time or
     Average
     Cache
     SampleSplitter
-    TimeAverage
-    TimeCache
     SamplesBuffer
 """
 
@@ -65,7 +63,9 @@ class LockedGenerator:
             return self.it.__next__()
 
 
-@deprecated_alias({'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'])
+@deprecated_alias(
+    {'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'], removal_version='25.10'
+)
 class Average(InOut):
     """
     Calculate the average across consecutive time samples or frequency snapshots.
@@ -675,48 +675,6 @@ class SampleSplitter(InOut):
             raise OSError(msg)
 
 
-class TimeAverage(Average):
-    """
-    Calculate the average of the signal.
-
-    .. deprecated:: 24.10
-        The use of :class:`~acoular.process.TimeAverage` is deprecated
-        and will be removed in Acoular version 25.07.
-        Please use :class:`~acoular.process.Average` instead for future compatibility.
-
-    Alias for :class:`~acoular.process.Average`.
-    """
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        warn(
-            'Using TimeAverage is deprecated and will be removed in Acoular version 25.07. Use Average instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
-class TimeCache(Cache):
-    """
-    Cache source signals in cache file.
-
-    .. deprecated:: 24.10
-        The use of :class:`~acoular.process.TimeCache` is deprecated
-        and will be removed in Acoular version 25.07.
-        Please use :class:`~acoular.process.Cache` instead for future compatibility.
-
-    Alias for :class:`~acoular.process.Cache`.
-    """
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        warn(
-            'Using TimeCache is deprecated and will be removed in Acoular version 25.07. Use Cache instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )
-
-
 class SamplesBuffer(InOut):
     """
     Handle buffering of samples from a source.

acoular/sdinput.py

@@ -21,7 +21,10 @@ if config.have_sounddevice:
     import sounddevice as sd
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples', 'collectsamples': 'collect_samples'})
+@deprecated_alias(
+    {'numchannels': 'num_channels', 'numsamples': 'num_samples', 'collectsamples': 'collect_samples'},
+    removal_version='25.10',
+)
 class SoundDeviceSamplesGenerator(SamplesGenerator):
     """Controller for sound card hardware using sounddevice library.
 
@@ -87,15 +90,20 @@ class SoundDeviceSamplesGenerator(SamplesGenerator):
         self._sample_freq = f
 
     def device_properties(self):
-        """Returns
+        """
+        Display the properties of the sounddevice input device.
+
+        Returns
         -------
         Dictionary of device properties according to sounddevice
         """
         return sd.query_devices(self.device)
 
     def result(self, num):
-        """Python generator that yields the output block-wise. Use at least a
-        block-size of one ring cache block.
+        """
+        Python generator that yields the output block-wise.
+
+        Use at least a block-size of one ring cache block.
 
         Parameters
         ----------

acoular/signals.py

@@ -43,7 +43,7 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'numsamples': 'num_samples'})
+@deprecated_alias({'numsamples': 'num_samples'}, removal_version='25.10')
 class SignalGenerator(ABCHasStrictTraits):
     """
     ABC for a simple one-channel signal generator.
@@ -556,7 +556,7 @@ class SineGenerator(PeriodicSignalGenerator):
         return self.amplitude * sin(2 * pi * self.freq * t + self.phase)
 
 
-@deprecated_alias({'rms': 'amplitude'})
+@deprecated_alias({'rms': 'amplitude'}, removal_version='25.10')
 class GenericSignalGenerator(SignalGenerator):
     """
     Generate signals from a :class:`~acoular.base.SamplesGenerator` or derived object.