acoular 25.3.post1__py3-none-any.whl → 25.7__py3-none-any.whl

acoular/__init__.py

@@ -16,7 +16,6 @@ from .base import (
     SamplesGenerator,
     SpectraGenerator,
     SpectraOut,
-    TimeInOut,
     TimeOut,
 )
 from .calib import Calib
@@ -52,7 +51,7 @@ from .fbeamform import (
     SteeringVector,
     integrate,
 )
-from .fprocess import IRFFT, RFFT, AutoPowerSpectra, CrossPowerSpectra, FFTSpectra
+from .fprocess import IRFFT, RFFT, AutoPowerSpectra, CrossPowerSpectra
 from .grids import (
     CircSector,
     ConvexSector,
@@ -69,7 +68,7 @@ from .grids import (
     Sector,
 )
 from .microphones import MicGeom
-from .process import Average, Cache, SampleSplitter, TimeAverage, TimeCache
+from .process import Average, Cache, SampleSplitter
 from .sdinput import SoundDeviceSamplesGenerator
 from .signals import (
     FiltWNoiseGenerator,
@@ -117,7 +116,6 @@ from .tprocess import (
     FiltFiltOctave,
     FiltFreqWeight,
     FiltOctave,
-    MaskedTimeInOut,
     MaskedTimeOut,
     Mixer,
     OctaveFilterBank,

acoular/aiaa/aiaa.py

@@ -32,6 +32,7 @@ from traits.api import (
     File,
     Instance,
     Property,
+    Union,
     cached_property,
     on_trait_change,
     property_depends_on,
@@ -84,12 +85,12 @@ class TriggerAIAABenchmark(TimeSamplesAIAABenchmark):
         (self.num_samples, self.num_channels) = self.data.shape
 
 
-@deprecated_alias({'name': 'file'})
+@deprecated_alias({'name': 'file'}, removal_version='25.10')
 class CsmAIAABenchmark(PowerSpectraImport):
     """Class to load the CSM that is stored in AIAA Benchmark HDF5 file."""
 
     #: Full name of the .h5 file with data
-    file = File(filter=['*.h5'], exists=True, desc='name of data file')
+    file = Union(None, File(filter=['*.h5'], exists=True), desc='name of data file')
 
     #: Basename of the .h5 file with data, is set automatically.
     basename = Property(
@@ -167,11 +168,15 @@ class MicAIAABenchmark(MicGeom):
     """
 
     #: Name of the .h5-file from which to read the data.
-    file = File(filter=['*.h5'], exists=True, desc='name of the h5 file containing the microphone geometry')
+    file = Union(
+        None, File(filter=['*.h5'], exists=True), desc='name of the h5 file containing the microphone geometry'
+    )
 
     @on_trait_change('file')
     def _import_mpos(self):
-        """Import the microphone positions from .h5 file.
+        """
+        Import the microphone positions from .h5 file.
+
         Called when :attr:`basename` changes.
         """
         file = _get_h5file_class()

acoular/base.py

@@ -16,7 +16,6 @@ to be used directly, but to be subclassed by classes that implement the actual s
     InOut
     TimeOut
     SpectraOut
-    TimeInOut
 """
 
 from abc import abstractmethod
@@ -37,7 +36,7 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'})
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, removal_version='25.10')
 class Generator(ABCHasStrictTraits):
     """Interface for any generating signal processing block.
 
@@ -157,10 +156,10 @@ class SpectraGenerator(Generator):
         """
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class TimeOut(SamplesGenerator):
-    """Abstract base class for any signal processing block that receives data from any
-    :attr:`source` domain and returns time domain signals.
+    """
+    Abstract base class receiving from a :attr:`source` and returning time domain signals.
 
     It provides a base class that can be used to create signal processing blocks that receive data
     from any generating :attr:`source` and generates a time signal output via the generator
@@ -205,10 +204,14 @@ class TimeOut(SamplesGenerator):
         """
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples', 'numfreqs': 'num_freqs'}, read_only=True)
+@deprecated_alias(
+    {'numchannels': 'num_channels', 'numsamples': 'num_samples', 'numfreqs': 'num_freqs'},
+    read_only=True,
+    removal_version='25.10',
+)
 class SpectraOut(SpectraGenerator):
-    """Abstract base class for any signal processing block that receives data from any
-    :attr:`source` domain and returns frequency domain signals.
+    """
+    Abstract base class receiving from a :attr:`source` and returning frequency domain signals.
 
     It provides a base class that can be used to create signal processing blocks that receive data
     from any generating :attr:`source` domain and generates a frequency domain output via the
@@ -260,10 +263,10 @@ class SpectraOut(SpectraGenerator):
         """
 
 
-@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True)
+@deprecated_alias({'numchannels': 'num_channels', 'numsamples': 'num_samples'}, read_only=True, removal_version='25.10')
 class InOut(SamplesGenerator, SpectraGenerator):
-    """Abstract base class for any signal processing block that receives data from any
-    :attr:`source` domain and returns signals in the same domain.
+    """
+    Abstract base class receiving from a :attr:`source` and returning signals in the same domain.
 
     It provides a base class that can be used to create signal processing blocks that receive data
     from any generating :attr:`source` and generates an output via the generator :meth:`result` in
@@ -308,25 +311,3 @@ class InOut(SamplesGenerator, SpectraGenerator):
         numpy.ndarray
             Two-dimensional output data block of shape (num, ...)
         """
-
-
-class TimeInOut(TimeOut):
-    """Deprecated alias for :class:`~acoular.base.TimeOut`.
-
-    .. deprecated:: 24.10
-        Using :class:`~acoular.base.TimeInOut` is deprecated and will be removed in Acoular 25.07.
-        Use :class:`~acoular.base.TimeOut` instead.
-    """
-
-    #: Data source; :class:`~acoular.base.SamplesGenerator` or derived object.
-    source = Instance(SamplesGenerator)
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        import warnings
-
-        warnings.warn(
-            'TimeInOut is deprecated and will be removed in Acoular 25.07. Use TimeOut instead.',
-            DeprecationWarning,
-            stacklevel=2,
-        )

acoular/calib.py

@@ -13,7 +13,7 @@
 import xml.dom.minidom
 
 from numpy import array, newaxis
-from traits.api import CArray, CInt, File, List, Property, cached_property, on_trait_change
+from traits.api import CArray, CInt, File, List, Property, Union, cached_property, on_trait_change
 
 import acoular as ac
 
@@ -24,7 +24,7 @@ from .deprecation import deprecated_alias
 from .internal import digest
 
 
-@deprecated_alias({'from_file': 'file'})
+@deprecated_alias({'from_file': 'file'}, removal_version='25.10')
 class Calib(InOut):
     """Processing block for handling calibration data in `*.xml` or NumPy format.
 
@@ -72,13 +72,12 @@ class Calib(InOut):
     0.07458428+0.49657939j  1.772696  +3.92233098j  3.19543248+0.17988554j
     0.3379041 -3.93342331j  0.93949242+2.5328611j   2.97352574+0.j        ]]
 
-    Deprecated and will be removed in Acoular 25.10:
     This class serves as interface to load calibration data for the used
     microphone array. The calibration factors are stored as [Pa/unit].
     """
 
     #: Name of the .xml file to be imported.
-    file = File(filter=['*.xml'], exists=True, desc='name of the xml file to import')
+    file = Union(None, File(filter=['*.xml'], exists=True), desc='name of the xml file to import')
 
     #: Number of microphones in the calibration data,
     #: is set automatically when read from file or when data is set.
@@ -102,6 +101,7 @@ class Calib(InOut):
 
     @on_trait_change('data')
     def set_num_mics(self):
+        """Sets the number of microphones based on the shape of the data array."""
         self.num_mics = self.data.shape[0]
 
     @cached_property

acoular/configuration.py

@@ -68,7 +68,7 @@ class Config(HasStrictTraits):
     The package used to read and write .h5 files can be specified
     by :attr:`h5library`.
 
-    Example:
+    Examples
     --------
         For using Acoular with h5py package and overwrite existing cache:
 

acoular/demo/__init__.py

@@ -11,4 +11,9 @@
 """
 
 from . import acoular_demo
-from .acoular_demo import create_three_sources
+from .acoular_demo import (
+    create_three_sources,
+    create_three_sources_1d,
+    create_three_sources_2d,
+    create_three_sources_3d,
+)

acoular/demo/acoular_demo.py

@@ -33,28 +33,52 @@ Source Location        RMS
 
 
 def create_three_sources(mg, h5savefile='three_sources.h5'):
-    """Create three noise sources and return them as Mixer."""
-    import acoular as ac
+    """
+    Create three noise sources and return them as Mixer.
+
+    Alias for :func:`create_three_sources_2d`.
+    """
+    return create_three_sources_2d(mg, h5savefile=h5savefile)
+
 
-    # set up the parameters
+def _create_three_sources(mg, locs, h5savefile='', sfreq=51200, duration=1):
+    """Create three noise sources with custom locations and return them as Mixer."""
+    import acoular as ac
 
-    sfreq = 51200
-    duration = 1
     nsamples = duration * sfreq
 
     n1 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=1)
     n2 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=2, rms=0.7)
     n3 = ac.WNoiseGenerator(sample_freq=sfreq, num_samples=nsamples, seed=3, rms=0.5)
-    p1 = ac.PointSource(signal=n1, mics=mg, loc=(-0.1, -0.1, -0.3))
-    p2 = ac.PointSource(signal=n2, mics=mg, loc=(0.15, 0, -0.3))
-    p3 = ac.PointSource(signal=n3, mics=mg, loc=(0, 0.1, -0.3))
-    pa = ac.Mixer(source=p1, sources=[p2, p3])
+
+    noises = [n1, n2, n3]
+    ps = [ac.PointSource(signal=n, mics=mg, loc=loc) for n, loc in list(zip(noises, locs))]
+    pa = ac.Mixer(source=ps[0], sources=ps[1:])
+
     if h5savefile:
         wh5 = ac.WriteH5(source=pa, file=h5savefile)
         wh5.save()
     return pa
 
 
+def create_three_sources_1d(mg, h5savefile='three_sources_1d.h5'):
+    """Create three noise sources on a 1D line and return them as Mixer."""
+    locs = [(-0.1, 0, -0.3), (0.15, 0, -0.3), (0, 0, -0.3)]
+    return _create_three_sources(mg, locs, h5savefile=h5savefile)
+
+
+def create_three_sources_2d(mg, h5savefile='three_sources_2d.h5'):
+    """Create three noise sources in a 2D plane and return them as Mixer."""
+    locs = [(-0.1, -0.1, -0.3), (0.15, 0, -0.3), (0, 0.1, -0.3)]
+    return _create_three_sources(mg, locs, h5savefile=h5savefile)
+
+
+def create_three_sources_3d(mg, h5savefile='three_sources_3d.h5'):
+    """Create three noise sources in 3D space and return them as Mixer."""
+    locs = [(-0.1, -0.1, -0.3), (0.15, 0, -0.17), (0, 0.1, -0.25)]
+    return _create_three_sources(mg, locs, h5savefile=h5savefile)
+
+
 def run():
     """Run the Acoular demo."""
     from pathlib import Path
@@ -87,7 +111,7 @@ def run():
         from matplotlib.pyplot import axis, colorbar, figure, imshow, plot, show
 
         # show map
-        imshow(spl.T, origin='lower', vmin=spl.max() - 10, extent=rg.extend(), interpolation='bicubic')
+        imshow(spl.T, origin='lower', vmin=spl.max() - 10, extent=rg.extent, interpolation='bicubic')
         colorbar()
 
         # plot microphone geometry

acoular/deprecation.py

@@ -1,6 +1,13 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
+"""Implements helper functions for deprecation handling.
+
+.. autosummary::
+    :toctree: generated/
+
+    deprecated_alias
+"""
 
 from warnings import warn
 
@@ -8,7 +15,9 @@ from traits.api import Property
 
 
 def deprecated_alias(old2new, read_only=False, removal_version=''):
-    """Decorator function for deprecating renamed class traits.
+    """
+    Decorator function for deprecating renamed class traits.
+
     Replaced traits should no longer be part of the class definition
     and only mentioned in this decorator's parameter list.
     The replacement trait has to be defined in the updated class and
@@ -66,7 +75,10 @@ def deprecated_alias(old2new, read_only=False, removal_version=''):
             else:
                 current_removal_version = ''
             # Define Trait Property type
-            trait_type = Property(*_alias_accessor_factory(old, new, current_read_only, current_removal_version))
+            trait_type = Property(
+                *_alias_accessor_factory(old, new, current_read_only, current_removal_version),
+                transient=True,
+            )
 
             # If the new trait exists, set or update alias
             if new in cls.class_traits():

acoular/environments.py

@@ -557,8 +557,7 @@ class OpenJet(FlowField):
 
 class RotatingFlow(FlowField):
     """
-    Analytical approximation of a rotating flow field with additional velocity component
-    in z-direction.
+    Analytical approximation of a rotating flow field with velocity component in z-direction.
 
     This class provides an analytical model for a fluid flow field with a
     rigid-body-like rotation about the z-axis. The flow combines rotational motion
@@ -591,11 +590,12 @@ class RotatingFlow(FlowField):
     # Positive values indicate clockwise rotation of the flow.
     # This is contrary to the usual definition of the direction of rotation.
     # Deprecated! Please use the differently defined :attr:`rps` attribute instead.
-    rpm = Property(desc='revolutions per minute of the flow; positive values for clockwise rotation')
+    rpm = Property(transient=True, desc='revolutions per minute of the flow; positive values for clockwise rotation')
 
     def _get_rpm(self):
         warn(
-            'Deprecated use of "rpm" trait. Please use the "rps" trait instead.',
+            'Deprecated use of "rpm" trait (will be removed in version 26.01). \
+            Please use the "rps" trait instead.',
             DeprecationWarning,
             stacklevel=2,
         )
@@ -603,7 +603,8 @@ class RotatingFlow(FlowField):
 
     def _set_rpm(self, rpm):
         warn(
-            'Deprecated use of "rpm" trait. Please use the "rps" trait instead (divide rpm value by -60).',
+            'Deprecated use of "rpm" trait (will be removed in version 26.01). \
+            Please use the "rps" trait instead (divide rpm value by -60).',
             DeprecationWarning,
             stacklevel=2,
         )

acoular/fastFuncs.py

@@ -1,9 +1,7 @@
 # ------------------------------------------------------------------------------
 # Copyright (c) Acoular Development Team.
 # ------------------------------------------------------------------------------
-"""Contains all the functionalities which are very expansive, regarding
-computational costs. All functionalities are optimized via NUMBA.
-"""
+"""Contains all computationally expensive operations and accelerates them with NUMBA."""
 
 import numba as nb
 import numpy as np
@@ -27,7 +25,8 @@ FAST_OPTION = True  # fastmath options
 )
 def calcCSM(csm, SpecAllMics):
     """Adds a given spectrum to the Cross-Spectral-Matrix (CSM).
-    Here only the upper triangular matrix of the CSM is calculated. After
+
+    Here, only the upper triangular matrix of the CSM is calculated. After
     averaging over the various ensembles, the whole CSM is created via complex
     conjugation transposing. This happens outside
     (in :class:`PowerSpectra<acoular.spectra.PowerSpectra>`).
@@ -56,9 +55,11 @@ def calcCSM(csm, SpecAllMics):
 
 
 def beamformerFreq(steerVecType, boolRemovedDiagOfCSM, normFactor, inputTupleSteer, inputTupleCsm):
-    r"""Conventional beamformer in frequency domain. Use either a predefined
-    steering vector formulation (see Sarradj 2012) or pass your own
-    steering vector.
+    r"""
+    Conventional beamformer in frequency domain.
+
+    Use either a predefined steering vector formulation (see Sarradj 2012) or pass your own steering
+    vector.
 
     Parameters
     ----------
@@ -545,8 +546,11 @@ def _freqBeamformer_EigValProb_SpecificSteerVec_CsmRemovedDiag(
 
 # %% Point - Spread - Function
 def calcPointSpreadFunction(steerVecType, distGridToArrayCenter, distGridToAllMics, waveNumber, indSource, dtype):
-    r"""Calculates the Point-Spread-Functions. Use either a predefined steering vector
-    formulation (see :ref:`Sarradj, 2012<Sarradj2012>`) or pass it your own steering vector.
+    r"""
+    Calculates the Point-Spread-Functions.
+
+    Use either a predefined steering vector formulation (see :ref:`Sarradj, 2012<Sarradj2012>`) or
+    pass it your own steering vector.
 
     Parameters
     ----------
@@ -789,7 +793,9 @@ def _psf_Formulation4AkaTrueLocation(
     fastmath=FAST_OPTION,
 )
 def damasSolverGaussSeidel(A, dirtyMap, nIterations, relax, damasSolution):
-    """Solves the DAMAS inverse problem via modified gauss seidel.
+    """
+    Solves the DAMAS inverse problem via modified gauss seidel.
+
     This is the original formulation from :ref:`Brooks and Humphreys, 2006<BrooksHumphreys2006>`.
 
     Parameters