Merge remote-tracking branch 'origin/main' into feature/dcdh-survey-variance-extensions

Author: igerber

CHANGELOG.md

@@ -7,8 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.1.2] - 2026-04-18
+
+### Fixed
+- **SyntheticDiD catastrophic cancellation at extreme Y scale** (PR #312) - the Frank-Wolfe weight solver lost precision when outcome magnitudes were very large or very small; results are now numerically stable across scales.
+- **Non-convergence signaling in FE imputation alternating-projection solvers** (PR #314) - `ImputationDiD`, `TwoStageDiD`, and shared `within_transform` now emit a `ConvergenceWarning` when the alternating-projection / weighted-demean loop exits without meeting the tolerance. `max_iter` and `tol` are documented on `within_transform`.
+- **Non-convergence signaling in SyntheticDiD Frank-Wolfe solver** (PR #315) - the numpy-path Frank-Wolfe SC weight solver now emits a `ConvergenceWarning` when the loop exits without meeting `min_decrease`. Wrapper-level and `max_iter=0` regression tests added.
+
 ### Changed
-- Refresh `ROADMAP.md` to drop top-level phase numbering and reflect shipped state through v3.1.1. Absorbs dCDH into the Current State estimator list; adds Recently Shipped summary; reorganizes open work as Shipping Next / Under Consideration / AI-Agent Track / Long-term. Updates `docs/business-strategy.md`, `docs/survey-roadmap.md`, `docs/practitioner_decision_tree.rst`, `docs/choosing_estimator.rst`, `docs/api/chaisemartin_dhaultfoeuille.rst`, `README.md`, and `diff_diff/guides/llms-full.txt` to remove stale phase-deferral language now that the deferred items have shipped.
+- Refresh `ROADMAP.md` to drop top-level phase numbering and reflect shipped state through v3.1.1 (PR #313). Absorbs dCDH into the Current State estimator list; adds Recently Shipped summary; reorganizes open work as Shipping Next / Under Consideration / AI-Agent Track / Long-term. Updates `docs/business-strategy.md`, `docs/survey-roadmap.md`, `docs/practitioner_decision_tree.rst`, `docs/choosing_estimator.rst`, `docs/api/chaisemartin_dhaultfoeuille.rst`, `README.md`, and `diff_diff/guides/llms-full.txt` to remove stale phase-deferral language now that the deferred items have shipped.
+- Bump the `SyntheticDiD(lambda_reg=...)` and `SyntheticDiD(zeta=...)` deprecation warnings' removal target from `v3.1` to `v4.0.0`. Removing public kwargs in a patch / minor release would violate Semantic Versioning; the deprecation stays warning-only throughout the `3.x` line and will be removed in the next major release. Use `zeta_omega` / `zeta_lambda` instead.
 
 ## [3.1.1] - 2026-04-16
 
@@ -1298,6 +1306,7 @@ for the full feature history leading to this release.
 [2.1.2]: https://github.com/igerber/diff-diff/compare/v2.1.1...v2.1.2
 [2.1.1]: https://github.com/igerber/diff-diff/compare/v2.1.0...v2.1.1
 [2.1.0]: https://github.com/igerber/diff-diff/compare/v2.0.3...v2.1.0
+[3.1.2]: https://github.com/igerber/diff-diff/compare/v3.1.1...v3.1.2
 [3.1.1]: https://github.com/igerber/diff-diff/compare/v3.1.0...v3.1.1
 [3.1.0]: https://github.com/igerber/diff-diff/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/igerber/diff-diff/compare/v3.0.1...v3.0.2

TODO.md

@@ -124,7 +124,7 @@ Deprecated parameters still present for backward compatibility:
 
 - `lambda_reg` and `zeta` in `SyntheticDiD` (`synthetic_did.py`)
   - Deprecated in favor of `zeta_omega`/`zeta_lambda` parameters
-  - Remove in v3.1
+  - Remove in v4.0.0 (SemVer-safe: public kwarg removal requires a major bump)
 
 ---
 

diff_diff/__init__.py

@@ -231,7 +231,7 @@
 ETWFE = WooldridgeDiD
 DCDH = ChaisemartinDHaultfoeuille
 
-__version__ = "3.1.1"
+__version__ = "3.1.2"
 __all__ = [
     # Estimators
     "DifferenceInDifferences",

diff_diff/guides/llms-full.txt

@@ -2,7 +2,7 @@
 
 > A Python library for Difference-in-Differences causal inference analysis. Provides sklearn-like estimators with statsmodels-style output for econometric analysis.
 
-- Version: 3.1.1
+- Version: 3.1.2
 - Repository: https://github.com/igerber/diff-diff
 - License: MIT
 - Dependencies: numpy, pandas, scipy (no statsmodels dependency)

diff_diff/synthetic_did.py

@@ -149,14 +149,14 @@ def __init__(
             warnings.warn(
                 "lambda_reg is deprecated and ignored. Regularization is now "
                 "auto-computed from data. Use zeta_omega to override unit weight "
-                "regularization. Will be removed in v3.1.",
+                "regularization. Will be removed in v4.0.0.",
                 DeprecationWarning,
                 stacklevel=2,
             )
         if zeta is not None:
             warnings.warn(
                 "zeta is deprecated and ignored. Use zeta_lambda to override "
-                "time weight regularization. Will be removed in v3.1.",
+                "time weight regularization. Will be removed in v4.0.0.",
                 DeprecationWarning,
                 stacklevel=2,
             )
@@ -1471,7 +1471,7 @@ def set_params(self, **params) -> "SyntheticDiD":
             if key in _deprecated:
                 warnings.warn(
                     f"{key} is deprecated and ignored. Use zeta_omega/zeta_lambda "
-                    f"instead. Will be removed in v3.1.",
+                    f"instead. Will be removed in v4.0.0.",
                     DeprecationWarning,
                     stacklevel=2,
                 )

diff_diff/utils.py

@@ -1460,12 +1460,15 @@ def _sc_weight_fw_numpy(
         lam = np.ones(T0) / T0
 
     vals = np.full(max_iter, np.nan)
+    converged = False
     for t in range(max_iter):
         lam = _fw_step(A, lam, b, eta)
         err = Y @ np.append(lam, -1.0)
         vals[t] = zeta**2 * np.sum(lam**2) + np.sum(err**2) / N
         if t >= 1 and vals[t - 1] - vals[t] < min_decrease**2:
+            converged = True
             break
+    warn_if_not_converged(converged, "Frank-Wolfe SC weight solver", max_iter, min_decrease)
 
     return lam
 

docs/methodology/REGISTRY.md

@@ -1496,7 +1496,7 @@ Convergence criterion: stop when objective decrease < min_decrease² (default mi
   P-value: analytical (normal distribution), not empirical.
 
 *Edge cases:*
-- **Frank-Wolfe non-convergence**: Returns current weights after max_iter iterations. No warning emitted; the convergence check `vals[t-1] - vals[t] < min_decrease²` simply does not trigger early exit, and the final iterate is returned.
+- **Frank-Wolfe non-convergence**: Returns current weights after max_iter iterations when the convergence check `vals[t-1] - vals[t] < min_decrease²` never triggers early exit. The numpy-backend path (`_sc_weight_fw_numpy`) emits a `UserWarning` via `diff_diff.utils.warn_if_not_converged` in that case; the Rust-backend path silently returns the final iterate (Rust-side signature change required to thread convergence status — tracked as an axis-G backend-parity follow-up).
 - **`_sparsify` all-zero input**: If `max(v) <= 0`, returns uniform weights `ones(len(v)) / len(v)`.
 - **Single control unit**: `compute_sdid_unit_weights` returns `[1.0]` immediately (short-circuit before Frank-Wolfe).
 - **Zero control units**: `compute_sdid_unit_weights` returns empty array `[]`.

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "maturin"
 
 [project]
 name = "diff-diff"
-version = "3.1.1"
+version = "3.1.2"
 description = "Difference-in-Differences causal inference with sklearn-like API. Callaway-Sant'Anna, Synthetic DiD, Honest DiD, event studies, parallel trends."
 readme = "README.md"
 license = "MIT"

rust/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "diff_diff_rust"
-version = "3.1.1"
+version = "3.1.2"
 edition = "2021"
 rust-version = "1.84"
 description = "Rust backend for diff-diff DiD library"

tests/test_methodology_sdid.py

@@ -21,6 +21,7 @@
     _compute_regularization,
     _fw_step,
     _sc_weight_fw,
+    _sc_weight_fw_numpy,
     _sparsify,
     _sum_normalize,
     compute_sdid_estimator,
@@ -207,6 +208,58 @@ def test_intercept_centering(self):
         # They should be different because centering matters
         assert not np.allclose(lam_intercept, lam_no_intercept, atol=1e-3)
 
+    def test_fw_warns_on_nonconvergence(self):
+        """Silent-failure audit axis B: _sc_weight_fw_numpy must warn when max_iter exhausts."""
+        rng = np.random.default_rng(42)
+        Y = rng.standard_normal((15, 7))  # (N, T0+1) with T0=6
+
+        with pytest.warns(UserWarning, match="did not converge"):
+            _sc_weight_fw_numpy(Y, zeta=0.1, max_iter=1, min_decrease=1e-12)
+
+    def test_fw_no_warning_on_convergence(self):
+        """Silent-failure audit axis B: no warning on well-conditioned convergent input."""
+        rng = np.random.default_rng(42)
+        Y = rng.standard_normal((15, 7))
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            _sc_weight_fw_numpy(Y, zeta=0.1, max_iter=10000, min_decrease=1e-3)
+        assert not any("did not converge" in str(x.message) for x in w)
+
+    def test_fw_wrapper_warns_on_nonconvergence_without_rust(self):
+        """Silent-failure audit axis B: public _sc_weight_fw wrapper must route
+        warnings through even when called via the dispatcher with the Rust
+        backend disabled. Pins the contract against refactors that would
+        bypass the numpy path."""
+        rng = np.random.default_rng(42)
+        Y = rng.standard_normal((15, 7))
+
+        with patch("diff_diff.utils.HAS_RUST_BACKEND", False):
+            with pytest.warns(UserWarning, match="did not converge"):
+                _sc_weight_fw(Y, zeta=0.1, max_iter=1, min_decrease=1e-12)
+
+    def test_fw_wrapper_no_warning_on_convergence_without_rust(self):
+        """Silent-failure audit axis B: wrapper-level negative control."""
+        rng = np.random.default_rng(42)
+        Y = rng.standard_normal((15, 7))
+
+        with patch("diff_diff.utils.HAS_RUST_BACKEND", False):
+            with warnings.catch_warnings(record=True) as w:
+                warnings.simplefilter("always")
+                _sc_weight_fw(Y, zeta=0.1, max_iter=10000, min_decrease=1e-3)
+            assert not any("did not converge" in str(x.message) for x in w)
+
+    def test_fw_max_iter_zero_warns(self):
+        """Silent-failure audit axis B: max_iter=0 produces the uniform init
+        without iterating, which cannot converge by construction. The warning
+        must fire (consistent with the convention: if we exited the loop
+        without hitting the tolerance gate, we signal). Pins this contract."""
+        Y = np.random.default_rng(0).standard_normal((5, 4))
+
+        with patch("diff_diff.utils.HAS_RUST_BACKEND", False):
+            with pytest.warns(UserWarning, match="did not converge"):
+                _sc_weight_fw(Y, zeta=0.1, max_iter=0)
+
 
 class TestSparsify:
     """Verify sparsification behavior."""