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

acoular/h5cache.py

@@ -32,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'

acoular/h5files.py

@@ -11,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:
@@ -38,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:
@@ -62,34 +125,42 @@ if config.have_tables:
         """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)
 
@@ -115,11 +186,13 @@ if config.have_tables:
         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]
@@ -133,43 +206,53 @@ if config.have_h5py:
         """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}'])
 
@@ -196,11 +279,13 @@ if config.have_h5py:
         #        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,
@@ -212,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':
@@ -220,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/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,17 +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'], removal_version='25.10'
-)
 class MicGeom(HasStrictTraits):
     """
     Provide the geometric arrangement of microphones in an array.
@@ -43,23 +39,22 @@ 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`
       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
@@ -142,32 +137,32 @@ class MicGeom(HasStrictTraits):
 
     #: Path to the XML file containing microphone positions. The XML file should have elements with
     #: the tag ``pos`` and attributes ``Name``, ``x``, ``y``, and ``z``.
-    file = Union(None, File(filter=['*.xml'], exists=True), desc='name of the xml file to import')
+    file = Union(None, File(filter=['*.xml'], exists=True))
 
     #: 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. 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')
+    #: 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))
 
     #: 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')
+    #: All coordinates are in meters by default (:ref:`see here <units_note_microphones>`).
+    pos = Property(depends_on=['pos_total', 'invalid_channels'])
 
     #: List of indices indicating microphones to be excluded from calculations and results.
     #: Default is ``[]``.
-    invalid_channels = List(int, desc='list of invalid channels')
+    invalid_channels = List(int)
 
     #: Number of valid microphones in the array. (read-only)
-    num_mics = Property(depends_on=['pos'], desc='number of microphones in the geometry')
+    num_mics = Property(depends_on=['pos'])
 
     #: The geometric center of the array, calculated as the arithmetic mean of the positions of all
     #: valid microphones. (read-only)
-    center = Property(depends_on=['pos'], desc='array center')
+    center = Property(depends_on=['pos'])
 
     #: The maximum distance between any two valid microphones in the array. (read-only)
-    aperture = Property(depends_on=['pos'], desc='array aperture')
+    aperture = Property(depends_on=['pos'])
 
     #: A unique identifier for the geometry, based on its properties. (read-only)
     digest = Property(depends_on=['pos'])
@@ -181,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):
@@ -190,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
@@ -202,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``,
@@ -237,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):
         """
@@ -266,8 +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 (see
-          :ref:`notes <units_note_micophones>`).
+        - All coordinates (x, y, z) are exported in meters by default (:ref:`see here
+          <units_note_microphones>`).
         """
         filepath = Path(filename)
         basename = filepath.stem
@@ -275,6 +270,6 @@ class MicGeom(HasStrictTraits):
             f.write(f'<?xml version="1.1" encoding="utf-8"?><MicArray name="{basename}">\n')
             for i in range(self.pos.shape[-1]):
                 f.write(
-                    f'  <pos Name="Point {i+1}" x="{self.pos[0, i]}" y="{self.pos[1, i]}" z="{self.pos[2, i]}"/>\n',
+                    f'  <pos Name="Point {i + 1}" x="{self.pos[0, i]}" y="{self.pos[1, i]}" z="{self.pos[2, i]}"/>\n',
                 )
             f.write('</MicArray>')

acoular/process.py

@@ -19,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
@@ -49,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.
     """
 
@@ -63,9 +62,6 @@ class LockedGenerator:
             return self.it.__next__()
 
 
-@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.
@@ -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
@@ -120,7 +116,7 @@ class Average(InOut):
 
     #: The number of samples (time domain source) or snapshots (frequency domain source)
     #: to average over. Default is ``64``.
-    num_per_average = Int(64, desc='number of samples/snapshots to average over')
+    num_per_average = Int(64)
 
     #: The sampling frequency of the output signal. It is set automatically as
     #: (:attr:`~acoular.base.Generator.sample_freq` ``/`` :attr:`num_per_average`).
@@ -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
     --------
@@ -483,7 +479,6 @@ class SampleSplitter(InOut):
     buffer_overflow_treatment = Dict(
         key_trait=Instance(Generator),
         value_trait=Enum('error', 'warning', 'none'),
-        desc='defines buffer overflow behaviour.',
     )
 
     # A shadow trait to monitor if source deliver samples or is empty.
@@ -542,8 +537,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)
@@ -732,7 +727,7 @@ class SamplesBuffer(InOut):
     """  # noqa: W505
 
     #: The number of samples that the buffer can hold.
-    length = Int(desc='number of samples that fit in the buffer')
+    length = Int()
 
     #: The number of samples per block to obtain from the source. If set to ``None``, the number of
     #: samples will be determined by the ``num`` argument of the :meth:`result` method.
@@ -740,7 +735,6 @@ class SamplesBuffer(InOut):
         None,
         Int(),
         default_value=None,
-        desc='number of samples to return from the source. If "None", use "num" argument of result method',
     )
 
     #: The number of samples to return from the buffer. If set to ``None``, the number of
@@ -749,7 +743,6 @@ class SamplesBuffer(InOut):
         None,
         Int(),
         default_value=None,
-        desc="number of samples to return from the buffer. If 'None', use 'num' argument of result method",
     )
 
     #: Index shift value for the buffer.
@@ -759,26 +752,22 @@ class SamplesBuffer(InOut):
     #:   samples.
     shift_index_by = Enum(
         ('result_num', 'num'),
-        desc=(
-            'index shift value for the buffer. If "result_num", use "result_num" trait.'
-            ' If "num", use "num" argument of result method'
-        ),
     )
 
     #: The current filling level of the buffer, i.e., how many samples are currently available.
-    level = Property(desc='current filling level of buffer')
+    level = Property()
 
     #: The data type of the elements in the buffer.
-    dtype = Any(desc='data type of the buffer')
+    dtype = Any()
 
     # Flag indicating if the source is empty (for internal use).
-    _empty_source = Bool(False, desc='flag to indicate that the source is empty')
+    _empty_source = Bool(False)
 
     # The actual buffer holding the samples for processing.
-    _buffer = Array(shape=(None, None), desc='buffer for block processing')
+    _buffer = Array(shape=(None, None))
 
     # The current index position in the buffer.
-    _index = Int(desc='current index in buffer')
+    _index = Int()
 
     def _get_level(self):
         return self._buffer.shape[0] - self._index

acoular/sdinput.py

@@ -14,17 +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'},
-    removal_version='25.10',
-)
 class SoundDeviceSamplesGenerator(SamplesGenerator):
     """Controller for sound card hardware using sounddevice library.
 
@@ -40,36 +35,36 @@ class SoundDeviceSamplesGenerator(SamplesGenerator):
             raise ImportError(msg)
 
     #: input device index, refers to sounddevice list
-    device = Int(0, desc='input device index')
+    device = Int(0)
 
     #: Number of input channels, maximum depends on device
-    num_channels = Int(1, desc='number of analog input channels that collects data')
+    num_channels = Int(1)
 
     #: Number of samples to collect; defaults to -1. If is set to -1 device collects until user
     # breaks streaming by setting Trait: collect_samples = False.
-    num_samples = Int(-1, desc='number of samples to collect')
+    num_samples = Int(-1)
 
     #: Indicates if samples are collected, helper trait to break result loop
-    collect_samples = Bool(True, desc='Indicates if samples are collected')
+    collect_samples = Bool(True)
 
     #: Sampling frequency of the signal, changes with sinusdevices
-    sample_freq = Property(desc='sampling frequency')
+    sample_freq = Property()
 
     _sample_freq = Float(default_value=None)
 
     #: Datatype (resolution) of the signal, used as `dtype` in a sd `Stream` object
-    precision = Enum('float32', 'float16', 'int32', 'int16', 'int8', 'uint8', desc='precision (resolution) of signal')
+    precision = Enum('float32', 'float16', 'int32', 'int16', 'int8', 'uint8')
 
     #: Indicates that the sounddevice buffer has overflown
-    overflow = Bool(False, desc='Indicates if sounddevice buffer overflow')
+    overflow = Bool(False)
 
     #: Indicates that the stream is collecting samples
-    running = Bool(False, desc='Indicates that the stream is collecting samples')
+    running = Bool(False)
 
     #: The sounddevice InputStream object for inspection
     stream = Any
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['device', 'num_channels', 'num_samples'])
 
     @cached_property