acoular 24.5__py3-none-any.whl → 24.7__py3-none-any.whl

acoular/grids.py

@@ -550,8 +550,8 @@ class RectGrid3D(RectGrid):
         if isscalar(increment):
             try:
                 self._increment = absolute(float(increment))
-            except:
-                raise TraitError(args=self, name='increment', info='Float or CArray(3,)', value=increment)
+            except ValueError as ve:
+                raise TraitError(args=self, name='increment', info='Float or CArray(3,)', value=increment) from ve
         elif len(increment) == 3:
             self._increment = array(increment, dtype=float)
         else:
@@ -559,14 +559,14 @@ class RectGrid3D(RectGrid):
 
     # Respective increments in x,y, and z-direction (in m).
     # Deprecated: Use :attr:`~RectGrid.increment` for this functionality
-    increment3D = Property(desc='3D step sizes')
+    increment3D = Property(desc='3D step sizes')  # noqa N815
 
-    def _get_increment3D(self):
+    def _get_increment3D(self):  # noqa N802
         if isscalar(self._increment):
             return array([self._increment, self._increment, self._increment])
         return self._increment
 
-    def _set_increment3D(self, inc):
+    def _set_increment3D(self, inc):  # noqa N802
         if not isscalar(inc) and len(inc) == 3:
             self._increment = array(inc, dtype=float)
         else:

acoular/h5cache.py

@@ -13,7 +13,7 @@ from .configuration import Config, config
 from .h5files import _get_cachefile_class
 
 
-class H5cache_class(HasPrivateTraits):
+class HDF5Cache(HasPrivateTraits):
     """Cache class that handles opening and closing 'tables.File' objects."""
 
     config = Instance(Config)
@@ -24,23 +24,23 @@ class H5cache_class(HasPrivateTraits):
 
     open_files = WeakValueDictionary()
 
-    openFileReferenceCount = Dict()
+    open_file_reference = Dict()
 
     def _idle_if_busy(self):
         while self.busy:
             pass
 
-    def open_cachefile(self, cacheFileName, mode):
-        File = _get_cachefile_class()
-        return File(path.join(self.cache_dir, cacheFileName), mode)
+    def open_cachefile(self, filename, mode):
+        file = _get_cachefile_class()
+        return file(path.join(self.cache_dir, filename), mode)
 
     def close_cachefile(self, cachefile):
-        self.openFileReferenceCount.pop(get_basename(cachefile))
+        self.open_file_reference.pop(get_basename(cachefile))
         cachefile.close()
 
     def get_filename(self, file):
-        File = _get_cachefile_class()
-        if isinstance(file, File):
+        file_class = _get_cachefile_class()
+        if isinstance(file, file_class):
             return get_basename(file)
         return 0
 
@@ -51,13 +51,13 @@ class H5cache_class(HasPrivateTraits):
             return iter(self.open_files.values())
 
     def close_unreferenced_cachefiles(self):
-        for openCacheFile in self.get_open_cachefiles():
-            if not self.is_reference_existent(openCacheFile):
-                #                print("close unreferenced File:",get_basename(openCacheFile))
-                self.close_cachefile(openCacheFile)
+        for cachefile in self.get_open_cachefiles():
+            if not self.is_reference_existent(cachefile):
+                #                print("close unreferenced File:",get_basename(cachefile))
+                self.close_cachefile(cachefile)
 
     def is_reference_existent(self, file):
-        existFlag = False
+        exist_flag = False
         # inspect all refererres to the file object
         gc.collect()  # clear garbage before collecting referrers
         for ref in gc.get_referrers(file):
@@ -65,41 +65,41 @@ class H5cache_class(HasPrivateTraits):
             # attribute?
             if isinstance(ref, dict) and 'h5f' in ref:
                 # file is still referred, must not be closed
-                existFlag = True
+                exist_flag = True
                 break
-        return existFlag
+        return exist_flag
 
-    def is_cachefile_existent(self, cacheFileName):
-        if cacheFileName in listdir(self.cache_dir):
+    def is_cachefile_existent(self, filename):
+        if filename in listdir(self.cache_dir):
             return True
         return False
 
-    def _increase_file_reference_counter(self, cacheFileName):
-        self.openFileReferenceCount[cacheFileName] = self.openFileReferenceCount.get(cacheFileName, 0) + 1
+    def _increase_file_reference_counter(self, filename):
+        self.open_file_reference[filename] = self.open_file_reference.get(filename, 0) + 1
 
-    def _decrease_file_reference_counter(self, cacheFileName):
-        self.openFileReferenceCount[cacheFileName] = self.openFileReferenceCount[cacheFileName] - 1
+    def _decrease_file_reference_counter(self, filename):
+        self.open_file_reference[filename] = self.open_file_reference[filename] - 1
 
     def _print_open_files(self):
-        print(list(self.openFileReferenceCount.items()))
+        print(list(self.open_file_reference.items()))
 
     def get_cache_file(self, obj, basename, mode='a'):
         """Returns pytables .h5 file to h5f trait of calling object for caching."""
         self._idle_if_busy()  #
         self.busy = True
 
-        cacheFileName = basename + '_cache.h5'
-        objFileName = self.get_filename(obj.h5f)
+        filename = basename + '_cache.h5'
+        obj_filename = self.get_filename(obj.h5f)
 
-        if objFileName:
-            if objFileName == cacheFileName:
+        if obj_filename:
+            if obj_filename == filename:
                 self.busy = False
                 return
-            self._decrease_file_reference_counter(objFileName)
+            self._decrease_file_reference_counter(obj_filename)
 
-        if cacheFileName not in self.open_files:  # or tables.file._open_files.filenames
+        if filename not in self.open_files:  # or tables.file._open_files.filenames
             if config.global_caching == 'readonly' and not self.is_cachefile_existent(
-                cacheFileName,
+                filename,
             ):  # condition ensures that cachefile is not created in readonly mode
                 obj.h5f = None
                 self.busy = False
@@ -107,11 +107,11 @@ class H5cache_class(HasPrivateTraits):
                 return
             if config.global_caching == 'readonly':
                 mode = 'r'
-            f = self.open_cachefile(cacheFileName, mode)
-            self.open_files[cacheFileName] = f
+            f = self.open_cachefile(filename, mode)
+            self.open_files[filename] = f
 
-        obj.h5f = self.open_files[cacheFileName]
-        self._increase_file_reference_counter(cacheFileName)
+        obj.h5f = self.open_files[filename]
+        self._increase_file_reference_counter(filename)
 
         # garbage collection
         self.close_unreferenced_cachefiles()
@@ -120,7 +120,7 @@ class H5cache_class(HasPrivateTraits):
         self._print_open_files()
 
 
-H5cache = H5cache_class(config=config)
+H5cache = HDF5Cache(config=config)
 
 
 def get_basename(file):

acoular/h5files.py

@@ -33,7 +33,7 @@ class H5FileBase:
 class H5CacheFileBase:
     """Base class for File objects that handle writing and reading of .h5 cache files."""
 
-    compressionFilter = None
+    compression_filter = None
 
     def is_cached(self, nodename, group=None):
         pass
@@ -72,7 +72,7 @@ if config.have_tables:
             node.set_attr(attrname, value)
 
         def get_node_attribute(self, node, attrname):
-            return node._v_attrs[attrname]
+            return node._v_attrs[attrname]  # noqa: SLF001
 
         def append_data(self, node, data):
             node.append(data)
@@ -93,10 +93,10 @@ if config.have_tables:
             """Recursively convert an HDF5 node to a dictionary."""
             node = self.get_node(nodename)
             # initialize node-dict with node's own attributes
-            result = {attr: node._v_attrs[attr] for attr in node._v_attrs._f_list()}
+            result = {attr: node._v_attrs[attr] for attr in node._v_attrs._f_list()}  # noqa: SLF001
             if isinstance(node, tables.Group):
                 # if node is a group, recursively add its children
-                for childname in node._v_children:
+                for childname in node._v_children:  # noqa: SLF001
                     result[childname] = self.node_to_dict(f'{nodename}/{childname}')
             elif isinstance(node, tables.Leaf):
                 # if node contains only data, add it
@@ -106,7 +106,7 @@ if config.have_tables:
             return result
 
     class H5CacheFileTables(H5FileTables, H5CacheFileBase):
-        compressionFilter = tables.Filters(complevel=5, complib='blosc')
+        compression_filter = tables.Filters(complevel=5, complib='blosc')
 
         def is_cached(self, nodename, group=None):
             if not group:
@@ -119,7 +119,7 @@ if config.have_tables:
             if not group:
                 group = self.root
             atom = precision_to_atom[precision]
-            self.create_carray(group, nodename, atom, shape, filters=self.compressionFilter)
+            self.create_carray(group, nodename, atom, shape, filters=self.compression_filter)
 
 
 if config.have_h5py:
@@ -149,10 +149,10 @@ if config.have_h5py:
             return node.attrs[attrname]
 
         def append_data(self, node, data):
-            oldShape = node.shape
-            newShape = (oldShape[0] + data.shape[0], data.shape[1])
-            node.resize(newShape)
-            node[oldShape[0] : newShape[0], :] = data
+            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):
             in_file_path = self._get_in_file_path(nodename, group)
@@ -184,8 +184,8 @@ if config.have_h5py:
             return result
 
     class H5CacheFileH5py(H5CacheFileBase, H5FileH5py):
-        compressionFilter = 'lzf'
-        #        compressionFilter = 'blosc' # unavailable...
+        compression_filter = 'lzf'
+        #        compression_filter = 'blosc' # unavailable...
 
         def is_cached(self, nodename, group=None):
             if not group:
@@ -200,7 +200,7 @@ if config.have_h5py:
                 in_file_path,
                 dtype=precision,
                 shape=shape,
-                compression=self.compressionFilter,
+                compression=self.compression_filter,
                 chunks=True,
             )
 

acoular/internal.py

@@ -13,13 +13,13 @@ def digest(obj, name='digest'):
             for i in do_.split('.'):
                 vobj = list(vobj.trait_get(i.rstrip('[]')).values())[0]
             str_.append(str(vobj).encode('UTF-8'))
-        except:
+        except:  # noqa: E722
             pass
     return '_' + md5(b''.join(str_)).hexdigest()
 
 
-def ldigest(l):
+def ldigest(obj_list):
     str_ = []
-    for i in l:
+    for i in obj_list:
         str_.append(str(i.digest).encode('UTF-8'))
     return '_' + md5(b''.join(str_)).hexdigest()

acoular/sdinput.py

@@ -9,12 +9,15 @@
     SoundDeviceSamplesGenerator
 """
 
-import sounddevice as sd
 from traits.api import Any, Bool, Int, Long, Property, cached_property, observe
 
+from .configuration import config
 from .internal import digest
 from .tprocess import SamplesGenerator
 
+if config.have_sounddevice:
+    import sounddevice as sd
+
 
 class SoundDeviceSamplesGenerator(SamplesGenerator):
     """Controller for sound card hardware using sounddevice library.
@@ -24,6 +27,12 @@ class SoundDeviceSamplesGenerator(SamplesGenerator):
     :meth:`result`.
     """
 
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        if config.have_sounddevice is False:
+            msg = 'SoundDevice library not found but is required for using the SoundDeviceSamplesGenerator class.'
+            raise ImportError(msg)
+
     #: input device index, refers to sounddevice list
     device = Int(0, desc='input device index')
 

acoular/signals.py

@@ -279,7 +279,21 @@ class SineGenerator(SignalGenerator):
 
 
 class GenericSignalGenerator(SignalGenerator):
-    """Generate signal from output of :class:`~acoular.tprocess.SamplesGenerator` object."""
+    """Generate signal from output of :class:`~acoular.tprocess.SamplesGenerator` object.
+
+    This class can be used to inject arbitrary signals into Acoular processing
+    chains. For example, it can be used to read signals from a HDF5 file or create any signal
+    by using the :class:`acoular.sources.TimeSamples` class.
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> from acoular import TimeSamples, GenericSignalGenerator
+    >>> data = np.random.rand(1000, 1)
+    >>> ts = TimeSamples(data=data, sample_freq=51200)
+    >>> sig = GenericSignalGenerator(source=ts)
+
+    """
 
     #: Data source; :class:`~acoular.tprocess.SamplesGenerator` or derived object.
     source = Trait(SamplesGenerator)

acoular/sources.py

@@ -1,7 +1,7 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Measured multichannel data managment and simulation of acoustic sources.
+"""Measured multichannel data management and simulation of acoustic sources.
 
 .. autosummary::
     :toctree: generated/
@@ -22,6 +22,7 @@
 
 # imports from other packages
 
+import contextlib
 from os import path
 from warnings import warn
 
@@ -104,7 +105,7 @@ def _fill_mic_signal_block(out, signal, rm, ind, blocksize, numchannels, up, pre
     return out
 
 
-def spherical_hn1(n, z, derivativearccos=False):
+def spherical_hn1(n, z):
     """Spherical Hankel Function of the First Kind."""
     return spherical_jn(n, z, derivative=False) + 1j * spherical_yn(n, z, derivative=False)
 
@@ -146,7 +147,7 @@ def get_radiation_angles(direction, mpos, sourceposition):
     return azi, ele
 
 
-def get_modes(lOrder, direction, mpos, sourceposition=None):
+def get_modes(lOrder, direction, mpos, sourceposition=None):  # noqa: N803
     """Returns Spherical Harmonic Radiation Pattern at the Microphones.
 
     Parameters
@@ -170,9 +171,9 @@ def get_modes(lOrder, direction, mpos, sourceposition=None):
     azi, ele = get_radiation_angles(direction, mpos, sourceposition)  # angles between source and mics
     modes = zeros((azi.shape[0], (lOrder + 1) ** 2), dtype=complex128)
     i = 0
-    for l in range(lOrder + 1):
-        for m in range(-l, l + 1):
-            modes[:, i] = sph_harm(m, l, azi, ele)
+    for lidx in range(lOrder + 1):
+        for m in range(-lidx, lidx + 1):
+            modes[:, i] = sph_harm(m, lidx, azi, ele)
             if m < 0:
                 modes[:, i] = modes[:, i].conj() * 1j
             i += 1
@@ -180,12 +181,44 @@ def get_modes(lOrder, direction, mpos, sourceposition=None):
 
 
 class TimeSamples(SamplesGenerator):
-    """Container for time data in `*.h5` format.
-
-    This class loads measured data from h5 files and
-    and provides information about this data.
-    It also serves as an interface where the data can be accessed
-    (e.g. for use in a block chain) via the :meth:`result` generator.
+    """Container for processing time data in `*.h5` or NumPy array format.
+
+    This class loads measured data from HDF5 files and provides information about this data.
+    It also serves as an interface where the data can be accessed (e.g. for use in a block chain) via the
+    :meth:`result` generator.
+
+    Examples
+    --------
+    Data can be loaded from a HDF5 file as follows:
+
+    >>> from acoular import TimeSamples
+    >>> name = <some_h5_file.h5>  # doctest: +SKIP
+    >>> ts = TimeSamples(name=name)  # doctest: +SKIP
+    >>> print(f'number of channels: {ts.numchannels}')  # doctest: +SKIP
+    number of channels: 56 # doctest: +SKIP
+
+    Alternatively, the time data can be specified directly as a numpy array.
+    In this case, the :attr:`data` and :attr:`sample_freq` attributes must be set manually.
+
+    >>> import numpy as np
+    >>> data = np.random.rand(1000, 4)
+    >>> ts = TimeSamples(data=data, sample_freq=51200)
+
+    Chunks of the time data can be accessed iteratively via the :meth:`result` generator.
+    The last block will be shorter than the block size if the number of samples is not a multiple of the block size.
+
+    >>> blocksize = 512
+    >>> generator = ts.result(num=blocksize)
+    >>> for block in generator:
+    ...     print(block.shape)
+    (512, 4)
+    (488, 4)
+
+    See Also
+    --------
+    acoular.sources.MaskedTimeSamples :
+        Extends the functionality of class :class:`TimeSamples` by enabling the definition of start and stop samples
+        as well as the specification of invalid channels.
     """
 
     #: Full name of the .h5 file with data.
@@ -233,31 +266,31 @@ class TimeSamples(SamplesGenerator):
         return path.splitext(path.basename(self.name))[0]
 
     @on_trait_change('basename')
-    def load_data(self):
+    def _load_data(self):
         """Open the .h5 file and set attributes."""
         if not path.isfile(self.name):
-            # no file there
-            self.numsamples = 0
-            self.numchannels = 0
             self.sample_freq = 0
             raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
-            try:
+            with contextlib.suppress(OSError):
                 self.h5f.close()
-            except OSError:
-                pass
         file = _get_h5file_class()
         self.h5f = file(self.name)
-        self.load_timedata()
-        self.load_metadata()
+        self._load_timedata()
+        self._load_metadata()
 
-    def load_timedata(self):
+    @on_trait_change('data')
+    def _load_shapes(self):
+        """Set numchannels and numsamples from data."""
+        if self.data is not None:
+            self.numsamples, self.numchannels = self.data.shape
+
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('time_data')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sample_freq')
-        (self.numsamples, self.numchannels) = self.data.shape
 
-    def load_metadata(self):
+    def _load_metadata(self):
         """Loads metadata from .h5 file. Only for internal use."""
         self.metadata = {}
         if '/metadata' in self.h5f:
@@ -266,15 +299,20 @@ class TimeSamples(SamplesGenerator):
     def result(self, num=128):
         """Python generator that yields the output block-wise.
 
+        Reads the time data either from a HDF5 file or from a numpy array given
+        by :attr:`data` and iteratively returns a block of size `num` samples.
+        Calibrated data is returned if a calibration object is given by :attr:`calib`.
+
         Parameters
         ----------
         num : integer, defaults to 128
             This parameter defines the size of the blocks to be yielded
-            (i.e. the number of samples per block) .
+            (i.e. the number of samples per block).
 
-        Returns
-        -------
-        Samples in blocks of shape (num, numchannels).
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, numchannels).
             The last block may be shorter than num.
 
         """
@@ -298,14 +336,40 @@ class TimeSamples(SamplesGenerator):
 
 
 class MaskedTimeSamples(TimeSamples):
-    """Container for time data in `*.h5` format.
-
-    This class loads measured data from h5 files
-    and provides information about this data.
-    It supports storing information about (in)valid samples and (in)valid channels
-    It also serves as an interface where the data can be accessed
-    (e.g. for use in a block chain) via the :meth:`result` generator.
-
+    """Container for processing time data in `*.h5` or NumPy array format.
+
+    This class loads measured data from HDF5 files and provides information about this data.
+    It supports storing information about (in)valid samples and (in)valid channels and allows
+    to specify a start and stop index for the valid samples.
+    It also serves as an interface where the data can be accessed (e.g. for use in a block chain) via the
+    :meth:`result` generator.
+
+    Examples
+    --------
+    Data can be loaded from a HDF5 file and invalid channels can be specified as follows:
+
+    >>> from acoular import MaskedTimeSamples
+    >>> name = <some_h5_file.h5>  # doctest: +SKIP
+    >>> ts = MaskedTimeSamples(name=name, invalid_channels=[0, 1])  # doctest: +SKIP
+    >>> print(f'number of valid channels: {ts.numchannels}')  # doctest: +SKIP
+    number of valid channels: 54 # doctest: +SKIP
+
+    Alternatively, the time data can be specified directly as a numpy array.
+    In this case, the :attr:`data` and :attr:`sample_freq` attributes must be set manually.
+
+    >>> from acoular import MaskedTimeSamples
+    >>> import numpy as np
+    >>> data = np.random.rand(1000, 4)
+    >>> ts = MaskedTimeSamples(data=data, sample_freq=51200)
+
+    Chunks of the time data can be accessed iteratively via the :meth:`result` generator:
+
+    >>> blocksize = 512
+    >>> generator = ts.result(num=blocksize)
+    >>> for block in generator:
+    ...     print(block.shape)
+    (512, 4)
+    (488, 4)
     """
 
     #: Index of the first sample to be considered valid.
@@ -362,26 +426,28 @@ class MaskedTimeSamples(TimeSamples):
         return sli[1] - sli[0]
 
     @on_trait_change('basename')
-    def load_data(self):
+    def _load_data(self):
         # """ open the .h5 file and set attributes
         # """
         if not path.isfile(self.name):
             # no file there
-            self.numsamples_total = 0
-            self.numchannels_total = 0
             self.sample_freq = 0
             raise OSError('No such file: %s' % self.name)
         if self.h5f is not None:
-            try:
+            with contextlib.suppress(OSError):
                 self.h5f.close()
-            except OSError:
-                pass
         file = _get_h5file_class()
         self.h5f = file(self.name)
-        self.load_timedata()
-        self.load_metadata()
+        self._load_timedata()
+        self._load_metadata()
+
+    @on_trait_change('data')
+    def _load_shapes(self):
+        """Set numchannels and numsamples from data."""
+        if self.data is not None:
+            self.numsamples_total, self.numchannels_total = self.data.shape
 
-    def load_timedata(self):
+    def _load_timedata(self):
         """Loads timedata from .h5 file. Only for internal use."""
         self.data = self.h5f.get_data_by_reference('time_data')
         self.sample_freq = self.h5f.get_node_attribute(self.data, 'sample_freq')
@@ -390,15 +456,20 @@ class MaskedTimeSamples(TimeSamples):
     def result(self, num=128):
         """Python generator that yields the output block-wise.
 
+        Reads the time data either from a HDF5 file or from a numpy array given
+        by :attr:`data` and iteratively returns a block of size `num` samples.
+        Calibrated data is returned if a calibration object is given by :attr:`calib`.
+
         Parameters
         ----------
         num : integer, defaults to 128
             This parameter defines the size of the blocks to be yielded
             (i.e. the number of samples per block).
 
-        Returns
-        -------
-        Samples in blocks of shape (num, numchannels).
+        Yields
+        ------
+        numpy.ndarray
+            Samples in blocks of shape (num, numchannels).
             The last block may be shorter than num.
 
         """
@@ -588,7 +659,7 @@ class SphericalHarmonicSource(PointSource):
     """
 
     #: Order of spherical harmonic source
-    lOrder = Int(0, desc='Order of spherical harmonic')
+    lOrder = Int(0, desc='Order of spherical harmonic')  # noqa: N815
 
     alpha = CArray(desc='coefficients of the (lOrder,) spherical harmonic mode')
 

acoular/spectra.py

@@ -383,7 +383,7 @@ class PowerSpectra(BaseSpectra):
         wind = wind[newaxis, :].swapaxes(0, 1)
         numfreq = int(self.block_size / 2 + 1)
         csm_shape = (numfreq, t.numchannels, t.numchannels)
-        csmUpper = zeros(csm_shape, dtype=self.precision)
+        csm_upper = zeros(csm_shape, dtype=self.precision)
         # print "num blocks", self.num_blocks
         # for backward compatibility
         if self.calib and self.calib.num_mics > 0:
@@ -394,11 +394,11 @@ class PowerSpectra(BaseSpectra):
         # get time data blockwise
         for data in self.get_source_data():
             ft = fft.rfft(data * wind, None, 0).astype(self.precision)
-            calcCSM(csmUpper, ft)  # only upper triangular part of matrix is calculated (for speed reasons)
+            calcCSM(csm_upper, ft)  # only upper triangular part of matrix is calculated (for speed reasons)
         # create the full csm matrix via transposing and complex conj.
-        csmLower = csmUpper.conj().transpose(0, 2, 1)
-        [fill_diagonal(csmLower[cntFreq, :, :], 0) for cntFreq in range(csmLower.shape[0])]
-        csm = csmLower + csmUpper
+        csm_lower = csm_upper.conj().transpose(0, 2, 1)
+        [fill_diagonal(csm_lower[cntFreq, :, :], 0) for cntFreq in range(csm_lower.shape[0])]
+        csm = csm_lower + csm_upper
         # onesided spectrum: multiplication by 2.0=sqrt(2)^2
         return csm * (2.0 / self.block_size / weight / self.num_blocks)