Skip to main content

Acoular Logo

PyPI PyPI Actions status DOI

Acoular

Acoular is a Python module for acoustic beamforming that is distributed under the BSD 3-clause 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. It only takes 2 minutes.

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 💾 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 for most algorithms.

Citing

If you use Acoular for academic work, please consider citing both our publication:

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:

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. It is recommended to use a virtual environment. Inside the environment, run

pip install acoular

A second option is to install Acoular with conda. It is recommended to install into a dedicated conda environment. After activating the environment, run

conda install -c acoular acoular

For more detailed installation instructions, see the documentation.

Documentation and help

Documentation is available here with a getting started section and examples.

If you discover problems with the Acoular software, please report them using the issue tracker on GitHub. Please use the Acoular discussions forum 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:

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

Metadata

Release files for acoular 26.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for acoular 26.4
File Size Uploaded Provenance Actions
acoular-26.4.tar.gz 168.0 kB Without provenance Details for acoular-26.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for acoular 26.4
File Interpreter ABI Platform Actions
acoular-26.4-py3-none-any.whl Python 3 none any Details for acoular-26.4-py3-none-any.whl

Total release size: 360.0 kB

Release files / acoular-26.4.tar.gz

Download URL acoular-26.4.tar.gz
Size 168.0 kB
Tags Source
SHA-256 checksum
How to use checksums
8d7811d6ec977cef7a2b81a90ab962265622f6662037e9e5f89a636b337c7e80
BLAKE2b-256 checksum
How to use checksums
f7e262ac9307bd969f4a171e6f653d69d73a843f91613b327696b22c9ff562fc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / acoular-26.4-py3-none-any.whl

Download URL acoular-26.4-py3-none-any.whl
Size 192.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3042cd7306a744c2086303a64f51959e32fedb9e744d084d43f1157ab3ea3672
BLAKE2b-256 checksum
How to use checksums
70b852eeadca43cbf52b49fcc8c8e841a29abfb04cb5a1e4f644eae688f4a915
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.11.8 {"installer":{"name":"uv","version":"0.11.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for acoular 26.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page