class flamo.processor.system.Series(*args)

Module for cascading multiple DSP modules in series. Inherits from nn.Sequential. This class serves as a container for a series of DSP modules, allowing them to be cascaded in a single module. It ensures that all included modules share the same values for the nfft and alias_decay_db attributes, hence all parsed modules are expected to have these attributes.

Args:

  • *args: A variable number of DSP modules of the type nn.Module, nn.Sequential, or OrderedDict.

class flamo.processor.system.Recursion(fF: Module | Sequential | OrderedDict | Series, fB: Module | Sequential | OrderedDict | Series)

Recursion module for computing closed-loop transfer function. Inherits from nn.Module. The feedforward and feedback paths if are given as a nn.Module, nn.Sequential, or OrderedDict, they are converted to a Series instance.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels, and \(N_{out}\) is the number of output channels. Ellipsis \((...)\) represents additional dimensions.

Args:

  • fF: The feedforward path with size (M, N_{out}, N_{in}).

  • fB: The feedback path with size (M, N_{in}, N_{out}).

  • alias_decay_db (float, optional): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Defaults to None.

Attributes:

  • feedforward (nn.Module | Series): The feedforward path.

  • feedback (nn.Module | Series): The feedback path.

  • nfft (int): The number of frequency points.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples.

Methods:

  • forward(x): Applies the closed-loop transfer function to the input tensor x by convolution in frequency domain.

  • __check_attribute(attr): Checks if feedforward and feedback paths have the same value of the requested attribute.

  • __check_io(): Check if the feedforward and feedback paths have compatible input/output shapes.

For details on the closed-loop transfer function see Wikipedia page.

forward(X)

Applies the closed-loop transfer function to the input tensor X.

Args:

X (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

Returns:

torch.Tensor: Output tensor of shape \((B, M, N_{out}, ...)\).

class flamo.processor.system.Shell(core: Module | Recursion | Sequential, input_layer: Recursion | Series | Module = Identity(), output_layer: Recursion | Series | Module = Identity())

DSP wrapper class. Interfaces the DSP with dataset and loss function. Inherits from nn.Module.

Shape:

  • input: \((B, M, N_{in}, ...)\)

  • output: \((B, M, N_{out}, ...)\)

where \(B\) is the batch size, \(M\) is the number of frequency bins, \(N_{in}\) is the number of input channels (defined by the core and the input_layer), and \(N_{out}\) is the number of output channels (defined by the core and the output_layer). Ellipsis \((...)\) represents additional dimensions.

Args:

  • core (nn.Module | nn.Sequential): DSP.

  • input_layer (nn.Module, optional): layer preceeding the DSP and correctly preparing the Dataset input before the DSP processing. Default: Transform(lambda x: x).

  • output_layer (nn.Module, optional): layer following the DSP and preparing its output for the comparison with the Dataset target. Default: Transform(lambda x: x).

Attributes:

  • core (nn.Module | Series): DSP.

  • input_layer (nn.Module | Series): layer preceeding the DSP.

  • output_layer (nn.Module | Series): layer following the DSP.

  • nfft (int): Number of frequency points.

  • alias_decay_db (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples.

Methods:

  • forward(x): Forward pass through the input layer, the core, and the output layer.

  • get_inputLayer(): Returns the current input layer.

  • set_inputLayer(input_layer): Substitutes the current input layer with a given new one.

  • get_outputLayer(): Returns the output layer.

  • set_outputLayer(output_layer): Substitutes the current output layer with a given new one.

  • get_core(): Returns the core.

  • set_core(core): Substitutes the current core with a given new one.

  • get_time_response(fs, identity): Generates the impulse response of the DSP.

  • get_freq_response(fs, identity): Generates the frequency response of the DSP.

forward(x: Tensor) → Tensor

Forward pass through the input layer, the core, and the output layer. Keeps the three components separated.

Args:

  • x (torch.Tensor): Input tensor of shape \((B, M, N_{in}, ...)\).

Returns:

  • torch.Tensor: Output tensor of shape \((B, M, N_{out}, ...)\).

get_freq_response(fs: int = 48000, identity: bool = False) → Tensor

Generates the frequency response of the DSP.

Args:

  • fs (int, optional): Sampling frequency. Defaults to 48000.

  • identity (bool, optional): If False, return the input-to-output frequency responses of the DSP.

    If True, return the input-free frequency responses of the DSP. Defaults to False.

NOTE: Definition of ‘input-to-output’ and ‘input-free’

Let \(A \in \mathbb{R}^{F \times N_{out} \times N_{in}}\) be a frequency filter matrix. If \(x \in \mathbb{R}^{F \times N_{in}}\) is an \(N_{in}\)-dimensional signal having a unit impulse at time \(t=0\) spectrum for each element along \(N_{in}\). Let \(I \in R^{F \times N \times N}\) be an diagonal matrix across second and third dimension, with unit impulse at time \(t=0\) spectra for each element along such diagonal. If \(*\) represent the signal-wise matrix product operator, then: - \(y = A * x\) is the ‘input-to-output’ frequency response of \(A\). - \(A * I`is the 'input-free' frequency response of :math:`A\).

Returns:

torch.Tensor: Generated DSP frequency response.

get_time_response(fs: int = 48000, identity: bool = False) → Tensor

Generates the impulse response of the DSP.

Args:

  • fs (int, optional): Sampling frequency. Defaults to 48000.

  • identity (bool, optional): If False, return the input-to-output impulse responses of the DSP.

    If True, return the input-free impulse responses of the DSP. Defaults to False.

NOTE: Definition of ‘input-to-output’ and ‘input-free’

Let \(A \in \mathbb{R}^{T \times N_{out} \times N_{in}}\) be a time filter matrix. If \(x \in \mathbb{R}^{T \times N_{in}}\) is an \(N_{in}\)-dimensional time signal having a unit impulse at time \(t=0\) for each element along \(N_{in}\). Let \(I \in R^{T \times N \times N}\) be an diagonal matrix across second and third dimension, with unit impulse at time \(t=0`for each element along such diagonal. If :math:`*\) represent the signal-wise matrix convolution operator, then: - \(y = A * x\) is the ‘input-to-output’ impulse response of \(A\). - \(A * I\) is the ‘input-free’ impulse response of \(A\).

Returns:

  • torch.Tensor: Generated DSP impulse response.