`PointSourceConvolve`#

class acoular.sources.PointSourceConvolve

Bases: PointSource

Blockwise convolution of a source signal with an impulse response (IR).

The PointSourceConvolve class extends PointSource to simulate the effects of sound propagation through a room or acoustic environment by convolving the input signal with a specified convolution kernel (the IR).

The convolution is performed block-by-block to allow efficient streaming and processing of large signals.

See also

PointSource: Base class for point sources.
TimeConvolve: Class used for performing time-domain convolution.

Notes

The input convolution kernel must be provided as a time-domain array.
The second dimension of kernel must either be 1 (a single kernel applied to all channels) or match the number of channels in the output.
Convolution is performed using the TimeConvolve class.

Examples

Convolve a stationary sine wave source with a room impulse response (RIR):

>>> import numpy as np
>>> import acoular as ac
>>>
>>> # Define microphone geometry: 4 microphones in a 2x2 grid at z=0
>>> mic_positions = np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0], [1, 1, 0]]).T
>>> mg = ac.MicGeom(pos_total=mic_positions)
>>>
>>> # Generate a sine wave signal
>>> sine_signal = ac.SineGenerator(freq=1000, sample_freq=48000, num_samples=1000)
>>>
>>> # Define an impulse response kernel (example: 100-tap random kernel)
>>> kernel = np.random.randn(100, 1)  # One kernel for all channels
>>>
>>> # Create the convolving source
>>> convolve_source = PointSourceConvolve(
...     signal=sine_signal,
...     loc=(0, 0, 1),  # Source located at (0, 0, 1)
...     kernel=kernel,
...     mics=mg,
... )
>>>
>>> # Generate the convolved signal block by block
>>> for block in convolve_source.result(num=256):  # 256 samples per block
...     print(block.shape)
(256, 4)
(256, 4)
(256, 4)
(232, 4)

The last block has fewer samples.

kernel: Convolution kernel in the time domain. The array must either have one column (a single kernel applied to all channels) or match the number of output channels in its second dimension.

start_t: Start time of the signal in seconds. Default is 0.0.

start: Start time of the data acquisition the the microphones in seconds. Default is 0.0.

prepadding: Behavior for negative time indices. Default is None.

up: Upsampling factor for internal use. Default is None.

digest: Unique identifier for the current state of the source, based on microphone geometry, input signal, source location, and kernel. (read-only)

extend_signal

Controls whether to extend the output to include the full convolution result.

If False (default): Output length is \(\\max(L, M)\), where \(L\) is the kernel length and \(M\) is the signal length. This mode keeps the output length equal to the longest input (different from NumPy’s mode='same', since it does not pad the output).
If True: Output length is \(L + M - 1\), returning the full convolution at each overlap point (similar to NumPy’s mode='full').

Default is False.

result(num=128)

Generate the convolved signal at microphones in blocks.

The result() method produces blocks of the output signal by convolving the input signal with the specified kernel. Each block contains the signal for all output channels (microphones).

Parameters:

numint, optional: The number of samples per block to yield. Default is 128.

Yields:

numpy.ndarray: A 2D array of shape (num, num_channels) containing the convolved signal for all microphones. The last block may contain fewer samples if the total number of samples is not a multiple of num.

Notes

The input signal is expanded to match the number of microphones, if necessary.
Convolution is performed using the TimeConvolve class to ensure efficiency.

signal: Instance of the SignalGenerator class defining the emitted signal.

loc: Coordinates (x, y, z) of the source. Default is np.array([[0.0], [0.0], [1.0]]).

num_channels: Number of output channels, automatically set based on the microphone geometry.

mics: MicGeom object defining the positions of the microphones.

env: An Environment or derived object providing sound propagation details, such as speed of sound in the medium. Default is Environment.

num_samples: Total number of samples in the emitted signal, derived from the signal generator.

sample_freq: Sampling frequency of the signal, derived from the signal generator.

PointSourceConvolve#

`PointSourceConvolve`#