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 multipleGenerator
derived objects. For each object, theSampleSplitter
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 theTimePower
andAverage
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 theresult()
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.