`fprocess`#

Implements blockwise processing methods in the frequency domain.

`RFFT`	Compute the one-sided Fast Fourier Transform (FFT) for real-valued multichannel time data.
`IRFFT`	Perform the inverse Fast Fourier Transform (IFFT) for one-sided multi-channel spectra.
`AutoPowerSpectra`	Compute the real-valued auto-power spectra from multi-channel frequency-domain data.
`CrossPowerSpectra`	Compute the complex-valued auto- and cross-power spectra from frequency-domain data.

class acoular.fprocess.RFFT#

Bases: BaseSpectra, SpectraOut

Compute the one-sided Fast Fourier Transform (FFT) for real-valued multichannel time data.

The FFT is performed block-wise, dividing the input data into blocks of length specified by the block_size attribute. A window function can be optionally applied to each block before the FFT calculation, controlled via the window attribute.

This class provides flexibility in scaling the FFT results for different use cases, such as preserving amplitude or energy, by setting the scaling attribute.

source = Instance(SamplesGenerator)#: Data source; an instance of SamplesGenerator or a derived object. This provides the input time-domain data for FFT processing.

workers = Union(Int(), None, default_value=None, desc='number of workers to use')#: The number of workers to use for FFT calculation. If set to a negative value, all available logical CPUs are used. Default is None, which relies on the scipy.fft.rfft() implementation.

scaling = Enum('none', 'energy', 'amplitude')#

Defines the scaling method for the FFT result. Options are:

'none': No scaling is applied.
'energy': Compensates for energy loss in the FFT result due to truncation, doubling the values for frequencies other than DC and the Nyquist frequency.
'amplitude': Scales the result so that the amplitude of discrete tones is independent of the block size.

block_size = Property()#: The length of each block of time-domain data used for the FFT. Must be an even number. Default is 1024.

num_freqs = Property(depends_on=['_block_size'])#: The number of frequency bins in the FFT result, calculated as block_size // 2 + 1.

num_samples = Property(depends_on=['source.num_samples', '_block_size'])#: The total number of snapshots (blocks) available in the FFT result, determined by the size of the input data and the block size.

freqs = Property()#: A 1-D array containing the Discrete Fourier Transform sample frequencies corresponding to the FFT output.

digest = Property(depends_on=['source.digest', 'scaling', 'precision', '_block_size', 'window', 'overlap'])#: A unique identifier based on the process properties.

result(num=1)#

Yield the FFT results block-wise as multi-channel spectra.

This generator processes the input data block-by-block, applying the specified window function and FFT parameters. The output consists of the FFT spectra for each block, scaled according to the selected scaling method.

Parameters:

numint, optional: Number of multi-channel spectra (snapshots) per block to return. Default is 1.

Yields:

numpy.ndarray: A block of FFT spectra with shape (num, num_channels * num_freqs). The final block may contain fewer than num spectra if the input data is insufficient to fill the last block.

Notes

The generator compensates for energy or amplitude loss based on the scaling attribute.
If the input data source provides fewer samples than required for a complete block, the remaining spectra are padded or adjusted accordingly.

class acoular.fprocess.IRFFT#

Bases: TimeOut

Perform the inverse Fast Fourier Transform (IFFT) for one-sided multi-channel spectra.

This class converts spectral data from the frequency domain back into time-domain signals. The IFFT is calculated block-wise, where the block size is defined by the spectral data source. The output time-domain signals are scaled and processed according to the precision defined by the precision attribute.

workers = Union(Int(), None, default_value=None, desc='number of workers to use')#: The number of workers (threads) to use for the IFFT calculation. A negative value utilizes all available logical CPUs. Default is None, which relies on the scipy.fft.irfft() implementation.

precision = Enum('float64', 'float32', desc='precision of the time signal after the ifft')#: Determines the floating-point precision of the resulting time-domain signals. Options include 'float64' and 'float32'. Default is 'float64', ensuring high precision.

num_samples = Property(depends_on=['source.num_samples', 'source._block_size'])#: The total number of time-domain samples in the output. Computed as the product of the number of input samples and the block size. Returns -1 if the number of input samples is negative.

digest = Property(depends_on=['source.digest', 'scaling', 'precision', '_block_size', 'window', 'overlap'])#: A unique identifier based on the process properties.

result(num)#

Generate time-domain signal blocks from spectral data.

This generator processes spectral data block-by-block, performing an inverse Fast Fourier Transform (IFFT) to convert the input spectra into time-domain signals. The output is yielded in blocks of the specified size.

Parameters:

numint: The number of time samples per output block. If num differs from the source block size, an internal buffer is used to assemble the required output.

Yields:

numpy.ndarray: Blocks of time-domain signals with shape (num, num_channels). The last block may contain fewer samples if the input data is insufficient to fill the requested size.

Notes

The method ensures that the source block size and frequency data are compatible for IFFT.
If the requested block size does not match the source block size, a buffer is used to assemble the output, allowing arbitrary block sizes to be generated.
For performance optimization, the number of workers (threads) can be specified via the workers attribute.

class acoular.fprocess.AutoPowerSpectra#

Bases: SpectraOut

Compute the real-valued auto-power spectra from multi-channel frequency-domain data.

The auto-power spectra provide a measure of the power contained in each frequency bin for each channel. This class processes spectral data from the source block-by-block, applying scaling and precision adjustments as configured by the scaling and precision attributes.

source = Instance(SpectraGenerator)#: The data source that provides frequency-domain spectra, implemented as an instance of SpectraGenerator or a derived object.

scaling = Enum('power', 'psd')#

Specifies the scaling method for the auto-power spectra. Options are:

'power': Outputs the raw power of the spectra.
'psd': Outputs the Power Spectral Density (PSD), normalized by the block size and sampling frequency.

single_sided = Bool(True, desc='single sided spectrum')#: A Boolean flag indicating whether the input spectra are single-sided. Default is True.

precision = Enum('float64', 'float32', desc='floating-number-precision')#: Specifies the floating-point precision of the computed auto-power spectra. Options are 'float64' and 'float32'. Default is 'float64'.

digest = Property(depends_on=['source.digest', 'precision', 'scaling', 'single_sided'])#: A unique identifier based on the computation properties.

result(num=1)#

Generate real-valued auto-power spectra blocks.

This generator computes the auto-power spectra by taking the element-wise squared magnitude of the input spectra and applying the appropriate scaling. The results are yielded block-by-block with the specified number of snapshots.

Parameters:

numint, optional: Number of snapshots in each output block. Default is 1.

Yields:

numpy.ndarray: (num, num_channels * num_freqs). The last block may contain fewer snapshots if the input data does not completely fill the requested block size.

Notes

The auto-power spectra are computed as the squared magnitude of the spectra \(|S(f)|^2\), where \(S(f)\) is the frequency-domain signal.
Scaling is applied based on the configuration of the scaling and single_sided attributes.
The floating-point precision of the output is determined by the precision attribute.

class acoular.fprocess.CrossPowerSpectra#

Bases: AutoPowerSpectra

Compute the complex-valued auto- and cross-power spectra from frequency-domain data.

This class generates the cross-spectral matrix (CSM) in a flattened representation, which includes the auto-power spectra (diagonal elements) and cross-power spectra (off-diagonal elements). Depending on the calc_mode, the class can compute:

The full CSM, which includes all elements.
Only the upper triangle of the CSM.
Only the lower triangle of the CSM.

The results are computed block-by-block and scaled according to the specified configuration.

source = Instance(SpectraGenerator)#: The data source providing the input spectra, implemented as an instance of SpectraGenerator or a derived object.

precision = Enum('complex128', 'complex64', desc='precision of the fft')#: Specifies the floating-point precision of the computed cross-spectral matrix (CSM). Options are 'complex128' and 'complex64'. Default is 'complex128'.

calc_mode = Enum('full', 'upper', 'lower', desc='calculation mode')#

'lower': Computes only the lower triangle of the CSM,
excluding redundant upper-triangle elements.

Default is 'full'.

num_channels = Property(depends_on=['source.num_channels'])#

The number of channels in the output data. The value depends on the number of input channels \(n\) and the selected calc_mode:

'full': \(n^2\) (all elements in the CSM).

'upper': \(n + n(n-1)/2\) (diagonal + upper triangle elements).

'lower': \(n + n(n-1)/2\) (diagonal + lower triangle elements).

digest = Property(depends_on=['source.digest', 'precision', 'scaling', 'single_sided', 'calc_mode'])#: A unique identifier based on the computation properties.

result(num=1)#

Generate blocks of complex-valued auto- and cross-power spectra.

This generator computes the cross-spectral matrix (CSM) for input spectra block-by-block. Depending on the calc_mode, the resulting CSM is flattened in one of three ways:

'full': Includes all elements of the CSM.
'upper': Includes only the diagonal and upper triangle.
'lower': Includes only the diagonal and lower triangle.

Parameters:

numint, optional: Number of snapshots (blocks) in each output data block. Default is 1.

Yields:

numpy.ndarray: Blocks of complex-valued auto- and cross-power spectra with shape (num, :attr:`num_channels` * :attr:`num_freqs`). The last block may contain fewer than num elements if the input data does not completely fill the requested block size.

fprocess#

`fprocess`#