acoular 24.10__py3-none-any.whl → 25.3__py3-none-any.whl

acoular/spectra.py

@@ -8,10 +8,10 @@
 
     BaseSpectra
     PowerSpectra
-    synthetic
     PowerSpectraImport
 """
 
+from abc import abstractmethod
 from warnings import warn
 
 from numpy import (
@@ -25,75 +25,98 @@ from numpy import (
     hamming,
     hanning,
     imag,
-    isscalar,
     linalg,
     ndarray,
     newaxis,
     ones,
     real,
     searchsorted,
-    sum,
+    sum,  # noqa A004
     zeros,
-    zeros_like,
 )
 from scipy import fft
 from traits.api import (
+    ABCHasStrictTraits,
     Bool,
     CArray,
     Delegate,
     Enum,
     Float,
-    HasPrivateTraits,
     Instance,
     Int,
+    Map,
     Property,
-    Trait,
+    Union,
     cached_property,
     property_depends_on,
 )
 
+# acoular imports
 from .base import SamplesGenerator
-from .calib import Calib
 from .configuration import config
+from .deprecation import deprecated_alias
 from .fastFuncs import calcCSM
 from .h5cache import H5cache
 from .h5files import H5CacheFileBase
 from .internal import digest
+from .tools.utils import find_basename
 
 
-class BaseSpectra(HasPrivateTraits):
-    #: Data source; :class:`~acoular.sources.SamplesGenerator` or derived object.
-    source = Trait(SamplesGenerator)
+@deprecated_alias({'numchannels': 'num_channels'}, read_only=True)
+@deprecated_alias({'time_data': 'source'}, read_only=False)
+class BaseSpectra(ABCHasStrictTraits):
+    """
+    Base class for handling spectral data in Acoular.
+
+    This class defines the basic structure and functionality for computing and managing spectral
+    data derived from time-domain signals. It includes properties for configuring the Fast Fourier
+    Transformation (FFT), including overlap, and other parameters critical for spectral analysis.
+    """
 
-    #: Sampling frequency of output signal, as given by :attr:`source`.
+    #: Data source; an instance of :class:`~acoular.base.SamplesGenerator` or derived object.
+    source = Instance(SamplesGenerator)
+
+    #: Sampling frequency of the output signal, delegated from :attr:`source`.
     sample_freq = Delegate('source')
 
-    #: Number of time data channels
-    numchannels = Delegate('source')
-
-    #: Window function for FFT, one of:
-    #:   * 'Rectangular' (default)
-    #:   * 'Hanning'
-    #:   * 'Hamming'
-    #:   * 'Bartlett'
-    #:   * 'Blackman'
-    window = Trait(
-        'Rectangular',
+    #: Number of time microphones, delegated from :attr:`source`.
+    num_channels = Delegate('source')
+
+    #: Window function applied during FFT. Can be one of:
+    #:
+    #: - ``'Rectangular'`` (default)
+    #:
+    #: - ``'Hanning'``
+    #:
+    #: - ``'Hamming'``
+    #:
+    #: - ``'Bartlett'``
+    #:
+    #: - ``'Blackman'``
+    window = Map(
         {'Rectangular': ones, 'Hanning': hanning, 'Hamming': hamming, 'Bartlett': bartlett, 'Blackman': blackman},
+        default_value='Rectangular',
         desc='type of window for FFT',
     )
 
-    #: Overlap factor for averaging: 'None'(default), '50%', '75%', '87.5%'.
-    overlap = Trait('None', {'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, desc='overlap of FFT blocks')
+    #: Overlap factor for FFT block averaging. One of:
+    #:
+    #: - ``'None'`` (default)
+    #:
+    #: - ``'50%'``
+    #:
+    #: - ``'75%'``
+    #:
+    #: - ``'87.5%'``
+    overlap = Map({'None': 1, '50%': 2, '75%': 4, '87.5%': 8}, default_value='None', desc='overlap of FFT blocks')
 
-    #: FFT block size, one of: 128, 256, 512, 1024, 2048 ... 65536,
-    #: defaults to 1024.
-    block_size = Trait(
+    #: FFT block size. Must be one of: ``128``, ``256``, ``512``, ``1024``, ... ``65536``.
+    #: Default is ``1024``.
+    block_size = Enum(
         1024,
         128,
         256,
         512,
-        1024,
         2048,
         4096,
         8192,
@@ -103,25 +126,53 @@ class BaseSpectra(HasPrivateTraits):
         desc='number of samples per FFT block',
     )
 
-    #: The floating-number-precision of the resulting spectra, corresponding to numpy dtypes.
-    #: Default is 'complex128'.
-    precision = Trait('complex128', 'complex64', desc='precision of the fft')
+    #: Precision of the FFT, corresponding to NumPy dtypes. Default is ``'complex128'``.
+    precision = Enum('complex128', 'complex64', desc='precision of the fft')
 
-    # internal identifier
+    #: A unique identifier for the spectra, based on its properties. (read-only)
     digest = Property(depends_on=['precision', 'block_size', 'window', 'overlap'])
 
-    @cached_property
+    @abstractmethod
     def _get_digest(self):
-        return digest(self)
+        """Return internal identifier."""
 
     def fftfreq(self):
-        """Return the Discrete Fourier Transform sample frequencies.
+        """
+        Compute and return the Discrete Fourier Transform sample frequencies.
+
+        This method generates the frequency values corresponding to the FFT bins for the
+        configured :attr:`block_size` and sampling frequency from the data source.
 
         Returns
         -------
-        f : ndarray
-            Array of length *block_size/2+1* containing the sample frequencies.
-
+        :obj:`numpy.ndarray` or :obj:`None`
+            Array of shape ``(`` :attr:`block_size` ``/ 2 + 1,)`` containing the sample frequencies.
+            If :attr:`source` is not set, returns ``None``.
+
+        Examples
+        --------
+        Using normally distributed data for time samples as in
+        :class:`~acoular.sources.TimeSamples`.
+
+        >>> import numpy as np
+        >>> from acoular import TimeSamples
+        >>> from acoular.spectra import PowerSpectra
+        >>>
+        >>> data = np.random.rand(1000, 4)
+        >>> ts = TimeSamples(data=data, sample_freq=51200)
+        >>> print(ts.num_channels, ts.num_samples, ts.sample_freq)
+        4 1000 51200.0
+        >>> ps = PowerSpectra(source=ts, block_size=128, window='Blackman')
+        >>> ps.fftfreq()
+        array([    0.,   400.,   800.,  1200.,  1600.,  2000.,  2400.,  2800.,
+                3200.,  3600.,  4000.,  4400.,  4800.,  5200.,  5600.,  6000.,
+                6400.,  6800.,  7200.,  7600.,  8000.,  8400.,  8800.,  9200.,
+                9600., 10000., 10400., 10800., 11200., 11600., 12000., 12400.,
+               12800., 13200., 13600., 14000., 14400., 14800., 15200., 15600.,
+               16000., 16400., 16800., 17200., 17600., 18000., 18400., 18800.,
+               19200., 19600., 20000., 20400., 20800., 21200., 21600., 22000.,
+               22400., 22800., 23200., 23600., 24000., 24400., 24800., 25200.,
+               25600.])
         """
         if self.source is not None:
             return abs(fft.fftfreq(self.block_size, 1.0 / self.source.sample_freq)[: int(self.block_size / 2 + 1)])
@@ -130,7 +181,7 @@ class BaseSpectra(HasPrivateTraits):
     # generator that yields the time data blocks for every channel (with optional overlap)
     def _get_source_data(self):
         bs = self.block_size
-        temp = empty((2 * bs, self.numchannels))
+        temp = empty((2 * bs, self.num_channels))
         pos = bs
         posinc = bs / self.overlap_
         for data_block in self.source.result(bs):
@@ -145,134 +196,99 @@ class BaseSpectra(HasPrivateTraits):
 
 
 class PowerSpectra(BaseSpectra):
-    """Provides the cross spectral matrix of multichannel time data
-     and its eigen-decomposition.
-
-    This class includes the efficient calculation of the full cross spectral
-    matrix using the Welch method with windows and overlap (:cite:`Welch1967`). It also contains
-    the CSM's eigenvalues and eigenvectors and additional properties.
-
-    The result is computed only when needed, that is when the :attr:`csm`,
-    :attr:`eva`, or :attr:`eve` attributes are acturally read.
-    Any change in the input data or parameters leads to a new calculation,
-    again triggered when an attribute is read. The result may be
-    cached on disk in HDF5 files and need not to be recomputed during
-    subsequent program runs with identical input data and parameters. The
-    input data is taken to be identical if the source has identical parameters
-    and the same file name in case of that the data is read from a file.
+    """
+    Provides the cross-spectral matrix of multichannel time-domain data and its eigen-decomposition.
+
+    This class is designed to compute the cross-spectral matrix (CSM) efficiently using the Welch
+    method :cite:`Welch1967` with support for windowing and overlapping data segments. It also
+    calculates the eigenvalues and eigenvectors of the CSM, allowing for spectral analysis and
+    advanced signal processing tasks.
+
+    Key features:
+        - **Efficient Calculation**: Computes the CSM using FFT-based methods.
+        - **Caching**: Results can be cached in HDF5 files to avoid redundant calculations for
+          identical inputs and parameters.
+        - **Lazy Evaluation**: Calculations are triggered only when attributes like :attr:`csm`,
+          :attr:`eva`, or :attr:`eve` are accessed.
+        - **Dynamic Input Handling**: Automatically recomputes results when the input data or
+          parameters change.
     """
 
-    # Shadow trait, should not be set directly, for internal use.
-    _source = Trait(SamplesGenerator)
-
-    #: Data source; :class:`~acoular.sources.SamplesGenerator` or derived object.
-    source = Property(_source, desc='time data object')
-
-    #: The :class:`~acoular.base.SamplesGenerator` object that provides the data.
-    time_data = Property(
-        _source,
-        desc='deprecated attribute holding the time data object. Use PowerSpectra.source instead!',
-    )
-
-    #: The :class:`~acoular.calib.Calib` object that provides the calibration data,
-    #: defaults to no calibration, i.e. the raw time data is used.
-    #:
-    #: **deprecated, will be removed in version 25.01**: use :attr:`~acoular.sources.TimeSamples.calib` property of
-    #: :class:`~acoular.sources.TimeSamples` objects
-    calib = Property(desc='calibration object (deprecated, will be removed in version 25.01)')
-
-    _calib = Instance(Calib)
+    #: The data source for the time-domain samples. It must be an instance of
+    #: :class:`SamplesGenerator<acoular.base.SamplesGenerator>` or a derived class.
+    source = Instance(SamplesGenerator)
 
     # Shadow trait, should not be set directly, for internal use.
     _ind_low = Int(1, desc='index of lowest frequency line')
 
     # Shadow trait, should not be set directly, for internal use.
-    _ind_high = Trait(-1, (Int, None), desc='index of highest frequency line')
+    _ind_high = Union(Int(-1), None, desc='index of highest frequency line')
 
-    #: Index of lowest frequency line to compute, integer, defaults to 1,
-    #: is used only by objects that fetch the csm, PowerSpectra computes every
-    #: frequency line.
+    #: Index of lowest frequency line to compute. Default is ``1``. Only used by objects that fetch
+    #: the CSM. PowerSpectra computes every frequency line.
     ind_low = Property(_ind_low, desc='index of lowest frequency line')
 
-    #: Index of highest frequency line to compute, integer,
-    #: defaults to -1 (last possible line for default block_size).
+    #: Index of highest frequency line to compute. Default is ``-1``
+    #: (last possible line for default :attr:`~BaseSpectra.block_size`).
     ind_high = Property(_ind_high, desc='index of lowest frequency line')
 
     # Stores the set lower frequency, for internal use, should not be set directly.
     _freqlc = Float(0)
 
     # Stores the set higher frequency, for internal use, should not be set directly.
-    _freqhc = Trait(0, (Float, None))
+    _freqhc = Union(Float(0), None)
 
-    # Saves whether the user set indices or frequencies last, for internal use only,
-    # not to be set directly, if True (default), indices are used for setting
-    # the freq_range interval.
+    # Saves whether the user set indices or frequencies last, for internal use only, not to be set
+    # directly, if ``True``, indices are used for setting the :attr:`freq_range` interval.
+    # Default is ``True``.
     _index_set_last = Bool(True)
 
-    #: Flag, if true (default), the result is cached in h5 files and need not
-    #: to be recomputed during subsequent program runs.
+    #: A flag indicating whether the result should be cached in HDF5 files. Default is ``True``.
     cached = Bool(True, desc='cached flag')
 
-    #: Number of FFT blocks to average, readonly
-    #: (set from block_size and overlap).
+    #: The number of FFT blocks used for averaging. This is derived from the
+    #: :attr:`~BaseSpectra.block_size` and :attr:`~BaseSpectra.overlap` parameters. (read-only)
     num_blocks = Property(desc='overall number of FFT blocks')
 
-    #: 2-element array with the lowest and highest frequency. If set,
-    #: will overwrite :attr:`_freqlc` and :attr:`_freqhc` according to
-    #: the range.
-    #: The freq_range interval will be the smallest discrete frequency
-    #: inside the half-open interval [_freqlc, _freqhc[ and the smallest
-    #: upper frequency outside of the interval.
-    #: If user chooses the higher frequency larger than the max frequency,
-    #: the max frequency will be the upper bound.
+    #: 2-element array with the lowest and highest frequency. If the higher frequency is larger than
+    #: the max frequency, the max frequency will be the upper bound.
     freq_range = Property(desc='frequency range')
+    # If set, will overwrite :attr:`_freqlc`  and :attr:`_freqhc` according to the range. The
+    # freq_range interval will be the smallest discrete frequency inside the half-open interval
+    # [_freqlc, _freqhc[ and the smallest upper frequency outside of the interval.
 
-    #: Array with a sequence of indices for all frequencies
-    #: between :attr:`ind_low` and :attr:`ind_high` within the result, readonly.
+    #: The sequence of frequency indices between :attr:`ind_low` and :attr:`ind_high`. (read-only)
     indices = Property(desc='index range')
 
-    #: Name of the cache file without extension, readonly.
-    basename = Property(depends_on='_source.digest', desc='basename for cache file')
+    #: The name of the cache file (without the file extension) used for storing results. (read-only)
+    basename = Property(depends_on=['source.digest'], desc='basename for cache file')
 
-    #: The cross spectral matrix,
-    #: (number of frequencies, numchannels, numchannels) array of complex;
-    #: readonly.
+    #: The cross-spectral matrix, represented as an array of shape ``(n, m, m)`` of complex values
+    #: for ``n`` frequencies and ``m`` channels as in :attr:`~BaseSpectra.num_channels`. (read-only)
     csm = Property(desc='cross spectral matrix')
 
-    #: Eigenvalues of the cross spectral matrix as an
-    #: (number of frequencies) array of floats, readonly.
+    #: The eigenvalues of the CSM, stored as an array of shape ``(n,)`` of floats for ``n``
+    #: frequencies. (read-only)
     eva = Property(desc='eigenvalues of cross spectral matrix')
 
-    #: Eigenvectors of the cross spectral matrix as an
-    #: (number of frequencies, numchannels, numchannels) array of floats,
-    #: readonly.
+    #: The eigenvectors of the cross spectral matrix, stored as an array of shape ``(n, m, m)`` of
+    #: floats for ``n`` frequencies and ``m`` channels as in :attr:`~BaseSpectra.num_channels`.
+    #: (read-only)
     eve = Property(desc='eigenvectors of cross spectral matrix')
 
-    # internal identifier
+    #: A unique identifier for the spectra, based on its properties.  (read-only)
     digest = Property(
-        depends_on=['_source.digest', 'calib.digest', 'block_size', 'window', 'overlap', 'precision'],
+        depends_on=['source.digest', 'block_size', 'window', 'overlap', 'precision'],
     )
 
-    # hdf5 cache file
+    #: The HDF5 cache file used for storing the results if :attr:`cached` is set to ``True``.
     h5f = Instance(H5CacheFileBase, transient=True)
 
-    def _get_calib(self):
-        return self._calib
-
-    def _set_calib(self, calib):
-        msg = (
-            "Using 'calib' attribute is deprecated and will be removed in version 25.01. "
-            'use :attr:`~acoular.sources.TimeSamples.calib` property of '
-            ':class:`~acoular.sources.TimeSamples` object instead.'
-        )
-        warn(msg, DeprecationWarning, stacklevel=2)
-        self._calib = calib
-
-    @property_depends_on('_source.numsamples, block_size, overlap')
+    @property_depends_on(['source.num_samples', 'block_size', 'overlap'])
     def _get_num_blocks(self):
-        return self.overlap_ * self._source.numsamples / self.block_size - self.overlap_ + 1
+        return self.overlap_ * self.source.num_samples / self.block_size - self.overlap_ + 1
 
-    @property_depends_on('_source.sample_freq, block_size, ind_low, ind_high')
+    @property_depends_on(['source.sample_freq', 'block_size', 'ind_low', 'ind_high'])
     def _get_freq_range(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -286,7 +302,7 @@ class PowerSpectra(BaseSpectra):
         self._freqlc = freq_range[0]
         self._freqhc = freq_range[1]
 
-    @property_depends_on('_source.sample_freq, block_size, _ind_low, _freqlc')
+    @property_depends_on(['source.sample_freq', 'block_size', '_ind_low', '_freqlc'])
     def _get_ind_low(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -295,7 +311,7 @@ class PowerSpectra(BaseSpectra):
             return searchsorted(fftfreq[:-1], self._freqlc)
         return None
 
-    @property_depends_on('_source.sample_freq, block_size, _ind_high, _freqhc')
+    @property_depends_on(['source.sample_freq', 'block_size', '_ind_high', '_freqhc'])
     def _get_ind_high(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -316,24 +332,7 @@ class PowerSpectra(BaseSpectra):
         self._index_set_last = True
         self._ind_low = ind_low
 
-    def _set_time_data(self, time_data):
-        msg = (
-            "Using 'time_data' attribute is deprecated and will be removed in version 25.01. "
-            "Use 'source' attribute instead."
-        )
-        warn(msg, DeprecationWarning, stacklevel=2)
-        self._source = time_data
-
-    def _set_source(self, source):
-        self._source = source
-
-    def _get_time_data(self):
-        return self._source
-
-    def _get_source(self):
-        return self._source
-
-    @property_depends_on('block_size, ind_low, ind_high')
+    @property_depends_on(['block_size', 'ind_low', 'ind_high'])
     def _get_indices(self):
         fftfreq = self.fftfreq()
         if fftfreq is not None:
@@ -352,26 +351,44 @@ class PowerSpectra(BaseSpectra):
 
     @cached_property
     def _get_basename(self):
-        if 'basename' in self._source.all_trait_names():
-            return self._source.basename
-        return self._source.__class__.__name__ + self._source.digest
+        return find_basename(self.source, alternative_basename=self.source.__class__.__name__ + self.source.digest)
 
     def calc_csm(self):
-        """Csm calculation."""
+        """
+        Calculate the CSM for the given source data.
+
+        This method computes the CSM by performing a block-wise Fast Fourier Transform (FFT) on the
+        source data, applying a window function, and averaging the results. Only the upper
+        triangular part of the matrix is computed for efficiency, and the lower triangular part is
+        constructed via transposition and complex conjugation.
+
+        Returns
+        -------
+        :obj:`numpy.ndarray`
+            The computed cross spectral matrix as an array of shape ``(n, m, m)`` of complex values
+            for ``n`` frequencies and ``m`` channels as in :attr:`~BaseSpectra.num_channels`.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from acoular import TimeSamples
+        >>> from acoular.spectra import PowerSpectra
+        >>>
+        >>> data = np.random.rand(1000, 4)
+        >>> ts = TimeSamples(data=data, sample_freq=51200)
+        >>> print(ts.num_channels, ts.num_samples, ts.sample_freq)
+        4 1000 51200.0
+        >>> ps = PowerSpectra(source=ts, block_size=128, window='Blackman')
+        >>> ps.csm.shape
+        (65, 4, 4)
+        """
         t = self.source
         wind = self.window_(self.block_size)
         weight = dot(wind, wind)
         wind = wind[newaxis, :].swapaxes(0, 1)
         numfreq = int(self.block_size / 2 + 1)
-        csm_shape = (numfreq, t.numchannels, t.numchannels)
+        csm_shape = (numfreq, t.num_channels, t.num_channels)
         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:
-            if self.calib.num_mics == t.numchannels:
-                wind = wind * self.calib.data[newaxis, :]
-            else:
-                raise ValueError('Calibration data not compatible: %i, %i' % (self.calib.num_mics, t.numchannels))
         # get time data blockwise
         for data in self._get_source_data():
             ft = fft.rfft(data * wind, None, 0).astype(self.precision)
@@ -384,7 +401,43 @@ class PowerSpectra(BaseSpectra):
         return csm * (2.0 / self.block_size / weight / self.num_blocks)
 
     def calc_ev(self):
-        """Eigenvalues / eigenvectors calculation."""
+        """
+        Calculate eigenvalues and eigenvectors of the CSM for each frequency.
+
+        The eigenvalues represent the spectral power, and the eigenvectors correspond to the
+        principal components of the matrix. This calculation is performed for all frequency slices
+        of the CSM.
+
+        Returns
+        -------
+        :class:`tuple` of :obj:`numpy.ndarray`
+            A tuple containing:
+                - :attr:`eva` (:obj:`numpy.ndarray`): Eigenvalues as a 2D array of shape ``(n, m)``,
+                  where ``n`` is the number of frequencies and ``m`` is the number of channels. The
+                  datatype depends on the precision.
+                - :attr:`eve` (:obj:`numpy.ndarray`): Eigenvectors as a 3D array of shape
+                  ``(n, m, m)``. The datatype is consistent with the precision of the input data.
+
+        Notes
+        -----
+        - The precision of the eigenvalues is determined by :attr:`~BaseSpectra.precision`
+          (``'float64'`` for ``complex128`` precision and ``'float32'`` for ``complex64``
+          precision).
+        - This method assumes the CSM is already computed and accessible via :attr:`csm`.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from acoular import TimeSamples
+        >>> from acoular.spectra import PowerSpectra
+        >>>
+        >>> data = np.random.rand(1000, 4)
+        >>> ts = TimeSamples(data=data, sample_freq=51200)
+        >>> ps = PowerSpectra(source=ts, block_size=128, window='Hanning')
+        >>> eva, eve = ps.calc_ev()
+        >>> print(eva.shape, eve.shape)
+        (65, 4) (65, 4, 4)
+        """
         if self.precision == 'complex128':
             eva_dtype = 'float64'
         elif self.precision == 'complex64':
@@ -398,38 +451,51 @@ class PowerSpectra(BaseSpectra):
         return (eva, eve)
 
     def calc_eva(self):
-        """Calculates eigenvalues of csm."""
+        """
+        Calculate eigenvalues of the CSM.
+
+        This method computes and returns the eigenvalues of the CSM for all frequency slices.
+
+        Returns
+        -------
+        :obj:`numpy.ndarray`
+            A 2D array of shape ``(n, m)`` containing the eigenvalues for ``n`` frequencies and
+            ``m`` channels. The datatype depends on :attr:`~BaseSpectra.precision` (``'float64'``
+            for ``complex128`` precision and ``'float32'`` for ``complex64`` precision).
+
+        Notes
+        -----
+        This method internally calls :meth:`calc_ev` and extracts only the eigenvalues.
+        """
         return self.calc_ev()[0]
 
     def calc_eve(self):
-        """Calculates eigenvectors of csm."""
-        return self.calc_ev()[1]
+        """
+        Calculate eigenvectors of the Cross Spectral Matrix (CSM).
 
-    def _handle_dual_calibration(self):
-        obj = self.source  # start with time_data obj
-        while obj:
-            if 'calib' in obj.all_trait_names():  # at original source?
-                if obj.calib and self.calib:
-                    if obj.calib.digest == self.calib.digest:
-                        self.calib = None  # ignore it silently
-                    else:
-                        msg = 'Non-identical dual calibration for both TimeSamples and PowerSpectra object'
-                        raise ValueError(msg)
-                obj = None
-            else:
-                try:
-                    obj = obj.source  # traverse down until original data source
-                except AttributeError:
-                    obj = None
+        This method computes and returns the eigenvectors of the CSM for all frequency slices.
 
-    def _get_filecache(self, traitname):
-        """Function handles result caching of csm, eigenvectors and eigenvalues
-        calculation depending on global/local caching behaviour.
+        Returns
+        -------
+        :obj:`numpy.ndarray`
+            A 3D array of shape ``(n, m, m)`` containing the eigenvectors for ``n`` frequencies and
+            ``m`` channels. Each slice ``eve[f]`` represents an ``(m, m)`` matrix of eigenvectors
+            for frequency ``f``. The datatype matches the :attr:`~BaseSpectra.precision` of the CSM
+            (``complex128`` or ``complex64``).
+
+        Notes
+        -----
+        This method internally calls :meth:`calc_ev()` and extracts only the eigenvectors.
         """
+        return self.calc_ev()[1]
+
+    def _get_filecache(self, traitname):
+        # Handle caching of results for CSM, eigenvalues, and eigenvectors.
+        # Returns the requested data (``csm``, ``eva``, or ``eve``) as a NumPy array.
         if traitname == 'csm':
             func = self.calc_csm
             numfreq = int(self.block_size / 2 + 1)
-            shape = (numfreq, self._source.numchannels, self._source.numchannels)
+            shape = (numfreq, self.source.num_channels, self.source.num_channels)
             precision = self.precision
         elif traitname == 'eva':
             func = self.calc_eva
@@ -465,45 +531,44 @@ class PowerSpectra(BaseSpectra):
             self.h5f.flush()
         return ac
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_csm(self):
-        """Main work is done here:
-        Cross spectral matrix is either loaded from cache file or
-        calculated and then additionally stored into cache.
-        """
-        self._handle_dual_calibration()
         if config.global_caching == 'none' or (config.global_caching == 'individual' and self.cached is False):
             return self.calc_csm()
         return self._get_filecache('csm')
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eva(self):
-        """Eigenvalues of cross spectral matrix are either loaded from cache file or
-        calculated and then additionally stored into cache.
-        """
         if config.global_caching == 'none' or (config.global_caching == 'individual' and self.cached is False):
             return self.calc_eva()
         return self._get_filecache('eva')
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eve(self):
-        """Eigenvectors of cross spectral matrix are either loaded from cache file or
-        calculated and then additionally stored into cache.
-        """
         if config.global_caching == 'none' or (config.global_caching == 'individual' and self.cached is False):
             return self.calc_eve()
         return self._get_filecache('eve')
 
     def synthetic_ev(self, freq, num=0):
-        """Return synthesized frequency band values of the eigenvalues.
+        """
+        Retrieve synthetic eigenvalues for a specified frequency or frequency range.
+
+        This method calculates the eigenvalues of the CSM for a single frequency or a synthetic
+        frequency range. If ``num`` is set to ``0``, it retrieves the eigenvalues at the exact
+        frequency. Otherwise, it averages eigenvalues across a range determined by ``freq`` and
+        ``num``.
 
         Parameters
         ----------
-        freq : float
-            Band center frequency for which to return the results.
-        num : integer
-            Controls the width of the frequency bands considered; defaults to
-            3 (third-octave band).
+        freq : :class:`float`
+            The target frequency for which the eigenvalues are calculated. This is the center
+            frequency for synthetic averaging.
+        num : :class:`int`, optional
+            The number of subdivisions in the logarithmic frequency space around the center
+            frequency ``freq``.
+
+            - ``0`` (default): Only the eigenvalues for the exact frequency line are returned.
+            - Non-zero:
 
             ===  =====================
             num  frequency band width
@@ -516,10 +581,25 @@ class PowerSpectra(BaseSpectra):
 
         Returns
         -------
-        float
-            Synthesized frequency band value of the eigenvalues (the sum of
-            all values that are contained in the band).
-
+        :obj:`numpy.ndarray`
+            An array of eigenvalues. If ``num == 0``, the eigenvalues for the single frequency are
+            returned. For ``num > 0``, a summed array of eigenvalues across the synthetic frequency
+            range is returned.
+
+        Examples
+        --------
+        >>> import numpy as np
+        >>> from acoular import TimeSamples
+        >>> from acoular.spectra import PowerSpectra
+        >>> np.random.seed(0)
+        >>>
+        >>> data = np.random.rand(1000, 4)
+        >>> ts = TimeSamples(data=data, sample_freq=51200)
+        >>> ps = PowerSpectra(source=ts, block_size=128, window='Hamming')
+        >>> ps.synthetic_ev(freq=5000, num=5)
+        array([0.00048803, 0.0010141 , 0.00234248, 0.00457097])
+        >>> ps.synthetic_ev(freq=5000)
+        array([0.00022468, 0.0004589 , 0.00088059, 0.00245989])
         """
         f = self.fftfreq()
         if num == 0:
@@ -532,169 +612,67 @@ class PowerSpectra(BaseSpectra):
         return sum(self.eva[f1:f2], 0)
 
 
-def synthetic(data, freqs, f, num=3):
-    """Returns synthesized frequency band values of spectral data.
-
-    If used with :meth:`Beamformer.result()<acoular.fbeamform.BeamformerBase.result>`
-    and only one frequency band, the output is identical to the result of the intrinsic
-    :meth:`Beamformer.synthetic<acoular.fbeamform.BeamformerBase.synthetic>` method.
-    It can, however, also be used with the
-    :meth:`Beamformer.integrate<acoular.fbeamform.BeamformerBase.integrate>`
-    output and more frequency bands.
-
-    Parameters
-    ----------
-    data : array of floats
-        The spectral data (squared sound pressures in Pa^2) in an array with one value
-        per frequency line.
-        The number of entries must be identical to the number of
-        grid points.
-    freq : array of floats
-        The frequencies that correspon to the input *data* (as yielded by
-        the :meth:`PowerSpectra.fftfreq<acoular.spectra.PowerSpectra.fftfreq>`
-        method).
-    f : float or list of floats
-        Band center frequency/frequencies for which to return the results.
-    num : integer
-        Controls the width of the frequency bands considered; defaults to
-        3 (third-octave band).
-
-        ===  =====================
-        num  frequency band width
-        ===  =====================
-        0    single frequency line
-        1    octave band
-        3    third-octave band
-        n    1/n-octave band
-        ===  =====================
-
-    Returns
-    -------
-    array of floats
-        Synthesized frequency band values of the beamforming result at
-        each grid point (the sum of all values that are contained in the band).
-        Note that the frequency resolution and therefore the bandwidth
-        represented by a single frequency line depends on
-        the :attr:`sampling frequency<acoular.base.SamplesGenerator.sample_freq>`
-        and used :attr:`FFT block size<acoular.spectra.PowerSpectra.block_size>`.
-
-    """
-    if isscalar(f):
-        f = (f,)
-    if num == 0:
-        # single frequency lines
-        res = []
-        for i in f:
-            ind = searchsorted(freqs, i)
-            if ind >= len(freqs):
-                warn(
-                    'Queried frequency (%g Hz) not in resolved frequency range. Returning zeros.' % i,
-                    Warning,
-                    stacklevel=2,
-                )
-                h = zeros_like(data[0])
-            else:
-                if freqs[ind] != i:
-                    warn(
-                        f'Queried frequency ({i:g} Hz) not in set of '
-                        'discrete FFT sample frequencies. '
-                        f'Using frequency {freqs[ind]:g} Hz instead.',
-                        Warning,
-                        stacklevel=2,
-                    )
-                h = data[ind]
-            res += [h]
-    else:
-        # fractional octave bands
-        res = []
-        for i in f:
-            f1 = i * 2.0 ** (-0.5 / num)
-            f2 = i * 2.0 ** (+0.5 / num)
-            ind1 = searchsorted(freqs, f1)
-            ind2 = searchsorted(freqs, f2)
-            if ind1 == ind2:
-                warn(
-                    f'Queried frequency band ({f1:g} to {f2:g} Hz) does not '
-                    'include any discrete FFT sample frequencies. '
-                    'Returning zeros.',
-                    Warning,
-                    stacklevel=2,
-                )
-                h = zeros_like(data[0])
-            else:
-                h = sum(data[ind1:ind2], 0)
-            res += [h]
-    return array(res)
-
-
 class PowerSpectraImport(PowerSpectra):
-    """Provides a dummy class for using pre-calculated cross-spectral
-    matrices.
-
-    This class does not calculate the cross-spectral matrix. Instead,
-    the user can inject one or multiple existing CSMs by setting the
-    :attr:`csm` attribute. This can be useful when algorithms shall be
-    evaluated with existing CSM matrices.
-    The frequency or frequencies contained by the CSM must be set via the
-    attr:`frequencies` attribute. The attr:`numchannels` attributes
-    is determined on the basis of the CSM shape.
-    In contrast to the PowerSpectra object, the attributes
-    :attr:`sample_freq`, :attr:`time_data`, :attr:`source`,
-    :attr:`block_size`, :attr:`calib`, :attr:`window`,
-    :attr:`overlap`, :attr:`cached`, and :attr:`num_blocks`
-    have no functionality.
+    """
+    Provides a dummy class for using pre-calculated CSMs.
+
+    This class does not calculate the CSM. Instead, the user can inject one or multiple existing
+    CSMs by setting the :attr:`csm` attribute. This can be useful when algorithms shall be
+    evaluated with existing CSMs. The frequency or frequencies contained by the CSM must be set via
+    the :attr:`frequencies` attribute. The attr:`num_channels` attributes is determined on the basis
+    of the CSM shape. In contrast to the :class:`PowerSpectra` object, the attributes
+    :attr:`sample_freq`, :attr:`source`, :attr:`block_size`, :attr:`window`, :attr:`overlap`,
+    :attr:`cached`, and :attr:`num_blocks` have no functionality.
     """
 
-    #: The cross spectral matrix,
-    #: (number of frequencies, numchannels, numchannels) array of complex;
+    #: The cross-spectral matrix stored in an array of shape ``(n, m, m)`` of complex for ``n``
+    #: frequencies and ``m`` channels.
     csm = Property(desc='cross spectral matrix')
 
-    #: frequencies included in the cross-spectral matrix in ascending order.
-    #: Compound trait that accepts arguments of type list, array, and float
-    frequencies = Trait(None, (CArray, Float), desc='frequencies included in the cross-spectral matrix')
-
-    #: Number of time data channels
-    numchannels = Property(depends_on=['digest'])
+    #: The frequencies included in the CSM in ascending order. Accepts list, array, or a single
+    #: float value.
+    frequencies = Union(CArray, Float, desc='frequencies included in the cross-spectral matrix')
 
-    time_data = Enum(None, desc='PowerSpectraImport cannot consume time data')
+    #: Number of time data channels, inferred from the shape of the CSM.
+    num_channels = Property(depends_on=['digest'])
 
+    #: :class:`PowerSpectraImport` does not consume time data; source is always ``None``.
     source = Enum(None, desc='PowerSpectraImport cannot consume time data')
 
-    # Sampling frequency of the signal, defaults to None
+    #: Sampling frequency of the signal. Default is ``None``
     sample_freq = Enum(None, desc='sampling frequency')
 
+    #: Block size for FFT, non-functional in this class.
     block_size = Enum(None, desc='PowerSpectraImport does not operate on blocks of time data')
 
-    calib = Enum(None, desc='PowerSpectraImport cannot calibrate the time data')
-
+    #: Windowing method, non-functional in this class.
     window = Enum(None, desc='PowerSpectraImport does not perform windowing')
 
+    #: Overlap between blocks, non-functional in this class.
     overlap = Enum(None, desc='PowerSpectraImport does not consume time data')
 
+    #: Caching capability, always disabled.
     cached = Enum(False, desc='PowerSpectraImport has no caching capabilities')
 
+    #: Number of FFT blocks, always ``None``.
     num_blocks = Enum(None, desc='PowerSpectraImport cannot determine the number of blocks')
 
     # Shadow trait, should not be set directly, for internal use.
     _ind_low = Int(0, desc='index of lowest frequency line')
 
     # Shadow trait, should not be set directly, for internal use.
-    _ind_high = Trait(None, (Int, None), desc='index of highest frequency line')
+    _ind_high = Union(None, Int, desc='index of highest frequency line')
 
-    # internal identifier
-    digest = Property(
-        depends_on=[
-            '_csmsum',
-        ],
-    )
+    #: A unique identifier for the spectra, based on its properties. (read-only)
+    digest = Property(depends_on=['_csmsum'])
 
-    #: Name of the cache file without extension, readonly.
-    basename = Property(depends_on='digest', desc='basename for cache file')
+    #: Name of the cache file without extension. (read-only)
+    basename = Property(depends_on=['digest'], desc='basename for cache file')
 
-    # csm shadow trait, only for internal use.
+    # Shadow trait for storing the CSM, for internal use only.
     _csm = CArray()
 
-    # CSM checksum to trigger digest calculation, only for internal use.
+    # Checksum for the CSM to trigger digest calculation, for internal use only.
     _csmsum = Float()
 
     def _get_basename(self):
@@ -704,7 +682,7 @@ class PowerSpectraImport(PowerSpectra):
     def _get_digest(self):
         return digest(self)
 
-    def _get_numchannels(self):
+    def _get_num_channels(self):
         return self.csm.shape[1]
 
     def _get_csm(self):
@@ -712,33 +690,31 @@ class PowerSpectraImport(PowerSpectra):
 
     def _set_csm(self, csm):
         if (len(csm.shape) != 3) or (csm.shape[1] != csm.shape[2]):
-            msg = 'The cross spectral matrix must have the following shape: (number of frequencies, numchannels, numchannels)!'
+            msg = 'The cross spectral matrix must have the following shape: \
+            (number of frequencies, num_channels, num_channels)!'
             raise ValueError(msg)
         self._csmsum = real(self._csm).sum() + (imag(self._csm) ** 2).sum()  # to trigger new digest creation
         self._csm = csm
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eva(self):
-        """Eigenvalues of cross spectral matrix are either loaded from cache file or
-        calculated and then additionally stored into cache.
-        """
         return self.calc_eva()
 
-    @property_depends_on('digest')
+    @property_depends_on(['digest'])
     def _get_eve(self):
-        """Eigenvectors of cross spectral matrix are either loaded from cache file or
-        calculated and then additionally stored into cache.
-        """
         return self.calc_eve()
 
     def fftfreq(self):
-        """Return the Discrete Fourier Transform sample frequencies.
+        """
+        Return the Discrete Fourier Transform sample frequencies.
+
+        The method checks the type of :attr:`frequencies` and returns the corresponding frequency
+        array. If :attr:`frequencies` is not defined, a warning is raised.
 
         Returns
         -------
-        f : ndarray
+        :obj:`numpy.ndarray`
             Array containing the frequencies.
-
         """
         if isinstance(self.frequencies, float):
             return array([self.frequencies])