diffcb 0.1.7__tar.gz → 0.1.8__tar.gz

{diffcb-0.1.7 → diffcb-0.1.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: diffcb
-Version: 0.1.7
+Version: 0.1.8
 Summary: Differentiable Critical Bandwidth: Silverman's modality test as a differentiable PyTorch layer with IFT backward pass.
 Project-URL: Homepage, https://github.com/ryZhangHason/differentiable-critical-bandwidth
 Project-URL: Repository, https://github.com/ryZhangHason/differentiable-critical-bandwidth
@@ -295,15 +295,17 @@ Cumulative speedup vs v0.1.4 on CPU: 1.1× (100K), 1.7× (1M), **4.2× (10M)**.
 
 ```python
 DCBLayer(
-    target_modes=1,        # target number of modes (default 1)
-    use_fft=True,          # FFT path for n > 50K (default True)
-    max_n_exact=None,      # sketch above this n (None = always exact)
-    G_min=16384,           # minimum FFT histogram bins (accuracy ↑ with G)
-    use_richardson=True,   # Richardson extrapolation on h_crit (30% accuracy gain)
-    direct_n_max=25_000,   # use direct-KDE (no histogram) for n ≤ this
-    direct_M=2048,         # direct-KDE evaluation grid size
-    use_compile=False,     # infrastructure flag; use TrainingLayer for compile
-    safe_backward=False,   # clamp IFT denominator near bifurcations
+    target_modes=1,           # target number of modes (default 1)
+    use_fft=True,             # FFT path for n > 50K (default True)
+    max_n_exact=None,         # sketch above this n (None = always exact)
+    G_min=16384,              # minimum FFT histogram bins (accuracy ↑ with G)
+    use_richardson="auto",    # Richardson on CPU, off on GPU (30% accuracy gain on CPU)
+    direct_n_max=25_000,      # direct-KDE active only when forward_path='auto'/'direct'
+    direct_M=2048,            # direct-KDE evaluation grid size
+    forward_path='smooth',    # 'smooth' (default, strictly differentiable) |
+                              # 'auto' (direct-KDE at n≤25K, surrogate gradient) |
+                              # 'direct' (force direct-KDE, accuracy benchmarks)
+    safe_backward=False,      # clamp IFT denominator near bifurcations
 )
 ```
 
@@ -343,7 +345,7 @@ By default (`use_richardson=True`), DCB runs a second bisection at G/2=8192 and
 
 - **`compile=True` on MPS**: blocked by float64 in `_refine_hcrit` fallback (fix in v0.1.7)
 - **`compile=True` on CUDA with Python 3.12**: requires torch ≥ 2.4 or Python ≤ 3.11
-- **`gradcheck` with direct-KDE forward**: forward (n ≤ 25K) uses exact KDE; backward uses smooth IFT surrogate — gradcheck will fail by design; use `DCBLayer(direct_n_max=0)` for gradcheck
+- **`gradcheck`**: passes with the default `forward_path='smooth'`; the default is strictly differentiable at all n. Opt into `forward_path='auto'` only for forward-only accuracy benchmarks (surrogate gradient at n≤25K)
 - **n > 100M**: requires streaming histogram (not yet public API); use `max_n_exact=1_000_000` sketch as workaround
 
 ## Confirmed Experimental Results

{diffcb-0.1.7 → diffcb-0.1.8}/README.md

@@ -73,15 +73,17 @@ Cumulative speedup vs v0.1.4 on CPU: 1.1× (100K), 1.7× (1M), **4.2× (10M)**.
 
 ```python
 DCBLayer(
-    target_modes=1,        # target number of modes (default 1)
-    use_fft=True,          # FFT path for n > 50K (default True)
-    max_n_exact=None,      # sketch above this n (None = always exact)
-    G_min=16384,           # minimum FFT histogram bins (accuracy ↑ with G)
-    use_richardson=True,   # Richardson extrapolation on h_crit (30% accuracy gain)
-    direct_n_max=25_000,   # use direct-KDE (no histogram) for n ≤ this
-    direct_M=2048,         # direct-KDE evaluation grid size
-    use_compile=False,     # infrastructure flag; use TrainingLayer for compile
-    safe_backward=False,   # clamp IFT denominator near bifurcations
+    target_modes=1,           # target number of modes (default 1)
+    use_fft=True,             # FFT path for n > 50K (default True)
+    max_n_exact=None,         # sketch above this n (None = always exact)
+    G_min=16384,              # minimum FFT histogram bins (accuracy ↑ with G)
+    use_richardson="auto",    # Richardson on CPU, off on GPU (30% accuracy gain on CPU)
+    direct_n_max=25_000,      # direct-KDE active only when forward_path='auto'/'direct'
+    direct_M=2048,            # direct-KDE evaluation grid size
+    forward_path='smooth',    # 'smooth' (default, strictly differentiable) |
+                              # 'auto' (direct-KDE at n≤25K, surrogate gradient) |
+                              # 'direct' (force direct-KDE, accuracy benchmarks)
+    safe_backward=False,      # clamp IFT denominator near bifurcations
 )
 ```
 
@@ -121,7 +123,7 @@ By default (`use_richardson=True`), DCB runs a second bisection at G/2=8192 and
 
 - **`compile=True` on MPS**: blocked by float64 in `_refine_hcrit` fallback (fix in v0.1.7)
 - **`compile=True` on CUDA with Python 3.12**: requires torch ≥ 2.4 or Python ≤ 3.11
-- **`gradcheck` with direct-KDE forward**: forward (n ≤ 25K) uses exact KDE; backward uses smooth IFT surrogate — gradcheck will fail by design; use `DCBLayer(direct_n_max=0)` for gradcheck
+- **`gradcheck`**: passes with the default `forward_path='smooth'`; the default is strictly differentiable at all n. Opt into `forward_path='auto'` only for forward-only accuracy benchmarks (surrogate gradient at n≤25K)
 - **n > 100M**: requires streaming histogram (not yet public API); use `max_n_exact=1_000_000` sketch as workaround
 
 ## Confirmed Experimental Results

{diffcb-0.1.7 → diffcb-0.1.8}/dcb/__init__.py

@@ -21,4 +21,4 @@ __all__ = [
     "TrainingLayer",
     "anneal_eps_tau", "soft_mode_count_cross", "soft_mode_count",
 ]
-__version__ = "0.1.7"
+__version__ = "0.1.8"

{diffcb-0.1.7 → diffcb-0.1.8}/dcb/layer.py

@@ -14,16 +14,16 @@ the computational graph of the iterative solver and maintaining O(1) memory
 cost relative to the number of solver iterations. Hyperparameters ε and τ
 may be supplied explicitly or computed adaptively via `dcb.utils`.
 
-Forward/backward path mismatch (by design)
--------------------------------------------
-At n ≤ direct_n_max AND forward_path='auto' (default), the FORWARD pass uses
-direct KDE (no histogram) for zero binning bias.  The BACKWARD pass always
-uses the smooth IFT on M̃ (soft mode count) at all n.  These are different
-implicit functions, so ``torch.autograd.gradcheck`` will fail for
-n ≤ direct_n_max with the default settings.  Use ``forward_path='smooth'``
-to force the smooth path in the forward pass — gradcheck will then pass.
-For ML training the mismatch is correct by design: the smooth gradient is
-the appropriate object for gradient descent.
+Strict differentiability
+------------------------
+``forward_path='smooth'`` (the default) forces both the forward and backward
+to use the same smooth M̃ surrogate at all n — ``torch.autograd.gradcheck``
+passes and ∂h_crit/∂X is the exact IFT gradient of the computed h_crit.
+
+``forward_path='auto'`` opts into the direct-KDE forward at n ≤ direct_n_max
+for zero-bias accuracy, but forward and backward then use different implicit
+functions — gradcheck will fail and the gradient is a surrogate.  Only use
+'auto' for forward-only inference benchmarks.
 """
 
 from __future__ import annotations
@@ -189,26 +189,17 @@ class DCBLayer(nn.Module):
     forward_path : str
         Controls forward-pass routing.  One of:
 
-        - ``'auto'`` (default): use direct-KDE for n ≤ direct_n_max, FFT
-          histogram for n > 50K, legacy chunked-KDE for 50K >= n > direct_n_max.
-          This is the current behaviour.
-        - ``'smooth'``: always use the FFT histogram or chunked-KDE path
-          (never direct-KDE).  Internally sets direct_n_max=0.
-          **Use this when you need ``torch.autograd.gradcheck`` to pass**,
-          because it forces forward and backward to use the same smooth M̃.
-        - ``'direct'``: force direct-KDE even for large n.  Slow for large n;
-          intended for accuracy benchmarks.  Internally sets direct_n_max=inf.
-
-        Notes
-        -----
-        Forward/backward path at n <= direct_n_max:
-            The forward pass uses direct KDE (no histogram) for accuracy.
-            The backward pass uses the smooth IFT on M̃ (soft mode count) at all n.
-            These are different implicit functions, so ``torch.autograd.gradcheck``
-            will fail for n <= direct_n_max.  Use ``forward_path='smooth'`` to
-            force the smooth path at all n — gradcheck will then pass.
-            For ML training this mismatch is correct by design: the smooth
-            gradient is the appropriate object for gradient descent.
+        - ``'smooth'`` **(default)**: always use the FFT histogram or
+          chunked-KDE path.  Both forward and backward use the same smooth
+          M̃ surrogate — ``torch.autograd.gradcheck`` passes and gradients
+          are the exact IFT derivatives of the computed h_crit.
+        - ``'auto'``: use direct-KDE for n ≤ direct_n_max (zero histogram
+          bias), FFT for n > 50K, chunked-KDE otherwise.  Forward and
+          backward use different implicit functions at n ≤ direct_n_max,
+          so gradcheck will fail and the gradient is a surrogate.
+          Use only for forward-only inference / accuracy benchmarks.
+        - ``'direct'``: force direct-KDE at all n (accuracy benchmark only;
+          slow for large n; surrogate gradient at all n).
 
     Examples
     --------
@@ -244,7 +235,7 @@ class DCBLayer(nn.Module):
         use_compile: bool = False,
         direct_n_max: int = 25_000,
         direct_M: int = 2048,
-        forward_path: str = 'auto',
+        forward_path: str = 'smooth',
     ):
         super().__init__()
         if forward_path not in ('auto', 'smooth', 'direct'):

{diffcb-0.1.7 → diffcb-0.1.8}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "diffcb"
-version = "0.1.7"
+version = "0.1.8"
 description = "Differentiable Critical Bandwidth: Silverman's modality test as a differentiable PyTorch layer with IFT backward pass."
 readme = "README.md"
 license = { file = "LICENSE" }

{diffcb-0.1.7 → diffcb-0.1.8}/tests/test_gradcheck.py

@@ -17,37 +17,29 @@ from dcb.layer import DCBLayer
 # ---------------------------------------------------------------------------
 
 def test_gradcheck_smooth_path():
-    """gradcheck passes when forward_path='smooth' forces smooth M̃ at all n.
-
-    With forward_path='smooth', direct_n_max is set to 0 internally, so the
-    forward pass uses the same chunked-KDE path as the IFT backward (both use
-    the smooth M̃ without direct-KDE).  The forward and backward are consistent
-    implicit functions, so gradcheck passes.
-
-    Tolerances are intentionally loose (atol=0.05, rtol=0.2) because:
-    1. Hard bisection finds h_crit by discrete mode-count steps, introducing
-       quantisation noise of ~O(bisection_tol) in h_crit.
-    2. The IFT backward uses smooth M̃ evaluated at this h_crit, which is
-       not perfectly aligned with the bisection steps.
-    3. These two effects cause O(1%) discrepancies between the analytical
-       and numerical Jacobians — well within the intended ML-training use case,
-       but requiring loose gradcheck tolerances to pass reliably.
+    """gradcheck passes with the default DCBLayer (forward_path='smooth').
+
+    forward_path='smooth' (the default since v0.1.7) forces both the forward
+    pass and the IFT backward to use the same smooth M̃ surrogate — they are
+    the same implicit function, so gradcheck is internally consistent.
+
+    Tolerances are loose (atol=0.05, rtol=0.2) because the hard bisection
+    root-finder introduces O(1%) quantisation noise between the analytical
+    IFT gradient and the finite-difference Jacobian.  This is the expected
+    residual for the discrete-step bisection and does not affect ML training.
     """
     torch.manual_seed(42)
     X = torch.cat([torch.randn(30) - 1.0, torch.randn(30) + 1.0]).double()
     X.requires_grad_(True)
+    # Default forward_path='smooth' — strictly differentiable at all n
     layer = DCBLayer(
-        use_fft=False,           # use chunked-KDE (smooth) at small n
-        forward_path='smooth',   # disable direct-KDE routing; sets direct_n_max=0
-        use_richardson=False,    # Richardson adds a second backward; skip for gradcheck
+        use_fft=False,
+        use_richardson=False,   # skip Richardson for gradcheck clarity
     )
 
-    # eps=1e-3 for finite differences; atol/rtol are loose because the smooth
-    # IFT gradient and FD Jacobian can differ by ~1–5% due to bisection
-    # quantisation — verified reliable across 20 seeds.
     result = torch.autograd.gradcheck(layer, (X,), eps=1e-3, atol=0.05, rtol=0.2,
                                       raise_exception=True)
-    assert result, "gradcheck failed with forward_path='smooth'"
+    assert result, "gradcheck failed with default DCBLayer (forward_path='smooth')"
 
 
 # ---------------------------------------------------------------------------

{diffcb-0.1.7 → diffcb-0.1.8}/tests/test_layer.py

@@ -121,24 +121,27 @@ def test_dcblayer_state_dict():
 
 @pytest.mark.xfail(
     reason=(
-        "IFT gradient is an approximation (soft M̃_cross at h_crit found by hard bisection). "
-        "gradcheck at atol=1e-3 is too strict for the soft/hard mismatch at small n. "
-        "Qualitative correctness verified in test_ift_gradient_matches_finite_diff."
+        "Hard bisection introduces quantisation noise even with forward_path='smooth'. "
+        "atol=1e-3 is too strict for the bisection step-function discretisation. "
+        "Qualitative correctness verified in test_ift_gradient_matches_finite_diff; "
+        "loose-tolerance gradcheck passes in tests/test_gradcheck.py."
     ),
     strict=False,
 )
 def test_dcblayer_gradcheck():
     """torch.autograd.gradcheck with double precision, eps=1e-4, atol=1e-3.
 
-    Uses bimodal X with n=30 (small for speed). This is the strictest criterion.
-    gradcheck verifies that the custom IFT backward matches the numerical Jacobian.
+    Uses bimodal X with n=30 (small for speed).  Default forward_path='smooth'
+    means forward and backward use the same M̃ surrogate — the remaining xfail
+    is due to bisection quantisation noise (step-function root-finding), not a
+    forward/backward path mismatch.  Loose-tolerance gradcheck passes separately.
     """
     torch.manual_seed(42)
     n = 30
     X_base = torch.cat([torch.randn(15) - 1.0, torch.randn(15) + 1.0])
     X = X_base.double().requires_grad_(True)
 
-    layer = DCBLayer(target_modes=1, G=64)
+    layer = DCBLayer(target_modes=1, G=64)  # default forward_path='smooth'
 
     def fn(x):
         return layer(x)