flamo 0.1.5__tar.gz → 0.1.7__tar.gz

{flamo-0.1.5 → flamo-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flamo
-Version: 0.1.5
+Version: 0.1.7
 Summary: An Open-Source Library for Frequency-Domain Differentiable Audio Processing
 Project-URL: Homepage, https://github.com/gdalsanto/flamo
 Project-URL: Issues, https://github.com/gdalsanto/flamo/issues
@@ -71,7 +71,7 @@ Utilities, system designers, and optimization - in `flamo.processor.system`:
 - **Shell**: Container class for safe interaction between system, dataset, and loss functions
 
 Optimization - in `flamo.optimize`:
-- **Trianer** : Handling of the training and validation steps 
+- **Trainer** : Handling of the training and validation steps 
 - **Dataset** : Customizable dataset class and helper methods 
 
 --- 

{flamo-0.1.5 → flamo-0.1.7}/README.md

@@ -24,7 +24,7 @@ Utilities, system designers, and optimization - in `flamo.processor.system`:
 - **Shell**: Container class for safe interaction between system, dataset, and loss functions
 
 Optimization - in `flamo.optimize`:
-- **Trianer** : Handling of the training and validation steps 
+- **Trainer** : Handling of the training and validation steps 
 - **Dataset** : Customizable dataset class and helper methods 
 
 --- 

flamo-0.1.7/examples/e1_vn.py

@@ -0,0 +1,63 @@
+"""
+Example usage of velvet noise filters integrated with FLAMO Filter system.
+
+This example shows how to use the new Filter-based velvet noise classes
+that are differentiable and can be used within the FLAMO processing chain.
+"""
+
+import torch.nn as nn   
+
+import matplotlib.pyplot as plt
+from flamo.auxiliary.velvet import (
+    VelvetNoiseFilter,
+)
+from flamo.functional import signal_gallery
+from flamo.processor import dsp
+
+def example_velvet_noise_filter():
+    """Example using VelvetNoiseFilter."""
+    print("=== VelvetNoiseFilter Example ===")
+    
+    in_ch, out_ch = 1, 1
+    nfft = 2048  # FFT size for the filter
+    length = nfft # Length of the filter
+
+    # Create a velvet noise filter
+    # size = (length, output_channels, input_channels)
+    velvet_filter = VelvetNoiseFilter(
+        size=(length, out_ch, in_ch),  # 1024 samples, 1x1 matrix
+        density=1000.0,     # 1000 impulses per second
+        sample_rate=48000,
+        requires_grad=True  # Make it differentiable
+    )
+    
+    input_layer = dsp.FFT(nfft=nfft)
+    output_layer = dsp.iFFT(nfft=nfft)
+
+    my_dsp = nn.Sequential(input_layer, velvet_filter, output_layer)
+
+    # -------------- Apply unit impulse to DSP --------------
+
+    # Input signal
+    input_sig = signal_gallery(
+        signal_type="impulse",
+        batch_size=1,
+        n_samples=nfft,  
+        n=in_ch,
+        fs=48000,
+        device="cpu",
+    )
+
+    output_vn = my_dsp(input_sig)
+    # plot the sequence 
+    plt.figure(figsize=(12, 4))
+    plt.plot(output_vn[0, :, 0].squeeze().numpy())
+    for pos in velvet_filter.grid:
+        plt.axvline(x=pos.item(), color='r', linestyle='--', alpha=0.5)
+    plt.title('Output Velvet Noise Signal')
+    plt.xlabel('Samples')
+    plt.ylabel('Amplitude')
+    plt.grid(True, alpha=0.3)
+    plt.tight_layout()
+    
+    return 

{flamo-0.1.5 → flamo-0.1.7}/flamo/auxiliary/scattering.py

@@ -245,13 +245,11 @@ def get_random_shifts(N, sparsity_vect, pulse_size):
 
 def hadamard_matrix(N):
     """Generate a hadamard matrix of size N"""
-    X = np.array([[1]])
+    X = np.array([[1]]) 
     # Create a Hadamard matrix of the specified order
-    # TODO remove for loop becuase all matrices look the same
     while X.shape[0] < N:
         # Kronecker product to generate a larger Hadamard matrix
         X = np.kron(X, np.array([[1, 1], [1, -1]])) / np.sqrt(2)
-
     return X
 
 

flamo-0.1.7/flamo/auxiliary/velvet.py

@@ -0,0 +1,114 @@
+"""
+Velvet Noise implementations for FLAMO
+
+Velvet noise is a sparse pseudo-random noise used in artificial reverberation.
+It consists of sample values of +1, -1, and 0, with the non-zero samples 
+occurring at pseudo-random locations.
+
+References:
+    Välimäki, V., & Prawda, K. (2021). Late-Reverberation Synthesis Using 
+    Interleaved Velvet-Noise Sequences. IEEE/ACM Transactions on Audio, 
+    Speech, and Language Processing, 29, 1149-1160.
+"""
+
+import torch
+import torch.nn as nn
+import math
+from typing import Optional
+from flamo.processor.dsp import Filter, parallelFilter
+
+
+class VelvetNoiseFilter(Filter):
+    """
+    TODO 
+    Args:
+        size: Size of the filter parameters (length, output_channels, input_channels)
+        density: Number of impulses per second
+        delta: Scaling factor for impulse range (0 < delta <= 1)
+               When delta=0.25, impulses only appear in first 25% of each grid
+        sample_rate: Sample rate in Hz (default: 48000)
+        nfft: Number of FFT points required to compute the frequency response
+        requires_grad: Whether the filter parameters require gradients
+        alias_decay_db: The decaying factor in dB for the time anti-aliasing envelope
+        device: The device of the constructed tensors
+    """
+    
+    def __init__(
+        self,
+        size: tuple = (1, 1, 1),
+        density: float = 1000.0,
+        delta: float = 1.0,
+        sample_rate: int = 48000,
+        nfft: int = 2**11,
+        requires_grad: bool = False,
+        alias_decay_db: float = 0.0,
+        device: Optional[str] = None,
+    ):
+        self.density = density
+        self.sample_rate = sample_rate
+        self.Td = sample_rate / density  # Average distance between impulses
+        if not 0 < delta <= 1:
+            raise ValueError("Delta must be in range (0, 1]")
+            
+        self.delta = delta
+        # Create mapping function that generates velvet noise
+        map = lambda x: self._generate_velvet_impulse_response(x)
+        super().__init__(
+            size=size,
+            nfft=nfft,
+            map=map,
+            requires_grad=requires_grad,
+            alias_decay_db=alias_decay_db,
+            device=device,
+        )
+    
+    def _generate_velvet_impulse_response(self, param: torch.Tensor) -> torch.Tensor:
+        """Generate velvet noise impulse response from parameters."""        
+        # Calculate grid size (average distance between impulses)
+
+        
+        result = torch.zeros_like(param)
+        
+        for out_ch in range(self.param.shape[1]):
+            for in_ch in range(self.param.shape[2]):
+                # Extract parameters for this channel pair
+                result[:, out_ch, in_ch] = self._generate_velvet_sequence()
+                
+        return result
+    
+    def _generate_velvet_sequence(
+        self, 
+    ) -> torch.Tensor:
+        """Generate a single velvet noise sequence."""
+        
+        # Add random jitter to each position (uniform distribution)
+        jitter_factors = torch.rand(self.floor_impulses)
+        impulse_indices = torch.ceil(self.grid + self.delta *  jitter_factors * (self.Td - 1)).long()
+
+        # first impulse is at position 0 and all indices are within bounds
+        impulse_indices[0] = 0
+        impulse_indices = torch.clamp(impulse_indices, max=self.param.shape[0] - 1)
+        
+        # Generate random signs (+1 or -1)
+        signs = 2 * torch.randint(0, 2, (self.floor_impulses,)) - 1
+        
+        # Construct sparse signal
+        sequence = torch.zeros(self.size[0], device=self.device)
+        sequence[impulse_indices] = signs.float()
+
+        return sequence
+
+    def initialize_class(self):
+        r"""
+        Initializes the Filter module.
+
+        This method checks the shape of the gain parameters, computes the frequency response of the filter,
+        and computes the frequency convolution function.
+        """
+        self.check_param_shape()
+        self.get_io()
+        num_impulses = self.param.shape[0] / self.Td
+        self.floor_impulses = math.floor(num_impulses)
+        self.grid = torch.arange(self.floor_impulses) * self.Td
+        self.get_freq_response()
+        self.get_freq_convolve()

{flamo-0.1.5 → flamo-0.1.7}/flamo/functional.py

@@ -1,3 +1,4 @@
+import math
 import torch
 import torch.nn as nn
 import numpy as np
@@ -175,11 +176,12 @@ def signal_gallery(
         - ``sweep``: A linear sweep from 20 Hz to 20 kHz.
         - ``wgn``: White Gaussian noise.
         - ``exp``: An exponential decay signal.
+        - ``velvet``: A velvet noise signal with density :attr:`rate` impulses per second.
         - ``reference``: A reference signal provided as argument :attr:`reference`.
 
         **Arguments**:
             - **batch_size** (int): The number of batches to generate.
-            - **n_samples** (int): THe signal length in samples.
+            - **n_samples** (int): The signal length in samples.
             - **n_channel** (int): The number of channels in each signal.
             - **signal_type** (str, optional): The type of signal to generate. Defaults to 'impulse'.
             - **fs** (int, optional): The sampling frequency of the signals. Defaults to 48000.
@@ -198,6 +200,7 @@ def signal_gallery(
         "exp",
         "reference",
         "noise",
+        "velvet",
     }
 
     if signal_type not in signal_types:
@@ -243,6 +246,12 @@ def signal_gallery(
                 .expand(batch_size, n_samples, n)
                 .to(device)
             )
+        case "velvet":
+            x = torch.empty((batch_size, n_samples, n), device=device)
+            for i_batch in range(batch_size):
+                for i_ch in range(n):
+                    x[i_batch, :, i_ch] = gen_velvet_noise(n_samples, fs, rate, device)
+            return x
         case "reference":
             if isinstance(reference, torch.Tensor):
                 return reference.expand(batch_size, n_samples, n).to(device)
@@ -254,6 +263,38 @@ def signal_gallery(
             return torch.randn((batch_size, n_samples, n), device=device)
 
 
+def gen_velvet_noise(n_samples: int, fs: int, density: float, device: str | torch.device = None) -> torch.Tensor:
+    r"""
+    Generate a velvet noise sequence.
+    **Arguments**:
+        - **n_samples** (int): The length of the signal in samples.
+        - **fs** (int): The sampling frequency of the signal in Hz.
+        - **density** (float): The density of impulses in impulses per second.
+        - **device** (str | torch.device): The device of constructed tensors.
+    **Returns**:
+        - torch.Tensor: A tensor of shape (n_samples,) containing the velvet noise sequence.
+    """
+    Td = fs / density # average distance between impulses
+    num_impulses = n_samples / Td # expected number of impulses
+    floor_impulses = math.floor(num_impulses)
+    grid = torch.arange(floor_impulses) * Td
+
+    jitter_factors = torch.rand(floor_impulses)
+    impulse_indices = torch.ceil(grid + jitter_factors * (Td - 1)).long()
+
+    # first impulse is at position 0 and all indices are within bounds
+    impulse_indices[0] = 0
+    impulse_indices = torch.clamp(impulse_indices, max=n_samples - 1)
+            
+    # Generate random signs (+1 or -1)
+    signs = 2 * torch.randint(0, 2, (floor_impulses,)) - 1
+            
+    # Construct sparse signal
+    sequence = torch.zeros(n_samples, device=device)
+    sequence[impulse_indices] = signs.float()
+
+    return sequence
+
 def hertz2rad(hertz: torch.Tensor, fs: int):
     r"""
     Convert frequency from Hz to rad.

{flamo-0.1.5 → flamo-0.1.7}/flamo/processor/dsp.py

@@ -1,4 +1,5 @@
 import torch
+import math
 from typing import Optional
 import torch.nn as nn
 import torch.nn.functional as F
@@ -16,7 +17,8 @@ from flamo.auxiliary.eq import (
     geq, 
     accurate_geq)
 from flamo.auxiliary.scattering import (
-    ScatteringMapping)
+    ScatteringMapping, 
+    hadamard_matrix)
 # ============================= TRANSFORMS ================================
 
 
@@ -928,7 +930,7 @@ class parallelFilter(Filter):
 
 class ScatteringMatrix(Filter):
     r"""
-    A class representing a set of Scattering Filter matrix.
+    A class representing a Scattering Filter matrix.
 
     The :class:`ScatteringMatrix` was designed as filter feedback matrix of the
      Feedback Delay Network (FDN) reverberator structure.
@@ -1075,6 +1077,145 @@ class ScatteringMatrix(Filter):
         self.get_freq_response()
         self.get_freq_convolve()
 
+class VelvetNoiseMatrix(Filter):
+    r"""
+    A class representing a Velvet Noise Filter matrix.
+
+    The :class:`VelvetNoiseMatrix` was designed as filter feedback matrix of the
+     Feedback Delay Network (FDN) reverberator structure.
+    NOTE: It is not learnable. 
+
+    The input tensor is expected to be a complex-valued tensor representing the
+    frequency response of the input signal. The input tensor is then convolved in
+    frequency domain with the filter frequency responses to produce the output tensor.
+
+    Shape:
+        - input: :math:`(B, M, N_{in}, ...)`
+        - param: :math:`(N_{taps}, N_{out}, N_{in})`
+        - output: :math:`(B, M, N_{out}, ...)`
+
+    where :math:`B` is the batch size, :math:`M` is the number of frequency bins,
+    :math:`N_{in}` is the number of input channels, :math:`N_{out}` is the number of output channels,
+    and :math:`N_{taps}` is the number of filter parameters per input-output channel pair. By default, :math:`N_{taps}`
+    correspond to the length of the FIR filters.
+    Ellipsis :math:`(...)` represents additional dimensions.
+
+        **Arguments / Attributes**:
+            - **size** (tuple): The size of the filter parameters. Default: (1, 1, 1).
+            - **nfft** (int): The number of FFT points required to compute the frequency response. Default: 2 ** 11.
+            - **density** (float): Average number of pulses per sample. Default: 0.03.
+            - **gain_per_sample** (float): The gain per sample. This is useful when ensuring homogeneous decay in FDNs Default: 0.9999.
+            - **m_L** (torch.tensor): The leftmost delay vector. Default: None.
+            - **m_R** (torch.tensor): The rightmost delay vector. Default: None.
+            - **requires_grad** (bool): Whether the filter parameters require gradients. Default: False.
+            - **alias_decay_db** (float): The decaying factor in dB for the time anti-aliasing envelope. The decay refers to the attenuation after nfft samples. Default: 0.
+            - **device** (str): The device of the constructed tensors. Default: None.
+
+        **Attributes**:
+            - **param** (nn.Parameter): The parameters of the Filter module.
+            - **map** (function): Mapping function to ensure orthogonality of :math:`\mathbf{U}_k`.
+            - **map_filter** (ScatteringMapping): Mapping function to generate the filter matrix.
+            - **fft** (function): The FFT function. Calls the torch.fft.rfft function.
+            - **ifft** (function): The Inverse FFT function. Calls the torch.fft.irfft.
+            - **gamma** (torch.Tensor): The gamma value used for time anti-aliasing envelope.
+            - **new_value** (int): Flag indicating if new values have been assigned.
+            - **freq_response** (torch.Tensor): The frequency response of the filter.
+            - **freq_convolve** (function): The frequency convolution function.
+            - **input_channels** (int): The number of input channels.
+            - **output_channels** (int): The number of output channels.
+
+    Refereces:
+        - Schlecht, S. J., & Habets, E. A. (2020). Scattering in feedback delay networks. IEEE/ACM Transactions on Audio, Speech, and Language Processing, 28, 1915-1924.
+
+    """
+
+    def __init__(
+        self,
+        size: tuple = (1, 1, 1),
+        nfft: int = 2**11,
+        density: float = 0.03,
+        gain_per_sample: float = 0.9999,
+        m_L: torch.tensor = None,
+        m_R: torch.tensor = None,
+        alias_decay_db: float = 0.0,
+        device: Optional[str] = None,
+    ):
+        self.sparsity = 1/density
+        self.gain_per_sample = gain_per_sample
+        self.pulse_size = 1
+        self.m_L = m_L
+        self.m_R = m_R
+        map = lambda x: x
+        assert size[1] == size[2], "Matrix must be square"
+        assert (size[1] & (size[1] - 1)) == 0, "At the moment the Matrix must have dimensions which are powers of 2"
+        super().__init__(
+            size=size,
+            nfft=nfft,
+            map=map,
+            requires_grad=False,
+            alias_decay_db=alias_decay_db,
+            device=device,
+        )
+        self.assign_value(torch.tensor(hadamard_matrix(self.size[-1]), device=self.device).unsqueeze(0).repeat(self.size[0], 1, 1))
+
+    def get_freq_convolve(self):
+        r"""
+        Computes the frequency convolution function.
+
+        The frequency convolution is computed using the :func:`torch.einsum` function.
+
+            **Arguments**:
+                **x** (torch.Tensor): Input tensor.
+
+            **Returns**:
+                torch.Tensor: Output tensor after frequency convolution.
+        """
+        self.freq_convolve = lambda x, param: torch.einsum(
+            "fmn,bfn...->bfm...", self.freq_response(param), x
+        )
+
+    def get_freq_response(self):
+        r"""
+        Computes the frequency response of the filter.
+
+        The mapping function is applied to the filter parameters to obtain the filter impulse responses.
+        Then, the time anti-aliasing envelope is computed and applied to the impulse responses. Finally,
+        the frequency response is obtained by computing the FFT of the filter impulse responses.
+        """
+        L = (
+            (sum(self.map_filter.shifts).max() + 1).item()
+            + self.m_L.max().item()
+            + self.m_R.max().item()
+        )
+        self.freq_response = lambda param: self.fft(
+            self.map_filter(self.map(param))
+            * (self.gamma ** torch.arange(0, L, device=self.device)).view(
+                -1, *tuple([1 for i in self.size[1:]])
+            )
+        )
+
+    def initialize_class(self):
+        r"""
+        Initializes the ScatteringMatrix module.
+
+        This method creates the mapping to generate the filter matrix, checks the shape of the gain parameters, computes the frequency response of the filter,
+        and computes the frequency convolution function.
+        """
+        self.map_filter = ScatteringMapping(
+            self.size[-1],
+            n_stages=self.size[0] - 1,
+            sparsity=math.floor(self.sparsity),
+            gain_per_sample=self.gain_per_sample,
+            pulse_size=self.pulse_size,
+            m_L=self.m_L,
+            m_R=self.m_R,
+            device=self.device,
+        )
+        self.check_param_shape()
+        self.get_io()
+        self.get_freq_response()
+        self.get_freq_convolve()
+
 
 class Biquad(Filter):
     r"""
@@ -2410,7 +2551,7 @@ class AccurateGEQ(Filter):
     :math:`N_{in}` is the number of input channels, :math:`N_{out}` is the number of output channels,
     The :attr:'param' attribute represent the command gains of each band + shelving filters. The first dimension of the :attr:'param' tensor corresponds to the number of command gains/filters :math:`K`.
     Ellipsis :math:`(...)` represents additional dimensions (not tested).   
-    NOTE I: It is not differentiable 
+    NOTE I: It is not learnable 
     NOTE II: To avoid NaN or Inf values in the frequency response, the operations 
     performed in the frequency domain are done in double precision. The original 
     data type is restored at the end of the computation.
@@ -2531,7 +2672,7 @@ class parallelAccurateGEQ(AccurateGEQ):
     r"""
     Parallel counterpart of the :class:`GEQ` class
     For information about **attributes** and **methods** see :class:`flamo.processor.dsp.GEQ`.
-    NOTE: It is not differentiable 
+    NOTE: It is not learnable. 
 
     Shape:
         - input: :math:`(B, M, N, ...)`

{flamo-0.1.5 → flamo-0.1.7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "flamo"
-version = "0.1.5"
+version = "0.1.7"
 authors = [
   { name="Gloria Dal Santo", email="gloria.dalsanto@aalto.fi" },
   { name="Gian Marco De Bortoli", email="gian.debortoli@aalto.fi"},