acoular 25.10__tar.gz → 26.1__tar.gz

{acoular-25.10 → acoular-26.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: acoular
-Version: 25.10
+Version: 26.1
 Summary: Python library for acoustic beamforming
 Project-URL: homepage, https://acoular.org
 Project-URL: documentation, https://acoular.org
@@ -51,65 +51,14 @@ Requires-Python: <3.14,>=3.10
 Requires-Dist: numba
 Requires-Dist: numpy
 Requires-Dist: scikit-learn
-Requires-Dist: scipy!=1.16.*,>=1.1.0
+Requires-Dist: scipy!=1.16.0,>=1.15; python_version == '3.10'
+Requires-Dist: scipy>=1.16.1; python_version > '3.10'
 Requires-Dist: tables
 Requires-Dist: traits>=6.0
-Provides-Extra: dev
-Requires-Dist: graphviz; extra == 'dev'
-Requires-Dist: h5py; extra == 'dev'
-Requires-Dist: hatch; extra == 'dev'
-Requires-Dist: ipython; extra == 'dev'
-Requires-Dist: matplotlib; extra == 'dev'
-Requires-Dist: numpydoc; extra == 'dev'
-Requires-Dist: pickleshare; extra == 'dev'
-Requires-Dist: pydata-sphinx-theme; extra == 'dev'
-Requires-Dist: pylops; extra == 'dev'
-Requires-Dist: pytest; extra == 'dev'
-Requires-Dist: pytest-cases; extra == 'dev'
-Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: pytest-env; extra == 'dev'
-Requires-Dist: pytest-mock; extra == 'dev'
-Requires-Dist: pytest-profiling; extra == 'dev'
-Requires-Dist: pytest-regtest; extra == 'dev'
-Requires-Dist: pyyaml; extra == 'dev'
-Requires-Dist: ruff==0.8.1; extra == 'dev'
-Requires-Dist: setuptools; extra == 'dev'
-Requires-Dist: sounddevice; extra == 'dev'
-Requires-Dist: sphinx; extra == 'dev'
-Requires-Dist: sphinx-copybutton; extra == 'dev'
-Requires-Dist: sphinx-gallery; extra == 'dev'
-Requires-Dist: sphinxcontrib-bibtex; extra == 'dev'
-Requires-Dist: traitsui; extra == 'dev'
-Provides-Extra: docs
-Requires-Dist: graphviz; extra == 'docs'
-Requires-Dist: ipython; extra == 'docs'
-Requires-Dist: matplotlib; extra == 'docs'
-Requires-Dist: numpydoc; extra == 'docs'
-Requires-Dist: pickleshare; extra == 'docs'
-Requires-Dist: pydata-sphinx-theme; extra == 'docs'
-Requires-Dist: setuptools; extra == 'docs'
-Requires-Dist: sounddevice; extra == 'docs'
-Requires-Dist: sphinx; extra == 'docs'
-Requires-Dist: sphinx-copybutton; extra == 'docs'
-Requires-Dist: sphinx-gallery; extra == 'docs'
-Requires-Dist: sphinxcontrib-bibtex; extra == 'docs'
 Provides-Extra: full
 Requires-Dist: matplotlib; extra == 'full'
 Requires-Dist: pylops; extra == 'full'
 Requires-Dist: sounddevice; extra == 'full'
-Provides-Extra: tests
-Requires-Dist: h5py; extra == 'tests'
-Requires-Dist: pylops; extra == 'tests'
-Requires-Dist: pytest; extra == 'tests'
-Requires-Dist: pytest-cases; extra == 'tests'
-Requires-Dist: pytest-cov; extra == 'tests'
-Requires-Dist: pytest-env; extra == 'tests'
-Requires-Dist: pytest-mock; extra == 'tests'
-Requires-Dist: pytest-profiling; extra == 'tests'
-Requires-Dist: pytest-regtest; extra == 'tests'
-Requires-Dist: pyyaml; extra == 'tests'
-Requires-Dist: sounddevice; extra == 'tests'
-Requires-Dist: traitsui; extra == 'tests'
 Description-Content-Type: text/markdown
 
 ![Acoular Logo](https://github.com/acoular/acoular/blob/master/docs/source/_static/Acoular_logo.png?raw=true)
@@ -117,45 +66,57 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/pyversions/acoular.svg)](https://pypi.org/project/acoular)
 [![PyPI](https://img.shields.io/pypi/v/acoular.svg)](https://pypi.org/project/acoular)
 [![Actions status](https://github.com/acoular/acoular/actions/workflows/tests.yml/badge.svg)](https://github.com/acoular/acoular/actions)
-[![DOI](https://zenodo.org/badge/29729101.svg)](https://zenodo.org/doi/10.5281/zenodo.3690794)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/3690794.svg)](https://zenodo.org/doi/10.5281/zenodo.3690794)
 
 # Acoular
-Acoular is a Python module for acoustic beamforming that is distributed under the new BSD license. 
-
-It is aimed at applications in acoustic testing. Multichannel data recorded by a microphone array can be processed and analyzed in order to generate mappings of sound source distributions. The maps (acoustic photographs) can then be used to locate sources of interest and to characterize them using their spectra. 
-
-# Features
-- frequency domain beamforming algorithms: delay & sum, Capon (adaptive), MUSIC, functional beamforming, eigenvalue beamforming
-- frequency domain deconvolution algorithms: DAMAS, DAMAS+, Clean, CleanSC, orthogonal deconvolution
-- frequency domain inverse methods: CMF (covariance matrix fitting), general inverse beamforming, SODIX
-- time domain methods: delay & sum beamforming, CleanT deconvolution
-- time domain methods applicable for moving sources with arbitrary trajectory (linear, circular, arbitrarily 3D curved), 
-- frequency domain methods for rotating sources via virtual array rotation for arbitrary arrays and with different interpolation techniques
+Acoular is a Python module for acoustic beamforming that is distributed under the [BSD 3-clause license](LICENSE). 
+
+It is aimed at (but not limited to) applications in acoustic testing. Multichannel data recorded by microphone arrays can be processed and analyzed to generate mappings of sound source distributions. The maps (acoustic photographs) can then be used to locate sources of interest and to characterize them using their spectra. 
+
+👁️📢 Please consider taking the [**Acoular User Survey**](https://www.soscisurvey.de/acoularsurvey). It only takes 2 minutes.
+
+- **Website:** https://acoular.org
+- **Blog:** https://blog.acoular.org
+- **Installation:** https://acoular.org/install
+- **Getting Started** https://acoular.org/user_guide/get_started.html
+- **User Guide:** https://acoular.org/user_guide
+- **API Reference:** https://acoular.org/api_ref
+- **Examples:** https://acoular.org/auto_examples
+- **Contributing:** https://acoular.org/contributing
+- **Questions?:** https://github.com/orgs/acoular/discussions
+- **Bug Reports:** https://github.com/acoular/acoular/issues
+- **Report a Security Vulnerability:** https://github.com/acoular/acoular/security/advisories/new
+
+## Highlights
+- frequency domain methods:
+  - **beamforming:** delay & sum, Capon (adaptive), MUSIC, functional and eigenvalue beamforming
+  - **deconvolution:** DAMAS, DAMAS+, Clean, CleanSC, (gridless) orthogonal deconvolution
+  - **inverse methods:** CMF (covariance matrix fitting), general inverse beamforming, SODIX
+- time domain methods:
+  - **beamforming:** delay & sum
+  - **deconvolution:** CleanT
 - 1D, 2D and 3D mapping grids for all methods
-- gridless option for orthogonal deconvolution
-- four different built-in steering vector formulations
-- arbitrary stationary background flow can be considered for all methods
-- efficient cross spectral matrix computation
-- flexible modular time domain processing: n-th octave band filters, fast, slow, and impulse weighting, A-, C-, and Z-weighting, filter bank, zero delay filters
-- time domain simulation of array microphone signals from fixed and arbitrarily moving sources in arbitrary flow
-- fully object-oriented interface
-- lazy evaluation: while processing blocks are set up at any time, (expensive) computations are only performed when needed
-- intelligent and transparent caching: computed results are automatically saved and loaded on the next run to avoid unnecessary re-computation
-- parallel (multithreaded) implementation with Numba for most algorithms
-- easily extendable with new algorithms
-
-# License
-Acoular is licensed under the BSD 3-clause. See [LICENSE](LICENSE)
-
-# Citing
-
+- arbitrary stationary background 🌬️ **flow** can be considered for all methods
+- frequency domain methods for 🌀 **rotating sources** via virtual array rotation for arbitrary arrays
+- all time domain methods can identify 🚂🛩️ **moving sources** with arbitrary trajectory
+- flexible & modular 🧮 **signal processing**:
+  - n-th octave band filters
+  - fast, slow, and impulse weighting
+  - A-, C-, and Z-weighting
+  - filter bank
+  - linear phase filters
+- intelligent and transparent :floppy_disk: **caching**: computed results are automatically saved and loaded on the next run to avoid unnecessary re-computation.
+- 🦥 **lazy** evaluation: while processing blocks are set up at any time, (expensive) computations are only performed when needed.
+- 🏎️ **efficient & parallel** (multithreaded) computation with [Numba](https://numba.pydata.org) for most algorithms.
+
+## Citing
 If you use Acoular for academic work, please consider citing both our
 [publication](https://doi.org/10.1016/j.apacoust.2016.09.015):
 
     Sarradj, E., & Herold, G. (2017). 
     A Python framework for microphone array data processing.
     Applied Acoustics, 116, 50–58. 
-    https://doi.org/10.1016/j.apacoust.2016.09
+    https://doi.org/10.1016/j.apacoust.2016.09.015
 
 and our [software](https://zenodo.org/doi/10.5281/zenodo.3690794):
 
@@ -163,41 +124,26 @@ and our [software](https://zenodo.org/doi/10.5281/zenodo.3690794):
     Acoular – Acoustic testing and source mapping software. 
     Zenodo. https://zenodo.org/doi/10.5281/zenodo.3690794
 
-# Dependencies
-Acoular runs under Linux, Windows and MacOS and needs Numpy, Scipy, Traits, scikit-learn, pytables, Numba packages available. 
-Matplotlib is needed for some of the examples.
-
-If you want to use input from a soundcard, you will also need to install the [sounddevice](https://python-sounddevice.readthedocs.io/en/0.3.12/installation.html) package. Some solvers for the CMF method need [Pylops](https://pylops.readthedocs.io/en/stable/installation.html).
+## Installation
 
-# Installation
+Acoular can be installed from [PyPI](https://pypi.org/project/acoular). It is recommended to use a [virtual environment](https://docs.python.org/3/library/venv.html). Inside the environment, run
 
-Acoular can be installed via [conda](https://docs.conda.io/en/latest/), which is also part of the [Anaconda Python distribution](https://www.anaconda.com/). It is recommended to install into a dedicated [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). After activating this environment, run
+    pip install acoular
+    
+A second option is to install Acoular with [conda](https://docs.conda.io/en/latest/). It is recommended to install into a dedicated [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). After activating the environment, run
 
     conda install -c acoular acoular
 
-This will install Acoular in your Anaconda Python environment and make the Acoular library available from Python. In addition, this will install all dependencies (those other packages mentioned above) if they are not already present on your system. 
-
-A second option is to install Acoular via [pip](https://pip.pypa.io/en/stable/). It is recommended to use a dedicated [virtual environment](https://virtualenv.pypa.io/en/latest/) and then run
-
-    pip install acoular
-
 For more detailed installation instructions, see the [documentation](https://acoular.org/install/index.html).
 
-# Documentation and help
+## Documentation and help
 Documentation is available [here](https://acoular.org) with a
-[getting started](https://acoular.org/get_started/index.html) section and
+[getting started](https://www.acoular.org/user_guide/get_started.html) section and
 [examples](https://acoular.org/auto_examples/index.html).
 
-The Acoular [blog](https://acoular.github.io/blog/) contains some tutorials.
-
 If you discover problems with the Acoular software, please report them using the [issue tracker](https://github.com/acoular/acoular/issues) on GitHub. Please use the [Acoular discussions forum](https://github.com/acoular/acoular/discussions) for practical questions, discussions, and demos.
 
-# Contributing
-
-We are always happy to welcome new contributors to the project. 
-If you are interested in contributing, have a look at the [CONTRIBUTING.md](CONTRIBUTING.md) file.
-
-# Example
+## Example
 This reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band:
 
 ```python
@@ -244,4 +190,3 @@ plt.show()
 
 ![result](https://github.com/acoular/acoular/blob/master/docs/source/user_guide/three_source_py3_colormap.png?raw=true)
 
-

acoular-26.1/README.md

@@ -0,0 +1,129 @@
+![Acoular Logo](https://github.com/acoular/acoular/blob/master/docs/source/_static/Acoular_logo.png?raw=true)
+
+[![PyPI](https://img.shields.io/pypi/pyversions/acoular.svg)](https://pypi.org/project/acoular)
+[![PyPI](https://img.shields.io/pypi/v/acoular.svg)](https://pypi.org/project/acoular)
+[![Actions status](https://github.com/acoular/acoular/actions/workflows/tests.yml/badge.svg)](https://github.com/acoular/acoular/actions)
+[![DOI](https://zenodo.org/badge/DOI/10.5281/3690794.svg)](https://zenodo.org/doi/10.5281/zenodo.3690794)
+
+# Acoular
+Acoular is a Python module for acoustic beamforming that is distributed under the [BSD 3-clause license](LICENSE). 
+
+It is aimed at (but not limited to) applications in acoustic testing. Multichannel data recorded by microphone arrays can be processed and analyzed to generate mappings of sound source distributions. The maps (acoustic photographs) can then be used to locate sources of interest and to characterize them using their spectra. 
+
+👁️📢 Please consider taking the [**Acoular User Survey**](https://www.soscisurvey.de/acoularsurvey). It only takes 2 minutes.
+
+- **Website:** https://acoular.org
+- **Blog:** https://blog.acoular.org
+- **Installation:** https://acoular.org/install
+- **Getting Started** https://acoular.org/user_guide/get_started.html
+- **User Guide:** https://acoular.org/user_guide
+- **API Reference:** https://acoular.org/api_ref
+- **Examples:** https://acoular.org/auto_examples
+- **Contributing:** https://acoular.org/contributing
+- **Questions?:** https://github.com/orgs/acoular/discussions
+- **Bug Reports:** https://github.com/acoular/acoular/issues
+- **Report a Security Vulnerability:** https://github.com/acoular/acoular/security/advisories/new
+
+## Highlights
+- frequency domain methods:
+  - **beamforming:** delay & sum, Capon (adaptive), MUSIC, functional and eigenvalue beamforming
+  - **deconvolution:** DAMAS, DAMAS+, Clean, CleanSC, (gridless) orthogonal deconvolution
+  - **inverse methods:** CMF (covariance matrix fitting), general inverse beamforming, SODIX
+- time domain methods:
+  - **beamforming:** delay & sum
+  - **deconvolution:** CleanT
+- 1D, 2D and 3D mapping grids for all methods
+- arbitrary stationary background 🌬️ **flow** can be considered for all methods
+- frequency domain methods for 🌀 **rotating sources** via virtual array rotation for arbitrary arrays
+- all time domain methods can identify 🚂🛩️ **moving sources** with arbitrary trajectory
+- flexible & modular 🧮 **signal processing**:
+  - n-th octave band filters
+  - fast, slow, and impulse weighting
+  - A-, C-, and Z-weighting
+  - filter bank
+  - linear phase filters
+- intelligent and transparent :floppy_disk: **caching**: computed results are automatically saved and loaded on the next run to avoid unnecessary re-computation.
+- 🦥 **lazy** evaluation: while processing blocks are set up at any time, (expensive) computations are only performed when needed.
+- 🏎️ **efficient & parallel** (multithreaded) computation with [Numba](https://numba.pydata.org) for most algorithms.
+
+## Citing
+If you use Acoular for academic work, please consider citing both our
+[publication](https://doi.org/10.1016/j.apacoust.2016.09.015):
+
+    Sarradj, E., & Herold, G. (2017). 
+    A Python framework for microphone array data processing.
+    Applied Acoustics, 116, 50–58. 
+    https://doi.org/10.1016/j.apacoust.2016.09.015
+
+and our [software](https://zenodo.org/doi/10.5281/zenodo.3690794):
+
+    Sarradj, E., Herold, G., Kujawski, A., Jekosch, S., Pelling, A. J. R., Czuchaj, M., Gensch, T., & Oertwig, S..
+    Acoular – Acoustic testing and source mapping software. 
+    Zenodo. https://zenodo.org/doi/10.5281/zenodo.3690794
+
+## Installation
+
+Acoular can be installed from [PyPI](https://pypi.org/project/acoular). It is recommended to use a [virtual environment](https://docs.python.org/3/library/venv.html). Inside the environment, run
+
+    pip install acoular
+    
+A second option is to install Acoular with [conda](https://docs.conda.io/en/latest/). It is recommended to install into a dedicated [conda environment](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html). After activating the environment, run
+
+    conda install -c acoular acoular
+
+For more detailed installation instructions, see the [documentation](https://acoular.org/install/index.html).
+
+## Documentation and help
+Documentation is available [here](https://acoular.org) with a
+[getting started](https://www.acoular.org/user_guide/get_started.html) section and
+[examples](https://acoular.org/auto_examples/index.html).
+
+If you discover problems with the Acoular software, please report them using the [issue tracker](https://github.com/acoular/acoular/issues) on GitHub. Please use the [Acoular discussions forum](https://github.com/acoular/acoular/discussions) for practical questions, discussions, and demos.
+
+## Example
+This reads data from 64 microphone channels and computes a beamforming map for the 8kHz third octave band:
+
+```python
+from pathlib import Path
+
+import acoular as ac
+import matplotlib.pylab as plt
+
+# this file contains the microphone coordinates
+micgeofile = Path(ac.__file__).parent / 'xml' / 'array_64.xml'
+# set up object managing the microphone coordinates
+mg = ac.MicGeom( file=micgeofile )
+# generate test data, in real life this would come from an array measurement
+p = ac.demo.create_three_sources(mg, h5savefile='three_sources.h5')
+# set up object managing the microphone array data (usually from measurement)
+ts = ac.TimeSamples( file='three_sources.h5')
+# set up object managing the cross spectral matrix computation
+ps = ac.PowerSpectra( source=ts, block_size=128, window='Hanning' )
+# alternatively, you can use the in-memory Mixer object directly:
+# ps = ac.PowerSpectra( source=p, block_size=128, window='Hanning' )
+# set up object managing the mapping grid
+rg = ac.RectGrid( x_min=-0.2, x_max=0.2, y_min=-0.2, y_max=0.2, z=-0.3, \
+increment=0.01 )
+# set up steering vector, implicitely contains also the standard quiescent 
+# environment with standard speed of sound
+st = ac.SteeringVector( grid = rg, mics=mg )
+# set up the object managing the delay & sum beamformer
+bb = ac.BeamformerBase( freq_data=ps, steer=st )
+# request the result in the 8kHz third octave band from approriate FFT-Lines
+# this starts the actual computation (data intake, FFT, Welch CSM, beamforming)
+pm = bb.synthetic( 8000, 3 )
+# compute the sound pressure level
+Lm = ac.L_p( pm )
+# plot the map
+plt.imshow( Lm.T, origin='lower', vmin=Lm.max()-10, extent=rg.extent, \
+interpolation='bicubic')
+plt.title('Beamformer (base) for 3 sources measured for 8000 Hz')
+plt.xlabel('x in m')
+plt.ylabel('y in m')
+plt.colorbar(label=r'$L_p$')
+plt.savefig('three_sources.png', dpi=300, bbox_inches='tight')
+plt.show()
+```
+
+![result](https://github.com/acoular/acoular/blob/master/docs/source/user_guide/three_source_py3_colormap.png?raw=true)
+

{acoular-25.10 → acoular-26.1}/acoular/aiaa/aiaa.py

@@ -102,7 +102,7 @@ class CsmAIAABenchmark(PowerSpectraImport):
     #: HDF5 file object
     h5f = Instance(H5FileBase, transient=True)
 
-    # internal identifier
+    #: A unique identifier for the CSM importer, based on its properties. (read-only)
     digest = Property(depends_on=['basename', '_csmsum'])
 
     @cached_property

{acoular-25.10 → acoular-26.1}/acoular/base.py

@@ -55,7 +55,7 @@ class Generator(ABCHasStrictTraits):
     """
 
     #: Sampling frequency of the signal, defaults to 1.0
-    sample_freq = Float(1.0, desc='sampling frequency')
+    sample_freq = Float(1.0)
 
     #: Number of signal samples
     num_samples = CInt
@@ -63,7 +63,7 @@ class Generator(ABCHasStrictTraits):
     #: Number of channels
     num_channels = CInt
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels'])
 
     def _get_digest(self):
@@ -96,7 +96,7 @@ class SamplesGenerator(Generator):
 
     """
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels'])
 
     def _get_digest(self):
@@ -137,7 +137,7 @@ class SpectraGenerator(Generator):
     #: The length of the block used to calculate the spectra
     block_size = CInt
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['sample_freq', 'num_samples', 'num_channels', 'num_freqs', 'block_size'])
 
     def _get_digest(self):
@@ -181,7 +181,7 @@ class TimeOut(SamplesGenerator):
     #: Number of samples in output, as given by :attr:`source`.
     num_samples = Delegate('source')
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['source.digest'])
 
     @cached_property
@@ -237,7 +237,7 @@ class SpectraOut(SpectraGenerator):
     #: The size of the block used to calculate the spectra
     block_size = Delegate('source')
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['source.digest'])
 
     @cached_property
@@ -285,7 +285,7 @@ class InOut(SamplesGenerator, SpectraGenerator):
     #: Number of samples / snapshots in output, as given by :attr:`source`.
     num_samples = Delegate('source')
 
-    # internal identifier
+    #: A unique identifier for the generator, based on its properties. (read-only)
     digest = Property(depends_on=['source.digest'])
 
     @cached_property

{acoular-25.10 → acoular-26.1}/acoular/calib.py

@@ -78,26 +78,26 @@ class Calib(InOut):
     """
 
     #: Name of the .xml file to be imported.
-    file = Union(None, File(filter=['*.xml'], exists=True), desc='name of the xml file to import')
+    file = Union(None, File(filter=['*.xml'], exists=True))
 
     #: Number of microphones in the calibration data,
     #: is set automatically when read from file or when data is set.
-    num_mics = CInt(0, desc='number of microphones in the geometry')
+    num_mics = CInt(0)
 
     #: Array of calibration factors,
     #: is set automatically when read from file.
     #: Can be set manually by specifying a NumPy array with shape (num_channels, ) if
     #: :attr:`source` yields time domain signals. For frequency domain signals, the expected
     #: shape is (num_channels * num_freqs).
-    data = CArray(desc='calibration data')
+    data = CArray()
 
     #: Channels that are to be treated as invalid.
-    invalid_channels = List(int, desc='list of invalid channels')
+    invalid_channels = List(int)
 
     #: Channel mask to serve as an index for all valid channels, is set automatically.
-    channels = Property(depends_on=['invalid_channels', 'num_mics'], desc='channel mask')
+    channels = Property(depends_on=['invalid_channels', 'num_mics'])
 
-    # Internal identifier
+    #: A unique identifier for the object, based on its properties. (read-only)
     digest = Property(depends_on=['source.digest', 'data'])
 
     @observe('data')