`SamplesBuffer`#

class acoular.process.SamplesBuffer

Bases: InOut

Handle buffering of samples from a source.

The SamplesBuffer class buffers samples from a source and provides them in blocks of a specified size. It supports various use cases for efficient handling of sample data. Below is an example demonstrating its functionality.

Examples

Suppose we want to draw blocks of 16 samples from the source, while ensuring that the buffer always holds twice that number (32 samples). The following code achieves this behavior:

>>> import acoular as ac
>>> import numpy as np
>>> # create a white noise source with 512 samples
>>> source = ac.TimeSamples(
...     data=ac.WNoiseGenerator(
...         sample_freq=64,
...         num_samples=512,
...     ).signal()[:, np.newaxis],
...     sample_freq=64,
... )
>>> # create a buffer with a size of 32 samples
>>> buffer = ac.process.SamplesBuffer(source=source, length=32)
>>> # get the first block of 16 samples
>>> block = next(buffer.result(num=16))
>>> np.testing.assert_array_equal(block, source.data[:16])

In the example above, the buffer initially collects blocks of the specified size from the source. It then returns the first block of 16 samples. With subsequent calls to the result() method, the buffer refills and returns additional blocks of 16 samples.

In some cases, you may wish to retrieve a different number of samples from the source than you want to return. This can be achieved by setting the source_num attribute. For example, in the BeamformerTimeTraj class, the number of time samples varies based on the expected delay for moving sources, while still adhering to the desired block size for the buffer.

The shift_index_by attribute controls how the buffer updates its index when retrieving data. If set to 'num', the buffer returns result_num samples but forgets 'num' samples from the buffer. If set to result_num, the buffer will return and forget the same number of samples.

>>> buffer = ac.process.SamplesBuffer(source=source, length=32, result_num=20, shift_index_by='num')
>>> block_sizes = []
>>> block_sizes.append(
...     next(buffer.result(num=16)).shape[0]
... )  # this time, the buffer will return 20 samples, but the buffer will only forget the first 16 samples
>>> buffer.result_num = 24
>>> block_sizes.append(
...     next(buffer.result(num=16)).shape[0]
... )  # this time, the buffer will return 24 samples, but the buffer will only forget the first 16 samples
>>> np.testing.assert_array_equal(block_sizes, [20, 24])

length = Int(): The number of samples that the buffer can hold.

source_num = Union( …: The number of samples per block to obtain from the source. If set to None, the number of samples will be determined by the num argument of the result() method.

result_num = Union( …: The number of samples to return from the buffer. If set to None, the number of samples will be determined by the num argument of the result() method.

shift_index_by = Enum( …

Index shift value for the buffer.

If set to 'result_num', the buffer will return and forget result_num samples.
If set to 'num', the buffer will return result_num samples but forget num samples.

level = Property(): The current filling level of the buffer, i.e., how many samples are currently available.

dtype = Any(): The data type of the elements in the buffer.

increase_buffer(num)

Increase the size of the buffer by a specified number of samples.

This method expands the buffer by appending additional samples, effectively increasing its capacity. The new samples are initialized to zero. The index of the buffer is adjusted accordingly to accommodate the increase.

Parameters:

numint: The number of samples by which to increase the buffer size.

read_from_buffer(num)

Read a specified number of samples from the buffer.

This method retrieves samples from the buffer, ensuring that the requested number of samples is returned. If the buffer contains fewer samples than requested, the method will return all available samples. The index of the buffer is updated based on the shift_index_by setting.

Parameters:

numint: The number of samples to read from the buffer.

Returns:

numpy.ndarray: A block of samples (array) from the buffer.

Notes

If the result_num attribute is set, it determines the number of samples to return.
The method ensures the buffer index is adjusted according to the shift_index_by setting. Options are:
- 'result_num': The index will shift by the number of samples returned.
- 'num': The index will shift by the number of samples requested (num).

fill_buffer(snum)

Fill the buffer with samples from the source.

The fill_buffer() method collects samples from the source and writes them to the buffer. It continues to fill the buffer until there are enough samples available, or the source runs out of data. If the buffer reaches its maximum capacity, additional samples are discarded. The buffer will only contain the most recent data, and its index will be updated accordingly.

Parameters:

snumint: The number of samples to retrieve from the source in each iteration.

Yields:

None: This method is a generator and yields control back after filling the buffer.

Notes

The method ensures that the buffer is filled with the required number of samples, adjusting the buffer size if necessary (via the increase_buffer() method) when more space is needed.
Once the buffer is filled, it yields control and resumes only when the buffer is ready for more data.

result(num)

Return blocks of samples from the buffer.

The result() method retrieves blocks of samples from the buffer and yields them to the calling process. The number of samples per block is determined by the num argument, but can also be influenced by other attributes like result_num (if set). If the buffer is not yet filled, it will continue to collect samples from the source until the buffer contains enough data. Once the buffer is full, it will return the requested blocks of samples.

Parameters:

numint: The number of samples to return in each block. This value specifies the size of the blocks to be yielded from the buffer.

Yields:

numpy.ndarray: A block of samples from the buffer. The size of the block is determined by the num parameter or the result_num attribute, depending on the buffer’s configuration.

Notes

If result_num is set, the method will use it to determine the number of samples returned instead of the num parameter.
If the buffer is empty or does not have enough samples, it will attempt to fill the buffer by collecting data from the source. If there are not enough samples available from the source, the method will yield whatever samples are left in the buffer.

SamplesBuffer#

`SamplesBuffer`#