Acoular 25.01 documentation

SampleSplitter

«  Cache   ::   process   ::   TimeAverage  »

SampleSplitter

class acoular.process.SampleSplitter

Bases: InOut

Distributes data from a source to several following objects in a block-wise manner.

The SampleSplitter class is designed to take data from a single Generator derived source object and distribute it to multiple Generator derived objects. For each object, the SampleSplitter holds a virtual block buffer from which the subsequently connected objects receive data in a first-in-first-out (FIFO) manner. This allows for efficient data handling and processing in parallel.

Examples

Consider a time domain source signal stream from which the FFT spectra and the signal power are calculated block-wise and in parallel by using the RFFT as well as the TimePower and Average objects. The SampleSplitter object is used to distribute the incoming blocks of data to the RFFT and TimePower object buffers whenever one of these objects calls the result() generator. For the TimePower object, the buffer size is set to 10 blocks. If the buffer is full, an error is raised since the buffer overflow treatment is set to ‘error’. For the RFFT object, the block buffer size is set to 1 block, and the buffer overflow treatment is set to ‘none’. This is done to reduce latency in the FFT calculation, as the FFT calculation may take longer than the signal power calculation. If new data is available and the block buffer for the RFFT object is full, the SampleSplitter will drop the oldest block of data in the buffer. Thus, the RFFT object will always receive the most recent block of data.

>>> import acoular as ac
>>> import numpy as np
>>>
>>> # create a time domain signal source
>>> ts = ac.TimeSamples(data=np.random.rand(1024, 1), sample_freq=51200)
>>>
>>> # create the sample splitter object
>>> ss = ac.SampleSplitter(source=ts)
>>>
>>> # create the FFT spectra and further objects that receive the data
>>> fft = ac.RFFT(source=ss, block_size=64)
>>> pow = ac.TimePower(source=ss)
>>> avg = ac.Average(source=pow, num_per_average=64)
>>>
>>> # register the subsequent processing block objects at the sample splitter
>>> ss.register_object(fft, buffer_size=1, buffer_overflow_treatment='none')
>>> ss.register_object(pow, buffer_size=10, buffer_overflow_treatment='error')

After object registration, the SampleSplitter object is ready to distribute the data to the object buffers. The block buffers can be accessed via the block_buffer attribute of the SampleSplitter object.

>>> ss.block_buffer.values()
dict_values([deque([], maxlen=1), deque([], maxlen=10)])

Calling the result method of the FFT object will start the data collection and distribution process.

>>> generator = fft.result(num=1)
>>> fft_res = next(generator)

Although we haven’t called the result method of the signal power object, one data block is already available in the buffer.

>>> print(len(ss.block_buffer[pow]))
1

To remove registered objects from the SampleSplitter, use the remove_object() method.

>>> ss.remove_object(pow)
>>> print(len(ss.block_buffer))
1
block_buffer = Dict(key_trait=Instance(Generator))

dictionary with block buffers (dict values) of registered objects (dict keys).

buffer_size = Union(

max elements/blocks in block buffers. Can be set individually for each registered object. Default is 100 blocks for each registered object.

buffer_overflow_treatment = Dict(

defines behaviour in case of block_buffer overflow. Can be set individually for each registered object.

  • ‘error’: an IOError is thrown by the class

  • ‘warning’: a warning is displayed. Possibly leads to lost blocks of data

  • ‘none’: nothing happens. Possibly leads to lost blocks of data

register_object(*objects_to_register, buffer_size=None, buffer_overflow_treatment=None)

Register one or multiple Generator objects to the SampleSplitter.

Creates a block buffer for each object and sets the buffer size and buffer overflow treatment.

Parameters:
objects_to_registerGenerator

One or multiple Generator derived objects to be registered.

buffer_sizeint, optional

Maximum number of elements/blocks in block buffer. If not set, the default buffer size of 100 blocks is used.

buffer_overflow_treatmentstr, optional

Defines the behaviour in case of reaching the buffer size. Can be set individually for each object. Possible values are ‘error’, ‘warning’, and ‘none’. If not set, the default value is ‘error’.

remove_object(*objects_to_remove)

Function that can be used to remove registered objects.

If no objects are given, all registered objects are removed.

Parameters:
objects_to_removelist

One or multiple Generator derived objects to be removed. If not set, all registered objects are removed.

result(num)

Python generator that yields the output block-wise from block-buffer.

Parameters:
numinteger

This parameter defines the size of the blocks to be yielded (i.e. the number of samples per block).

Returns:
Samples in blocks of shape (num, num_channels).

Delivers a block of samples to the calling object. The last block may be shorter than num.

«  Cache   ::   process   ::   TimeAverage  »