Signal non-convergence in TROP alternating-minimization solvers

Addresses axis B findings #6 and #7 from the silent-failures audit:
trop_global.py:448 outer alternating-min loop, trop_global.py:466
hard-coded range(20) inner FISTA loop, and trop_local.py:680
alternating-minimization loop all exited silently on max_iter
exhaustion, returning the current iterate as if converged.

- trop_global._solve_global_with_lowrank: thread a converged flag through
  the outer loop; count non-convergence events from the inner FISTA and
  surface the count in the outer warning for diagnostic context. One
  warn_if_not_converged call per solver invocation.
- trop_local._estimate_model: thread a converged flag through the outer
  alternating-min loop; call warn_if_not_converged on exhaustion.
- REGISTRY updated under TROP.

New TestTROPConvergenceWarnings class (4 tests) exercises both global
and local paths with forced non-convergence (max_iter=1, tol=1e-15)
and a convergent negative control.

Notable: the default TROP local config (max_iter=100, tol=1e-6) does
not converge within max_iter on typical synthetic panels, so this PR
surfaces a previously silent non-convergence that affected routine
user fits. No numerical change in the returned iterate; the warning
is additive.

Axis-B regression-lint baseline: 5 -> 2 silent range(max_iter) loops
remaining (minor loops in honest_did/power not yet addressed).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: igerber

diff_diff/trop_global.py

@@ -26,7 +26,7 @@
 )
 from diff_diff.trop_local import _soft_threshold_svd, _validate_and_pivot_treatment
 from diff_diff.trop_results import TROPResults
-from diff_diff.utils import safe_inference
+from diff_diff.utils import safe_inference, warn_if_not_converged
 
 
 class TROPGlobalMixin:
@@ -445,6 +445,9 @@ def _solve_global_with_lowrank(
         # Initialize L = 0
         L = np.zeros((n_periods, n_units))
 
+        _FISTA_MAX_ITER = 20
+        inner_nonconverged_count = 0
+        outer_converged = False
         for iteration in range(max_iter):
             L_old = L.copy()
 
@@ -463,7 +466,8 @@ def _solve_global_with_lowrank(
             L_inner_prev = L_inner  # share reference initially (no copy needed)
             t_fista = 1.0
 
-            for _ in range(20):
+            inner_converged = False
+            for _ in range(_FISTA_MAX_ITER):
                 # FISTA momentum
                 t_fista_new = (1.0 + np.sqrt(1.0 + 4.0 * t_fista**2)) / 2.0
                 momentum = (t_fista - 1.0) / t_fista_new
@@ -479,14 +483,26 @@ def _solve_global_with_lowrank(
 
                 # Convergence check (L_inner_prev holds the pre-SVD value)
                 if np.max(np.abs(L_inner - L_inner_prev)) < tol:
+                    inner_converged = True
                     break
+            if not inner_converged:
+                inner_nonconverged_count += 1
 
             L = L_inner
 
             # Outer convergence check
             if np.max(np.abs(L - L_old)) < tol:
+                outer_converged = True
                 break
 
+        if not outer_converged:
+            detail = (
+                f"TROP global alternating minimization "
+                f"(inner FISTA non-converged in {inner_nonconverged_count}/{max_iter} "
+                f"outer iterations, FISTA max_iter={_FISTA_MAX_ITER})"
+            )
+            warn_if_not_converged(False, detail, max_iter, tol)
+
         # Final re-solve with converged L (match Rust behavior)
         Y_adj = Y_safe - L
         mu, alpha, beta = self._solve_global_no_lowrank(Y_adj, delta_masked)

diff_diff/trop_local.py

@@ -25,6 +25,7 @@
     _rust_unit_distance_matrix,
 )
 from diff_diff.trop_results import _PrecomputedStructures
+from diff_diff.utils import warn_if_not_converged
 
 
 def _validate_and_pivot_treatment(data, time, unit, treatment, all_periods, all_units):
@@ -677,6 +678,7 @@ def _estimate_model(
 
         # Alternating minimization following Algorithm 1 (page 9)
         # Minimize: sum W_{ti}(Y_{ti} - alpha_i - beta_t - L_{ti})^2 + lambda_nn||L||_*
+        converged = False
         for _ in range(self.max_iter):
             alpha_old = alpha.copy()
             beta_old = beta.copy()
@@ -717,7 +719,11 @@ def _estimate_model(
             L_diff = np.max(np.abs(L - L_old))
 
             if max(alpha_diff, beta_diff, L_diff) < self.tol:
+                converged = True
                 break
+        warn_if_not_converged(
+            converged, "TROP local alternating minimization", self.max_iter, self.tol
+        )
 
         return alpha, beta, L
 

docs/methodology/REGISTRY.md

@@ -1972,6 +1972,7 @@ Q(λ) = Σ_{j,s: D_js=0} [τ̂_js^loocv(λ)]²
 - **Bootstrap minimum**: `n_bootstrap` must be >= 2 (enforced via `ValueError`). TROP uses bootstrap for all variance estimation — there is no analytical SE formula.
 - **LOOCV failure metadata**: When LOOCV fits fail in the Rust backend, the first failed observation coordinates (t, i) are returned to Python for informative warning messages
 - **Inference CI distribution**: After `safe_inference()` migration, CI uses t-distribution (df = max(1, n_treated_obs - 1)), consistent with p_value. Previously CI used normal-distribution while p_value used t-distribution (inconsistent). This is a minor behavioral change; CIs may be slightly wider for small n_treated_obs.
+- **Note:** Both the `local` alternating-minimization solver (`_estimate_model`) and the `global` alternating-minimization solver (`_solve_global_with_lowrank`, including its hard-coded inner FISTA loop of 20 iterations) emit `UserWarning` via `diff_diff.utils.warn_if_not_converged` when the outer loop exhausts `max_iter` without reaching `tol`. The global-method warning surfaces the inner-FISTA non-convergence count as diagnostic context. Silent return of the current iterate was classified as a silent failure under the Phase 2 audit and replaced with an explicit signal to match the convention used across other iterative solvers in the library.
 
 **Reference implementation(s):**
 - Authors' replication code (forthcoming)

tests/test_trop.py

@@ -3936,3 +3936,109 @@ def test_observed_treatment_nan_raises_local(self):
         )
         with pytest.raises(ValueError, match="missing treatment values"):
             trop_est.fit(df, "outcome", "treated", "unit", "time")
+
+
+class TestTROPConvergenceWarnings:
+    """Silent-failure audit axis B: TROP alternating minimization must warn on non-convergence."""
+
+    @staticmethod
+    def _panel_matrices(simple_panel_data):
+        """Pivot simple_panel_data into (Y, D, n_units, n_periods, treated_periods)."""
+        all_units = sorted(simple_panel_data["unit"].unique())
+        all_periods = sorted(simple_panel_data["period"].unique())
+        n_units = len(all_units)
+        n_periods = len(all_periods)
+        Y = (
+            simple_panel_data.pivot(index="period", columns="unit", values="outcome")
+            .reindex(index=all_periods, columns=all_units)
+            .values
+        )
+        D = (
+            simple_panel_data.pivot(index="period", columns="unit", values="treated")
+            .reindex(index=all_periods, columns=all_units)
+            .fillna(0)
+            .astype(int)
+            .values
+        )
+        treated_periods = int(np.sum(np.any(D == 1, axis=1)))
+        return Y, D, n_units, n_periods, treated_periods
+
+    def test_global_alternating_min_warns_on_nonconvergence(self, simple_panel_data):
+        """_solve_global_with_lowrank must warn when outer alternating-min loop exhausts max_iter."""
+        Y, D, n_units, n_periods, treated_periods = self._panel_matrices(simple_panel_data)
+
+        trop_est = TROP(
+            method="global",
+            lambda_time_grid=[1.0],
+            lambda_unit_grid=[1.0],
+            lambda_nn_grid=[0.1],
+            seed=42,
+        )
+        delta = trop_est._compute_global_weights(
+            Y, D, 1.0, 1.0, treated_periods, n_units, n_periods
+        )
+
+        with pytest.warns(UserWarning, match="did not converge"):
+            trop_est._solve_global_with_lowrank(Y, delta, lambda_nn=0.1, max_iter=1, tol=1e-15)
+
+    def test_global_alternating_min_no_warning_on_convergence(self, simple_panel_data):
+        """_solve_global_with_lowrank must not warn on a well-behaved fit with generous max_iter."""
+        Y, D, n_units, n_periods, treated_periods = self._panel_matrices(simple_panel_data)
+
+        trop_est = TROP(
+            method="global",
+            lambda_time_grid=[1.0],
+            lambda_unit_grid=[1.0],
+            lambda_nn_grid=[0.1],
+            seed=42,
+        )
+        delta = trop_est._compute_global_weights(
+            Y, D, 1.0, 1.0, treated_periods, n_units, n_periods
+        )
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            trop_est._solve_global_with_lowrank(Y, delta, lambda_nn=0.1, max_iter=500, tol=1e-6)
+        assert not any("did not converge" in str(x.message) for x in w)
+
+    def test_local_alternating_min_warns_on_nonconvergence(self, simple_panel_data):
+        """TROP local _estimate_model must warn when alternating-min exhausts max_iter."""
+        Y, D, n_units, n_periods, _ = self._panel_matrices(simple_panel_data)
+        control_mask = (np.sum(D, axis=0) == 0)  # units never treated
+
+        trop_est = TROP(
+            method="local",
+            lambda_time_grid=[1.0],
+            lambda_unit_grid=[1.0],
+            lambda_nn_grid=[0.1],
+            max_iter=1,
+            tol=1e-15,
+            seed=42,
+        )
+        W = np.where(D == 0, 1.0, 0.0)
+
+        with pytest.warns(UserWarning, match="did not converge"):
+            trop_est._estimate_model(Y, control_mask, W, lambda_nn=0.1,
+                                     n_units=n_units, n_periods=n_periods)
+
+    def test_local_alternating_min_no_warning_on_convergence(self, simple_panel_data):
+        """TROP local _estimate_model must not warn on a well-behaved fit."""
+        Y, D, n_units, n_periods, _ = self._panel_matrices(simple_panel_data)
+        control_mask = (np.sum(D, axis=0) == 0)
+
+        trop_est = TROP(
+            method="local",
+            lambda_time_grid=[1.0],
+            lambda_unit_grid=[1.0],
+            lambda_nn_grid=[0.1],
+            max_iter=500,
+            tol=1e-6,
+            seed=42,
+        )
+        W = np.where(D == 0, 1.0, 0.0)
+
+        with warnings.catch_warnings(record=True) as w:
+            warnings.simplefilter("always")
+            trop_est._estimate_model(Y, control_mask, W, lambda_nn=0.1,
+                                     n_units=n_units, n_periods=n_periods)
+        assert not any("did not converge" in str(x.message) for x in w)