diffcb 0.1.0__py3-none-any.whl

dcb/utils.py

@@ -0,0 +1,183 @@
+"""
+dcb.utils — Adaptive Hyperparameter Defaults, Grid Construction, and Helpers
+
+This module provides utilities for constructing the evaluation grid Ω and for
+setting the softening hyperparameters ε and τ adaptively from data, following
+the data-adaptive defaults described in the DCB paper: ε = 0.1 · std_{x∈Ω}[f'_{h0}(x)]
+and τ = 0.2 · median_{x∈Ω}[|f''_{h0}(x)|], where h0 is a pilot bandwidth
+(Silverman's rule). The function `make_grid(X, G, margin_sigma)` returns a
+G-point uniform grid over [min(X) - margin·σ, max(X) + margin·σ]; the
+function `adaptive_eps_tau(X, h0, grid)` returns the tuple (ε, τ) computed
+from the pilot KDE derivatives; and `cosine_anneal(eps, tau, step, T_max)`
+returns annealed versions that tighten the smoothing over the course of
+training. The stabilized reciprocal `sg(u, delta)` is also defined here.
+"""
+
+from __future__ import annotations
+
+import math
+
+import torch
+from torch import Tensor
+
+
+def silverman_bandwidth(X: Tensor) -> float:
+    """Return Silverman's rule-of-thumb bandwidth h0 = 0.9 * std(X) * n^{-0.2}.
+
+    Parameters
+    ----------
+    X:
+        1-D sample tensor of shape (n,).
+
+    Returns
+    -------
+    float
+        Positive scalar bandwidth estimate.
+    """
+    n = X.shape[0]
+    std = X.std(unbiased=True).item()
+    return 0.9 * std * (n ** -0.2)
+
+
+def make_grid(X: Tensor, G: int, margin_sigma: float = 3.0) -> Tensor:
+    """Return a G-point uniform grid over [min(X) - margin_sigma*std, max(X) + margin_sigma*std].
+
+    Parameters
+    ----------
+    X:
+        1-D sample tensor of shape (n,).
+    G:
+        Number of grid points.
+    margin_sigma:
+        Number of standard deviations to extend beyond the data range.
+
+    Returns
+    -------
+    Tensor
+        Shape (G,), same dtype and device as X.
+    """
+    std = X.std().item()
+    lo = X.min().item() - margin_sigma * std
+    hi = X.max().item() + margin_sigma * std
+    return torch.linspace(lo, hi, G, dtype=X.dtype, device=X.device)
+
+
+def sg(u: Tensor, delta: float = 1e-4) -> Tensor:
+    """Stabilized gradient operator: sign(u) * max(|u|, delta).
+
+    Handles u=0 by returning delta (not 0), ensuring the output is never zero.
+
+    Parameters
+    ----------
+    u:
+        Input tensor of any shape.
+    delta:
+        Minimum absolute value floor. Default 1e-4.
+
+    Returns
+    -------
+    Tensor
+        Same shape as u; zero inputs map to +delta.
+    """
+    # sign(0) == 0, so zero inputs would give 0*delta == 0 — treat zero as +1
+    sign = torch.where(u >= 0, torch.ones_like(u), -torch.ones_like(u))
+    return sign * u.abs().clamp(min=delta)
+
+
+def adaptive_eps_tau(
+    X: Tensor,
+    h0: float,
+    grid: Tensor,
+    eps_coeff: float = 0.1,
+    tau_coeff: float = 0.2,
+) -> tuple[float, float]:
+    """Compute adaptive (eps, tau) from pilot KDE derivatives on the grid.
+
+    Uses the analytical Gaussian kernel derivative formulas to estimate the
+    first and second derivatives of the pilot KDE at bandwidth h0, then sets:
+        eps = eps_coeff * std(f')
+        tau = tau_coeff * median(|f''|)
+    Both values are clamped to at least 1e-8.
+
+    Parameters
+    ----------
+    X:
+        1-D sample tensor of shape (n,).
+    h0:
+        Pilot bandwidth (e.g. from silverman_bandwidth).
+    grid:
+        Evaluation grid of shape (G,).
+    eps_coeff:
+        Scaling coefficient for eps. Default 0.1.
+    tau_coeff:
+        Scaling coefficient for tau. Default 0.2.
+
+    Returns
+    -------
+    tuple[float, float]
+        (eps, tau), both positive floats >= 1e-8.
+    """
+    # diff[i, j] = (grid[j] - X[i]) / h0  — shape (n, G)
+    diff = (grid.unsqueeze(0) - X.unsqueeze(1)) / h0          # (n, G)
+    K = torch.exp(-0.5 * diff ** 2) / (math.sqrt(2 * math.pi) * h0)
+    f_prime = (-diff / h0 * K).mean(dim=0)                    # (G,)
+    f_double_prime = ((diff ** 2 - 1) / h0 ** 2 * K).mean(dim=0)  # (G,)
+
+    eps = eps_coeff * f_prime.std().item()
+    tau = tau_coeff * f_double_prime.abs().median().item()
+
+    eps = max(eps, 1e-8)
+    tau = max(tau, 1e-8)
+    return eps, tau
+
+
+def anneal_eps_tau(eps: float, tau: float, anneal_factor: float) -> tuple[float, float]:
+    """Scale (eps, tau) by anneal_factor to sharpen the soft mode-count approximation.
+
+    At anneal_factor=1.0 returns the original adaptive defaults.
+    At anneal_factor→0, M̃(h) converges to the true integer mode count M(h),
+    but IFT gradients become ill-conditioned.  Typical evaluation values:
+    0.05–0.10 for best accuracy; use 1.0 during gradient-based training.
+
+    Parameters
+    ----------
+    eps : float
+        Base Gaussian-delta width (from adaptive_eps_tau).
+    tau : float
+        Base sigmoid temperature (from adaptive_eps_tau).
+    anneal_factor : float
+        Multiplicative scale ∈ (0, 1].  Clamped to [1e-6, 1.0].
+
+    Returns
+    -------
+    tuple[float, float]
+        (eps_annealed, tau_annealed), both >= 1e-8.
+    """
+    factor = max(1e-6, min(1.0, anneal_factor))
+    return max(eps * factor, 1e-8), max(tau * factor, 1e-8)
+
+
+def cosine_anneal(val_init: float, val_final: float, step: int, T_max: int) -> float:
+    """Cosine annealing schedule from val_init to val_final over T_max steps.
+
+    At step=0 returns val_init exactly; at step=T_max returns val_final exactly.
+    Steps beyond T_max are clamped to T_max (returns val_final).
+
+    Parameters
+    ----------
+    val_init:
+        Starting value (returned at step=0).
+    val_final:
+        Ending value (returned at step=T_max).
+    step:
+        Current step index (0-based).
+    T_max:
+        Total number of annealing steps.
+
+    Returns
+    -------
+    float
+        Annealed value at the given step.
+    """
+    t = min(step, T_max)
+    return val_final + 0.5 * (val_init - val_final) * (1 + math.cos(math.pi * t / T_max))

diffcb-0.1.0.dist-info/METADATA

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: diffcb
+Version: 0.1.0
+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
+Project-URL: Documentation, https://github.com/ryZhangHason/differentiable-critical-bandwidth#readme
+Project-URL: Bug Tracker, https://github.com/ryZhangHason/differentiable-critical-bandwidth/issues
+Author-email: Ruiyu Zhang <dhhhason@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Ruiyu Zhang
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: PyTorch,anomaly detection,critical bandwidth,differentiable programming,generative models,kernel density estimation,mode counting,nonparametric statistics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.9
+Requires-Dist: matplotlib>=3.7.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scikit-learn>=1.3.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: torch>=2.0.0
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Provides-Extra: notebooks
+Requires-Dist: ipywidgets>=8.0.0; extra == 'notebooks'
+Requires-Dist: jupyter>=1.0.0; extra == 'notebooks'
+Description-Content-Type: text/markdown
+
+# DCB — Differentiable Critical Bandwidth
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
+
+A PyTorch package that makes **Silverman's critical bandwidth test (1981)** fully differentiable, enabling end-to-end gradient-based optimization over the modal structure of continuous distributions.
+
+## Overview
+
+The critical bandwidth `h_crit` is the minimum KDE bandwidth at which a distribution appears to have at most `m` modes — a classical nonparametric statistic for modality testing. DCB replaces every non-differentiable operation in its computation with a smooth surrogate, then uses the **Implicit Function Theorem** to compute exact gradients through the root-finding step at O(1) memory cost.
+
+```python
+import torch
+from dcb import DCBLayer
+
+X = torch.randn(256, requires_grad=True)   # 1D samples
+layer = DCBLayer(target_modes=1)
+h_crit = layer(X)                          # differentiable scalar
+h_crit.backward()                          # exact IFT gradients
+```
+
+## Installation
+
+```bash
+pip install dcb
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/ryZhangHason/dcb
+cd dcb
+pip install -e ".[dev]"
+```
+
+## Paper
+
+> Ruiyu Zhang. "Differentiable Critical Bandwidth: Making Silverman's Modality Test End-to-End Trainable." *Journal of Machine Learning Research*, 2026 (in preparation).
+
+## Confirmed Experimental Results
+
+All results produced on Kaggle GPU (T4 / P100) — see `experiments/` and `outputs/`.
+
+| Experiment | Result | Criterion |
+|---|---|---|
+| **Validation (m≥2)** | R²=0.91, MAE=0.07, Spearman ρ=0.89 | R²≥0.85, MAE≤0.10 ✓ |
+| **Speedup vs scipy (n=8192)** | **10.5×** on T4 | ≥3× ✓ |
+| **GAN mode preservation** | h_crit=1.232 >> 0.3 | h_crit>0.3 ✓ |
+| **Anomaly AUC (KDDCup99)** | DCB=**0.9982** vs IF=0.9867 | DCB≥IF ✓ |
+
+## Repository Structure
+
+```
+dcb/            Core PyTorch package (layer.py, solver.py, kde.py, utils.py)
+experiments/    Reproduction scripts for all paper figures and tables
+  phase1_validation.py   Figure 1: DCB vs reference h_crit scatter
+  phase1_speedup.py      Figure 2: GPU speedup benchmark
+  phase1_ablation.py     Figures S1–S2: ε/τ sensitivity heatmaps
+  phase2_gan.py          Figure 3: GAN mode-collapse prevention
+  phase3_anomaly.py      Table 2 + Figure 5: anomaly detection benchmark
+tests/          Unit tests (pytest, 35/35 passing)
+outputs/        All generated figures and tables (PDFs, PNGs, CSVs)
+notebooks/      Quickstart and demo notebooks
+```
+
+## Reproducing Paper Results
+
+```bash
+# Phase 1: validation, speedup, ablation
+python experiments/phase1_validation.py
+python experiments/phase1_speedup.py
+python experiments/phase1_ablation.py
+
+# Phase 2: GAN mode collapse experiment
+python experiments/phase2_gan.py
+
+# Phase 3: anomaly detection benchmark
+python experiments/phase3_anomaly.py
+```
+
+For GPU runs, use the provided Kaggle kernels:
+- Phase 1–2: `hsingle/dcb-full-experiments`
+- Phase 3: `hsingle/dcb-phase-3-anomaly-detection`
+
+## Kaggle GPU Notes
+
+Kaggle may assign a P100 (sm_60) instead of T4. The Phase 3 kernel handles this automatically by installing `torch==2.2.2+cu118` (the earliest PyTorch release with both Python 3.12 and sm_60 support) when P100 is detected.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

diffcb-0.1.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+dcb/__init__.py,sha256=M8ML4Ih1-VCAXwnzaTJqhY_NAL7xSRqV_YvYu6ztx_I,943
+dcb/diagnostics.py,sha256=oVWjgvlzCFN_hjGfIFU8BGgHJZ6xyVW2OnqlcBM-Dr4,6176
+dcb/fft_kde.py,sha256=euNX9rF8nXSJql0MtCDe_pasX-epWQ2L88ATNwKKIKM,4408
+dcb/kde.py,sha256=OSRqWV9_N_kaO9iOPXe9177mU32vMBgyTk0Bt4T13Tk,14147
+dcb/layer.py,sha256=6naZ0cm59orGz1eHKbt_Ih9qrIcfrOMzrtJJ5SAJ7xE,9787
+dcb/solver.py,sha256=97YFDR5Zjgxh3s9dghd00GljFVBWWYedv2cmi1F0Wzc,23206
+dcb/utils.py,sha256=beEVAwYcesK3WE0fSR1fsWL-y_t7TgcQQ5aWxXXNYRM,5787
+diffcb-0.1.0.dist-info/METADATA,sha256=72zc5v7w9yS0n4uxW7Hji4fSz-CJbZ64IXczeTa1pWc,6434
+diffcb-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+diffcb-0.1.0.dist-info/licenses/LICENSE,sha256=HS739ewRDP0n8t75HCwgUl5UDFH4Ab8eVrbAnBD11BA,1068
+diffcb-0.1.0.dist-info/RECORD,,

diffcb-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

diffcb-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruiyu Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.