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

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
@@ -146,13 +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. All coordinates are in meters by default (see
-    #: :ref:`notes <units_note_micophones>`).
+    #: 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 (see :ref:`notes <units_note>`).
+    #: 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.
@@ -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

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
@@ -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)

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.
 

acoular/signals.py

@@ -4,6 +4,12 @@
 """
 Implements signal generators for the simulation of acoustic sources.
 
+.. inheritance-diagram::
+                acoular.signals
+    :top-classes:
+                acoular.signals.SignalGenerator
+    :parts: 1
+
 .. autosummary::
     :toctree: generated/
 
@@ -21,8 +27,7 @@ Implements signal generators for the simulation of acoustic sources.
 from abc import abstractmethod
 from warnings import warn
 
-from numpy import arange, array, log, pi, repeat, sin, sqrt, tile, zeros
-from numpy.random import RandomState
+import numpy as np
 from scipy.signal import resample, sosfilt, tf2sos
 from traits.api import (
     ABCHasStrictTraits,
@@ -39,11 +44,9 @@ from traits.api import (
 
 # acoular imports
 from .base import SamplesGenerator
-from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'numsamples': 'num_samples'}, removal_version='25.10')
 class SignalGenerator(ABCHasStrictTraits):
     """
     ABC for a simple one-channel signal generator.
@@ -170,9 +173,9 @@ class NoiseGenerator(SignalGenerator):
 
     See Also
     --------
-    :class:`acoular.signals.PNoiseGenerator` : For pink noise generation.
-    :class:`acoular.signals.WNoiseGenerator` : For pink white generation.
-    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
+    :class:`~acoular.signals.PNoiseGenerator` : For pink noise generation.
+    :class:`~acoular.signals.WNoiseGenerator` : For pink white generation.
+    :class:`~acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
     """
 
     #: Root mean square (RMS) amplitude of the signal. For a point source,
@@ -211,8 +214,8 @@ class WNoiseGenerator(NoiseGenerator):
     --------
     :obj:`numpy.random.RandomState.standard_normal` :
         Used here to generate normally distributed noise.
-    :class:`acoular.signals.PNoiseGenerator` : For pink noise generation.
-    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
+    :class:`~acoular.signals.PNoiseGenerator` : For pink noise generation.
+    :class:`~acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
 
     Examples
     --------
@@ -260,7 +263,7 @@ class WNoiseGenerator(NoiseGenerator):
             A 1D array of floats containing the generated white noise signal.
             The length of the array is equal to :attr:`~SignalGenerator.num_samples`.
         """
-        rnd_gen = RandomState(self.seed)
+        rnd_gen = np.random.RandomState(self.seed)
         return self.rms * rnd_gen.standard_normal(self.num_samples)
 
 
@@ -278,8 +281,8 @@ class PNoiseGenerator(NoiseGenerator):
 
     See Also
     --------
-    :class:`acoular.signals.WNoiseGenerator` : For white noise generation.
-    :class:`acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
+    :class:`~acoular.signals.WNoiseGenerator` : For white noise generation.
+    :class:`~acoular.sources.UncorrelatedNoiseSource` : For per-channel noise generation.
 
     References
     ----------
@@ -320,26 +323,26 @@ class PNoiseGenerator(NoiseGenerator):
           simulation. If the specified depth exceeds the maximum possible value based on
           the number of samples, it is automatically adjusted, and a warning is printed.
         - The output signal is scaled to have the same overall level as white noise by dividing
-          the result by ``sqrt(depth + 1.5)``.
+          the result by ``np.sqrt(depth + 1.5)``.
         """
         nums = self.num_samples
         depth = self.depth
         # maximum depth depending on number of samples
-        max_depth = int(log(nums) / log(2))
+        max_depth = int(np.log(nums) / np.log(2))
 
         if depth > max_depth:
             depth = max_depth
             print(f'Pink noise filter depth set to maximum possible value of {max_depth:d}.')
 
-        rnd_gen = RandomState(self.seed)
+        rnd_gen = np.random.RandomState(self.seed)
         s = rnd_gen.standard_normal(nums)
         for _ in range(depth):
             ind = 2**_ - 1
             lind = nums - ind
             dind = 2 ** (_ + 1)
-            s[ind:] += repeat(rnd_gen.standard_normal(nums // dind + 1), dind)[:lind]
-        # divide by sqrt(depth+1.5) to get same overall level as white noise
-        return self.rms / sqrt(depth + 1.5) * s
+            s[ind:] += np.repeat(rnd_gen.standard_normal(nums // dind + 1), dind)[:lind]
+        # divide by np.sqrt(depth+1.5) to get same overall level as white noise
+        return self.rms / np.sqrt(depth + 1.5) * s
 
 
 class FiltWNoiseGenerator(WNoiseGenerator):
@@ -399,11 +402,11 @@ class FiltWNoiseGenerator(WNoiseGenerator):
 
     #: A :class:`numpy.ndarray` of autoregressive coefficients (denominator). Default is ``[]``,
     #: which results in no AR filtering (i.e., all-pole filter is ``[1.0]``).
-    ar = CArray(value=array([]), dtype=float, desc='autoregressive coefficients (coefficients of the denominator)')
+    ar = CArray(value=np.array([]), dtype=float, desc='autoregressive coefficients (coefficients of the denominator)')
 
     #: A :class:`numpy.ndarray` of moving-average coefficients (numerator). Default is ``[]``,
     #: which results in no MA filtering (i.e., all-zero filter is ``[1.0]``).
-    ma = CArray(value=array([]), dtype=float, desc='moving-average coefficients (coefficients of the numerator)')
+    ma = CArray(value=np.array([]), dtype=float, desc='moving-average coefficients (coefficients of the numerator)')
 
     #: A unique checksum identifier based on the object properties. (read-only)
     digest = Property(depends_on=['rms', 'seed', 'sample_freq', 'num_samples', 'ar', 'ma'])
@@ -432,7 +435,7 @@ class FiltWNoiseGenerator(WNoiseGenerator):
             if the input array is empty.
         """
         if coefficients.size == 0:
-            return array([1.0])
+            return np.array([1.0])
         return coefficients
 
     def signal(self):
@@ -450,7 +453,7 @@ class FiltWNoiseGenerator(WNoiseGenerator):
             An array representing the filtered white noise signal. The length of the returned array
             is equal to :attr:`the number of samples<SignalGenerator.num_samples>`.
         """
-        rnd_gen = RandomState(self.seed)
+        rnd_gen = np.random.RandomState(self.seed)
         ma = self.handle_empty_coefficients(self.ma)
         ar = self.handle_empty_coefficients(self.ar)
         sos = tf2sos(ma, ar)
@@ -552,11 +555,10 @@ class SineGenerator(PeriodicSignalGenerator):
         The generator supports high-frequency and high-resolution signals,
         limited by the Nyquist criterion.
         """
-        t = arange(self.num_samples, dtype=float) / self.sample_freq
-        return self.amplitude * sin(2 * pi * self.freq * t + self.phase)
+        t = np.arange(self.num_samples, dtype=float) / self.sample_freq
+        return self.amplitude * np.sin(2 * np.pi * self.freq * t + self.phase)
 
 
-@deprecated_alias({'rms': 'amplitude'}, removal_version='25.10')
 class GenericSignalGenerator(SignalGenerator):
     """
     Generate signals from a :class:`~acoular.base.SamplesGenerator` or derived object.
@@ -648,7 +650,7 @@ class GenericSignalGenerator(SignalGenerator):
                 stacklevel=2,
             )
         nums = self.num_samples
-        track = zeros(nums)
+        track = np.zeros(nums)
 
         # iterate through source generator to fill signal track
         for i, temp in enumerate(self.source.result(block)):
@@ -665,7 +667,7 @@ class GenericSignalGenerator(SignalGenerator):
             # fill up empty track with as many full source signals as possible
             nloops = nums // stop
             if nloops > 1:
-                track[stop : stop * nloops] = tile(track[:stop], nloops - 1)
+                track[stop : stop * nloops] = np.tile(track[:stop], nloops - 1)
             # fill up remaining empty track
             res = nums % stop  # last part of unfinished loop
             if res > 0: