`PointSource`#

class acoular.sources.PointSource

Bases: SamplesGenerator

Define a fixed point source emitting a signal, intended for simulations.

The PointSource class models a stationary sound source that generates a signal detected by microphones. It includes support for specifying the source’s location, handling signal behaviors for pre-padding, and integrating environmental effects on sound propagation. The output is being generated via the result() generator.

See also

SignalGenerator: For defining custom emitted signals.
MicGeom: For specifying microphone geometries.
Environment: For modeling sound propagation effects.

Notes

The signal is adjusted to account for the distances between the source and microphones.
The prepadding attribute allows control over how the signal behaves for time indices before start_t.
Environmental effects such as sound speed are included through the env attribute.

Examples

To define a point source emitting a signal at a specific location, we first programmatically set a microphone geomertry as in MicGeom:

>>> import numpy as np
>>>
>>> # Generate a (3,3) grid of points in the x-y plane
>>> x = np.linspace(-1, 1, 3)  # Generate 3 points for x, from -1 to 1
>>> y = np.linspace(-1, 1, 3)  # Generate 3 points for y, from -1 to 1
>>>
>>> # Create a meshgrid for 3D coordinates, with z=0 for all points
>>> X, Y = np.meshgrid(x, y)
>>> Z = np.zeros_like(X)  # Set all z-values to 0
>>>
>>> # Stack the coordinates into a single (3,9) array
>>> points = np.vstack([X.ravel(), Y.ravel(), Z.ravel()])
>>> points
array([[-1.,  0.,  1., -1.,  0.,  1., -1.,  0.,  1.],
       [-1., -1., -1.,  0.,  0.,  0.,  1.,  1.,  1.],
       [ 0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.,  0.]])

Now, to set the actual point source (ps), we define a microphone geomerity (mg), using the positional data from points, and a sine generator (sg) with a total number of 6 samples.

>>> from acoular import PointSource, SineGenerator, MicGeom
>>> mg = MicGeom(pos_total=points)
>>> sg = SineGenerator(freq=1000, sample_freq=51200, num_samples=6)
>>> ps = PointSource(signal=sg, loc=(0.5, 0.5, 1.0), mics=mg)

We choose a blocksize of 4 and generate the output signal at the microphones in blocks:

>>> for block in ps.result(num=4):
...     print(block.shape)
(4, 9)
(2, 9)

The first block has shape (4,9) for 4 samples and 9 microphones. The second block has shape (2,9), since of a total of 6 samples only 2 remained.

signal = Instance(SignalGenerator): Instance of the SignalGenerator class defining the emitted signal.

loc = Property(CArray, desc='source location'): Coordinates (x, y, z) of the source. Default is np.array([[0.0], [0.0], [1.0]]).

num_channels = Delegate('mics', 'num_mics'): Number of output channels, automatically set based on the microphone geometry.

mics = Instance(MicGeom): MicGeom object defining the positions of the microphones.

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

start_t = Float(0.0): Start time of the signal in seconds. Default is 0.0.

start = Float(0.0): Start time of data acquisition at the microphones in seconds. Default is 0.0.

prepadding = Enum('loop', 'zeros')

Behavior of the signal for negative time indices, i.e. if (start < start_t):

'loop': Repeat the signal from its end.
'zeros': Use zeros, recommended for deterministic signals.

Default is 'loop'.

up = Int(16): Internal upsampling factor for finer signal resolution. Default is 16.

num_samples = Delegate('signal'): Total number of samples in the emitted signal, derived from the signal generator.

sample_freq = Delegate('signal'): Sampling frequency of the signal, derived from the signal generator.

digest = Property( …: A unique identifier for the current state of the source, based on its properties. (read-only)

result(num=128)

Generate output signal at microphones in blocks, incorporating propagation effects.

The result() method provides a generator that yields blocks of the signal detected at microphones. The signal is adjusted for the distances between the source and microphones, as well as any environmental propagation effects.

Parameters:

numint, optional: Number of samples per block to be yielded. Default is 128.

Yields:

numpy.ndarray: A 2D array of shape (num, num_channels) containing the signal detected at the microphones. The last block may have fewer samples if num_samples is not a multiple of num.

Raises:

ValueError: If the source and a microphone are located at the same position.
RuntimeError: If signal processing or propagation cannot be performed.

PointSource#

`PointSource`#