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

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
@@ -31,23 +32,27 @@ class HDF5Cache(HasStrictTraits):
             pass
 
     def close_cachefile(self, cachefile):
+        """Close a cache file and remove it from the reference counter."""
         self.open_file_reference.pop(Path(cachefile.filename))
         cachefile.close()
 
     def get_open_cachefiles(self):
+        """Get an iterator over all open cache files."""
         try:
             return self.open_files.itervalues()
         except AttributeError:
             return iter(self.open_files.values())
 
     def close_unreferenced_cachefiles(self):
+        """Close cache files that are no longer referenced by any objects."""
         for cachefile in self.get_open_cachefiles():
             if not self.is_reference_existent(cachefile):
                 self.close_cachefile(cachefile)
 
     def is_reference_existent(self, file):
+        """Check if a file object still has active references."""
         exist_flag = False
-        # inspect all refererres to the file object
+        # inspect all referrers to the file object
         gc.collect()  # clear garbage before collecting referrers
         for ref in gc.get_referrers(file):
             # does the file object have a referrer that has a 'h5f'
@@ -92,10 +97,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
 
 
@@ -9,25 +11,88 @@ class H5FileBase:
     """Base class for File objects that handle writing and reading of .h5 files."""
 
     def create_extendable_array(self, nodename, shape, precision, group=None):
-        pass
+        """
+        Create an extendable array in the HDF5 file.
+
+        Parameters
+        ----------
+        nodename : :class:`str`
+            Name of the node (dataset) to create in the HDF5 file.
+        shape : :class:`tuple` of :class:`int`
+            Shape of the array to be created.
+        precision : :class:`str`
+            Data type/precision of the array (e.g., 'float32', 'int16').
+        group : object, optional
+            Group in which to create the array. If None, the root group is used.
+        """
 
     def get_data_by_reference(self, nodename, group=None):
-        pass
+        """
+        Get data by reference from the HDF5 file.
+
+        Parameters
+        ----------
+        nodename : :class:`str`
+            Name of the node (dataset or group) to retrieve from the HDF5 file.
+        group : object, optional
+            The parent group in which to look for the node. If None, the root group is used.
+
+        Returns
+        -------
+        object
+            A reference to the requested node (e.g., a dataset or group object) in the HDF5 file.
+        """
 
     def set_node_attribute(self, node, attrname, value):
-        pass
+        """
+        Set an attribute on a node.
+
+        Parameters
+        ----------
+        node : object
+            The node (e.g., group or dataset) to which the attribute will be set.
+        attrname : :class:`str`
+            The name of the attribute to set.
+        value : any
+            The value to assign to the attribute.
+        """
 
     def get_node_attribute(self, node, attrname):
-        pass
+        """
+        Get an attribute from a node.
+
+        Parameters
+        ----------
+        node : object
+            The node (e.g., group or dataset) from which to retrieve the attribute.
+        attrname : :class:`str`
+            The name of the attribute to retrieve.
+
+        Returns
+        -------
+        object
+            The value of the specified attribute.
+        """
 
     def append_data(self, node, data):
-        pass
+        """
+        Append data to an existing node.
+
+        Parameters
+        ----------
+        node : object
+            The node (e.g., array or dataset) in the HDF5 file to which data will be appended.
+            The expected type depends on the backend (e.g., PyTables node or h5py dataset).
+        data : array-like
+            The data to append. Should be compatible in shape and type with the existing node.
+            The format and type must match the node's requirements.
+        """
 
     def remove_data(self, nodename):
-        pass
+        """Remove data from the HDF5 file."""
 
     def create_new_group(self, name, group=None):
-        pass
+        """Create a new group in the HDF5 file."""
 
 
 class H5CacheFileBase:
@@ -36,10 +101,10 @@ class H5CacheFileBase:
     compression_filter = None
 
     def is_cached(self, nodename, group=None):
-        pass
+        """Check if data is cached in the HDF5 file."""
 
     def create_compressible_array(self, nodename, shape, precision, group=None):
-        pass
+        """Create a compressible array in the HDF5 cache file."""
 
 
 if config.have_tables:
@@ -57,35 +122,45 @@ if config.have_tables:
     }
 
     class H5FileTables(H5FileBase, tables.File):
+        """Hdf5 File based on PyTables."""
+
         def create_extendable_array(self, nodename, shape, precision, group=None):
+            """Create an extendable array using PyTables."""
             if not group:
                 group = self.root
             atom = precision_to_atom[precision]
             self.create_earray(group, nodename, atom, shape)
 
         def get_data_by_reference(self, nodename, group=None):
+            """Get data by reference using PyTables."""
             if not group:
                 group = self.root
             return self.get_node(group, nodename)
 
         def set_node_attribute(self, node, attrname, value):
+            """Set an attribute on a PyTables node."""
             node.set_attr(attrname, value)
 
         def get_node_attribute(self, node, attrname):
+            """Get an attribute from a PyTables node."""
             return node._v_attrs[attrname]  # noqa: SLF001
 
         def append_data(self, node, data):
+            """Append data to a PyTables node."""
             node.append(data)
 
         def remove_data(self, nodename):
+            """Remove data from PyTables file."""
             self.remove_node('/', nodename, recursive=True)
 
         def create_new_group(self, name, group=None):
+            """Create a new group in PyTables file."""
             if not group:
                 group = self.root
             return self.create_group(group, name)
 
         def get_child_nodes(self, nodename):
+            """Get child nodes from a PyTables group."""
             for childnode in self.list_nodes(nodename):
                 yield (childnode.name, childnode)
 
@@ -106,14 +181,18 @@ 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):
+            """Check if data is cached in PyTables file."""
             if not group:
                 group = self.root
             return nodename in group
 
         def create_compressible_array(self, nodename, shape, precision, group=None):
+            """Create a compressible array in PyTables cache file."""
             if not group:
                 group = self.root
             atom = precision_to_atom[precision]
@@ -124,44 +203,56 @@ 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):
+            """Get the in-file path for h5py operations."""
             if not group:
                 return '/' + nodename
             return group + '/' + nodename
 
         def create_array(self, where, name, obj):
+            """Create an array in h5py file."""
             self.create_dataset(f'{where}/{name}', data=obj)
 
         def create_extendable_array(self, nodename, shape, precision, group=None):
+            """Create an extendable array using h5py."""
             in_file_path = self._get_in_file_path(nodename, group)
             self.create_dataset(in_file_path, shape=shape, dtype=precision, maxshape=(None, shape[1]))
 
         def get_data_by_reference(self, nodename, group=None):
+            """Get data by reference using h5py."""
             in_file_path = self._get_in_file_path(nodename, group)
             return self[in_file_path]
 
         def set_node_attribute(self, node, attrname, value):
+            """Set an attribute on an h5py node."""
             node.attrs[attrname] = value
 
         def get_node_attribute(self, node, attrname):
+            """Get an attribute from an h5py node."""
             return node.attrs[attrname]
 
         def append_data(self, node, data):
+            """Append data to an h5py dataset."""
             old_shape = node.shape
             new_shape = (old_shape[0] + data.shape[0], data.shape[1])
             node.resize(new_shape)
             node[old_shape[0] : new_shape[0], :] = data
 
         def remove_data(self, nodename, group=None):
+            """Remove data from h5py file."""
             in_file_path = self._get_in_file_path(nodename, group)
             del self[in_file_path]
 
         def create_new_group(self, name, group=None):
+            """Create a new group in h5py file."""
             in_file_path = self._get_in_file_path(name, group)
             self.create_group(in_file_path)
             return in_file_path
 
         def get_child_nodes(self, nodename):
+            """Get child nodes from an h5py group."""
             for childnode in self[nodename]:
                 yield (childnode, self[f'{nodename}/{childnode}'])
 
@@ -182,15 +273,19 @@ if config.have_h5py:
             return result
 
     class H5CacheFileH5py(H5CacheFileBase, H5FileH5py):
+        """Hdf5 Cache File based on h5py."""
+
         compression_filter = 'lzf'
         #        compression_filter = 'blosc' # unavailable...
 
         def is_cached(self, nodename, group=None):
+            """Check if data is cached in h5py file."""
             if not group:
                 group = '/'
             return group + nodename in self
 
         def create_compressible_array(self, nodename, shape, precision, group=None):
+            """Create a compressible array in h5py cache file."""
             in_file_path = self._get_in_file_path(nodename, group)
             self.create_dataset(
                 in_file_path,
@@ -202,6 +297,7 @@ if config.have_h5py:
 
 
 def _get_h5file_class():
+    """Get the appropriate H5File class based on configuration."""
     if config.h5library in ['pytables', 'tables']:
         return H5FileTables
     if config.h5library == 'h5py':
@@ -210,6 +306,7 @@ def _get_h5file_class():
 
 
 def _get_cachefile_class():
+    """Get the appropriate H5CacheFile class based on configuration."""
     if config.h5library in ['pytables', 'tables']:
         return H5CacheFileTables
     if config.h5library == 'h5py':

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

@@ -14,7 +14,7 @@ Implements support for array microphone arrangements.
 import xml.dom.minidom
 from pathlib import Path
 
-from numpy import array, average
+import numpy as np
 from scipy.spatial.distance import cdist
 from traits.api import (
     CArray,
@@ -24,15 +24,13 @@ from traits.api import (
     Property,
     Union,
     cached_property,
-    on_trait_change,
+    observe,
 )
 
 # acoular imports
-from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'mpos_tot': 'pos_total', 'mpos': 'pos', 'from_file': 'file'}, read_only=['mpos'])
 class MicGeom(HasStrictTraits):
     """
     Provide the geometric arrangement of microphones in an array.
@@ -41,6 +39,16 @@ class MicGeom(HasStrictTraits):
     microphone array. The positions can be read from an XML file or set programmatically. Invalid
     microphones can be excluded by specifying their indices via :attr:`invalid_channels`.
 
+    .. _units_note_microphones:
+    .. admonition:: Unit of length
+
+      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.
+
     Notes
     -----
     - The microphone geometry as in :attr:`total_pos` is automatically changed if the :attr:`file`
@@ -133,11 +141,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
+    #: (:ref:`see here <units_note_microphones>`).
     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 (:ref:`see here <units_note_microphones>`).
     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.
@@ -166,7 +176,7 @@ class MicGeom(HasStrictTraits):
         if len(self.invalid_channels) == 0:
             return self.pos_total
         allr = [i for i in range(self.pos_total.shape[-1]) if i not in self.invalid_channels]
-        return self.pos_total[:, array(allr)]
+        return self.pos_total[:, np.array(allr)]
 
     @cached_property
     def _get_num_mics(self):
@@ -175,7 +185,7 @@ class MicGeom(HasStrictTraits):
     @cached_property
     def _get_center(self):
         if self.pos.any():
-            center = average(self.pos, axis=1)
+            center = np.average(self.pos, axis=1)
             # set very small values to zero
             center[abs(center) < 1e-16] = 0.0
             return center
@@ -187,8 +197,8 @@ class MicGeom(HasStrictTraits):
             return cdist(self.pos.T, self.pos.T).max()
         return None
 
-    @on_trait_change('file')
-    def _import_mpos(self):
+    @observe('file')
+    def _import_mpos(self, event):  # noqa ARG002
         # Import the microphone positions from an XML file.
         #
         # This method parses the XML file specified in :attr:`file` and extracts the ``x``, ``y``,
@@ -222,7 +232,7 @@ class MicGeom(HasStrictTraits):
         for el in doc.getElementsByTagName('pos'):
             names.append(el.getAttribute('Name'))
             xyz.append([float(el.getAttribute(a)) for a in 'xyz'])
-        self.pos_total = array(xyz, 'd').swapaxes(0, 1)
+        self.pos_total = np.array(xyz, 'd').swapaxes(0, 1)
 
     def export_mpos(self, filename):
         """
@@ -251,6 +261,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 (:ref:`see here
+          <units_note_microphones>`).
         """
         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
 """
 
@@ -21,12 +19,11 @@ from inspect import currentframe
 from warnings import warn
 
 import numpy as np
-from traits.api import Any, Array, Bool, Dict, Enum, Instance, Int, Property, Union, cached_property, on_trait_change
+from traits.api import Any, Array, Bool, Dict, Enum, Instance, Int, Property, Union, cached_property, observe
 
 # acoular imports
 from .base import Generator, InOut
 from .configuration import config
-from .deprecation import deprecated_alias
 from .h5cache import H5cache
 from .h5files import H5CacheFileBase
 from .internal import digest
@@ -51,7 +48,7 @@ class LockedGenerator:
 
     See Also
     --------
-    :class:`acoular.process.SampleSplitter` :
+    :class:`~acoular.process.SampleSplitter` :
         Distribute data from a source to several following objects in a block-wise manner.
     """
 
@@ -65,7 +62,6 @@ class LockedGenerator:
             return self.it.__next__()
 
 
-@deprecated_alias({'naverage': 'num_per_average', 'numsamples': 'num_samples'}, read_only=['numsamples'])
 class Average(InOut):
     """
     Calculate the average across consecutive time samples or frequency snapshots.
@@ -80,7 +76,7 @@ class Average(InOut):
 
     See Also
     --------
-    :class:`acoular.base.InOut` :
+    :class:`~acoular.base.InOut` :
         Receive data from any source domain and return signals in the same domain.
 
     Examples
@@ -214,8 +210,8 @@ class Cache(InOut):
 
     See Also
     --------
-    :class:`acoular.base.InOut` : Receive data from any source domain and return signals in the same
-                                  domain.
+    :class:`~acoular.base.InOut` : Receive data from any source domain and return signals in the
+                                   same domain.
 
     Examples
     --------
@@ -542,8 +538,8 @@ class SampleSplitter(InOut):
         next_block = next(self._source_generator)
         [self.block_buffer[obj].appendleft(next_block) for obj in self.block_buffer]
 
-    @on_trait_change('buffer_size')
-    def _change_buffer_size(self):  #
+    @observe('buffer_size')
+    def _change_buffer_size(self, event):  # noqa: ARG002
         for obj in self.block_buffer:
             self._remove_block_buffer(obj)
             self._create_block_buffer(obj)
@@ -675,48 +671,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

@@ -14,14 +14,12 @@ from traits.api import Any, Bool, Enum, Float, Int, Property, cached_property, o
 # acoular imports
 from .base import SamplesGenerator
 from .configuration import config
-from .deprecation import deprecated_alias
 from .internal import digest
 
 if config.have_sounddevice:
     import sounddevice as sd
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples', 'collectsamples': 'collect_samples'})
 class SoundDeviceSamplesGenerator(SamplesGenerator):
     """Controller for sound card hardware using sounddevice library.
 
@@ -87,15 +85,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
         ----------