torch-l1-snr 0.1.1__tar.gz → 0.1.2__tar.gz

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: torch-l1-snr
-Version: 0.1.1
+Version: 0.1.2
 Summary: L1-SNR loss functions for audio source separation in PyTorch
 Home-page: https://github.com/crlandsc/torch-l1-snr
 Author: Christopher Landschoot
@@ -237,7 +237,7 @@ While this can potentially reduce the "cleanliness" of separations and slightly
 
 The implementation is optimized for efficiency: if `l1_weight` is `0.0` or `1.0`, the unused loss component is not computed, saving computational resources.
 
-**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match the gradient magnitudes of the L1SNR component. This helps maintain stable training without manual tuning.
+**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match gradient magnitudes while preserving distinct gradient behaviors. This helps maintain stable training without manual tuning.
 
 ## Limitations
 

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/README.md

@@ -209,7 +209,7 @@ While this can potentially reduce the "cleanliness" of separations and slightly
 
 The implementation is optimized for efficiency: if `l1_weight` is `0.0` or `1.0`, the unused loss component is not computed, saving computational resources.
 
-**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match the gradient magnitudes of the L1SNR component. This helps maintain stable training without manual tuning.
+**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match gradient magnitudes while preserving distinct gradient behaviors. This helps maintain stable training without manual tuning.
 
 ## Limitations
 

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/tests/test_losses.py

@@ -542,4 +542,124 @@ def test_multi_wrapper_short_audio_4d():
     
     assert torch.allclose(wrapped_result, direct_result, atol=1e-6)
     assert wrapped_result.ndim == 0
-    assert not torch.isnan(wrapped_result) and not torch.isinf(wrapped_result) 
+    assert not torch.isnan(wrapped_result) and not torch.isinf(wrapped_result)
+
+
+# --- Gradient Behavior Tests ---
+def test_gradient_distinction_l1snr_vs_l1():
+    """
+    Verify L1SNR and L1 have distinct gradient behaviors.
+    L1SNR: inverse-error scaling (larger updates for small errors)
+    L1: uniform gradients regardless of error magnitude
+    """
+    torch.manual_seed(42)
+
+    actuals = torch.tensor([[1.0] * 100, [1.0] * 100])
+    estimates = actuals.clone()
+    estimates[0] += 0.01  # small error
+    estimates[1] += 0.5   # large error
+
+    # Pure L1SNR (l1_weight=0)
+    est_snr = estimates.clone().requires_grad_(True)
+    loss_snr = L1SNRLoss("test", l1_weight=0.0)(est_snr, actuals)
+    loss_snr.backward()
+    ratio_snr = est_snr.grad[0].abs().mean() / est_snr.grad[1].abs().mean()
+
+    # Pure L1 (l1_weight=1)
+    est_l1 = estimates.clone().requires_grad_(True)
+    loss_l1 = L1SNRLoss("test", l1_weight=1.0)(est_l1, actuals)
+    loss_l1.backward()
+    ratio_l1 = est_l1.grad[0].abs().mean() / est_l1.grad[1].abs().mean()
+
+    # L1SNR: larger gradient for small error sample (ratio >> 1)
+    assert ratio_snr > 10.0, f"L1SNR gradient ratio should be >> 1, got {ratio_snr}"
+    # L1: uniform gradients (ratio ~ 1)
+    assert 0.9 < ratio_l1 < 1.1, f"L1 gradient ratio should be ~1, got {ratio_l1}"
+
+
+def test_l1_weight_interpolation():
+    """
+    Verify l1_weight actually affects gradient behavior.
+    Gradient ratio should decrease as l1_weight increases (from inverse-error toward uniform).
+    """
+    torch.manual_seed(42)
+
+    actuals = torch.tensor([[1.0] * 100, [1.0] * 100])
+    estimates = actuals.clone()
+    estimates[0] += 0.01  # small error
+    estimates[1] += 0.5   # large error
+
+    ratios = []
+    for w in [0.0, 0.5, 1.0]:
+        est = estimates.clone().requires_grad_(True)
+        loss = L1SNRLoss("test", l1_weight=w)(est, actuals)
+        loss.backward()
+        ratio = (est.grad[0].abs().mean() / est.grad[1].abs().mean()).item()
+        ratios.append(ratio)
+
+    # Gradient ratio should monotonically decrease as l1_weight increases
+    assert ratios[0] > ratios[1] > ratios[2], \
+        f"Gradient ratios should decrease with l1_weight: {ratios}"
+
+
+def test_stft_gradient_distinction():
+    """
+    Same gradient distinction test for STFTL1SNRDBLoss.
+    """
+    torch.manual_seed(42)
+
+    # Need longer audio for STFT
+    actuals = torch.tensor([[1.0] * 4096, [1.0] * 4096])
+    estimates = actuals.clone()
+    estimates[0] += 0.01  # small error
+    estimates[1] += 0.5   # large error
+
+    # Pure L1SNR (l1_weight=0)
+    est_snr = estimates.clone().requires_grad_(True)
+    loss_fn_snr = STFTL1SNRDBLoss("test", l1_weight=0.0, n_ffts=[512], hop_lengths=[128], win_lengths=[512])
+    loss_snr = loss_fn_snr(est_snr, actuals)
+    loss_snr.backward()
+    ratio_snr = est_snr.grad[0].abs().mean() / est_snr.grad[1].abs().mean()
+
+    # Pure L1 (l1_weight=1)
+    est_l1 = estimates.clone().requires_grad_(True)
+    loss_fn_l1 = STFTL1SNRDBLoss("test", l1_weight=1.0, n_ffts=[512], hop_lengths=[128], win_lengths=[512])
+    loss_l1 = loss_fn_l1(est_l1, actuals)
+    loss_l1.backward()
+    ratio_l1 = est_l1.grad[0].abs().mean() / est_l1.grad[1].abs().mean()
+
+    # STFT processing smooths out per-sample differences, so ratios are smaller
+    # Key check: L1SNR ratio > L1 ratio (gradient behaviors differ)
+    assert ratio_snr > ratio_l1, f"STFT L1SNR ratio ({ratio_snr}) should be > L1 ratio ({ratio_l1})"
+    # L1: more uniform gradients (ratio closer to 1)
+    assert ratio_l1 < ratio_snr, f"STFT L1 should have more uniform gradients"
+
+
+def test_stft_l1_weight_interpolation():
+    """
+    Verify l1_weight interpolation works for STFTL1SNRDBLoss.
+    L1 weighting should make gradients more uniform compared to pure SNR.
+    """
+    torch.manual_seed(42)
+
+    actuals = torch.tensor([[1.0] * 4096, [1.0] * 4096])
+    estimates = actuals.clone()
+    estimates[0] += 0.01
+    estimates[1] += 0.5
+
+    ratios = []
+    for w in [0.0, 0.5, 1.0]:
+        est = estimates.clone().requires_grad_(True)
+        loss_fn = STFTL1SNRDBLoss("test", l1_weight=w, n_ffts=[512], hop_lengths=[128], win_lengths=[512])
+        loss = loss_fn(est, actuals)
+        loss.backward()
+        ratio = (est.grad[0].abs().mean() / est.grad[1].abs().mean()).item()
+        ratios.append(ratio)
+
+    # L1 weighting should make gradients more uniform (ratio closer to 1)
+    # Pure L1 (l1_weight=1.0) should have more uniform gradients than pure SNR (l1_weight=0.0)
+    assert ratios[2] < ratios[0], \
+        f"L1 weighting should make gradients more uniform: SNR ratio {ratios[0]} should be > L1 ratio {ratios[2]}"
+
+    # All ratios should be > 1 (signal with larger error should have larger gradients)
+    assert all(r > 1.0 for r in ratios), f"All gradient ratios should be > 1.0: {ratios}"

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/torch_l1_snr/__init__.py

@@ -14,4 +14,4 @@ __all__ = [
     "MultiL1SNRDBLoss",
 ] 
 
-__version__ = "0.1.1"
+__version__ = "0.1.2"

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/torch_l1_snr/l1snr.py

@@ -104,9 +104,10 @@ class L1SNRLoss(torch.nn.Module):
         l1snr_loss = torch.mean(d1)
 
         c = 10.0 / math.log(10.0)
-        inv_mean = torch.mean(1.0 / (l1_error.detach() + self.eps))
-        # w-independent scaling to match typical gradient magnitudes
-        scale_time = c * inv_mean
+        # Scale by reference signal magnitude (not error) to preserve gradient distinction
+        # L1SNR has inverse-error gradients; L1 should have uniform gradients
+        inv_ref_mean = torch.mean(1.0 / (l1_true.detach() + self.eps))
+        scale_time = c * inv_ref_mean
         l1_term = torch.mean(l1_error) * scale_time
 
         loss = (1.0 - w) * l1snr_loss + w * l1_term
@@ -446,10 +447,11 @@ class STFTL1SNRDBLoss(torch.nn.Module):
         w = float(self.l1_weight)
         if 0.0 < w < 1.0:
             c = 10.0 / math.log(10.0)
-            inv_mean_comp = torch.mean(0.5 * (1.0 / (err_re.detach() + self.l1snr_eps) +
-                                              1.0 / (err_im.detach() + self.l1snr_eps)))
-            # w-independent scaling to match typical gradient magnitudes (factor 2.0 for Re/Im symmetry)
-            scale_spec = 2.0 * c * inv_mean_comp
+            # Scale by reference signal magnitude (not error) to preserve gradient distinction
+            # L1SNR has inverse-error gradients; L1 should have uniform gradients
+            inv_ref_mean_comp = torch.mean(0.5 * (1.0 / (ref_re.detach() + self.l1snr_eps) +
+                                                  1.0 / (ref_im.detach() + self.l1snr_eps)))
+            scale_spec = 2.0 * c * inv_ref_mean_comp
             l1_term = 0.5 * (torch.mean(err_re) + torch.mean(err_im)) * scale_spec
 
             loss = (1.0 - w) * d1_sum + w * l1_term

{torch_l1_snr-0.1.1 → torch_l1_snr-0.1.2}/torch_l1_snr.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: torch-l1-snr
-Version: 0.1.1
+Version: 0.1.2
 Summary: L1-SNR loss functions for audio source separation in PyTorch
 Home-page: https://github.com/crlandsc/torch-l1-snr
 Author: Christopher Landschoot
@@ -237,7 +237,7 @@ While this can potentially reduce the "cleanliness" of separations and slightly
 
 The implementation is optimized for efficiency: if `l1_weight` is `0.0` or `1.0`, the unused loss component is not computed, saving computational resources.
 
-**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match the gradient magnitudes of the L1SNR component. This helps maintain stable training without manual tuning.
+**Note on Gradient Balancing:** When blending losses (`0.0 < l1_weight < 1.0`), the implementation automatically scales the L1 component to approximately match gradient magnitudes while preserving distinct gradient behaviors. This helps maintain stable training without manual tuning.
 
 ## Limitations