From 594b06ff308765f2c231c51f8d3e4216e630afe9 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 15:52:07 +0900 Subject: [PATCH 01/29] feat: add provisional many-body minimax solver and envelope gradient (ported from ellcech) Squash of local topic branch project26-port-minimax (8 commits) after two local Codex review rounds (gpt-5.6-sol, read-only): - round 1: REQUEST CHANGES, 3 documentation findings (contract exactness under regularization/conditioning; regularization scope and condition_number_limit guarantee; nonexistent damped-Newton fallback); fixed in 972ddbc (gpt-5.6-luna). - round 2: REQUEST CHANGES, residual wording (unadjusted := regularization == 0 and condition_number_limit is None; outputs are approximations); fixed in 2ed9783. Two-round cap reached; dispositions recorded here. No executable change relative to ellcech 82d13e3 (650-case bitwise comparison); checklist black/flake8/mypy/stubtest/pytest(396) passes. Names are provisional pending owner decisions in uda-lab/project-ellphi#26. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- AGENTS.md | 4 + src/ellphi/__init__.py | 12 + src/ellphi/__init__.pyi | 14 + src/ellphi/minimax.py | 1237 +++++++++++++++++++++++++++++++++ src/ellphi/minimax.pyi | 49 ++ src/ellphi/minimax_grad.py | 156 +++++ src/ellphi/minimax_grad.pyi | 25 + stubtest-allowlist.txt | 1 + tests/factories.py | 20 + tests/test_minimax.py | 410 +++++++++++ tests/test_minimax_grad.py | 290 ++++++++ tests/test_minimax_methods.py | 356 ++++++++++ 12 files changed, 2574 insertions(+) create mode 100644 src/ellphi/minimax.py create mode 100644 src/ellphi/minimax.pyi create mode 100644 src/ellphi/minimax_grad.py create mode 100644 src/ellphi/minimax_grad.pyi create mode 100644 tests/test_minimax.py create mode 100644 tests/test_minimax_grad.py create mode 100644 tests/test_minimax_methods.py diff --git a/AGENTS.md b/AGENTS.md index 1c885c6..5a46c04 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,6 +90,10 @@ This section documents the reasons for each entry in the `stubtest-allowlist.txt **Reason:** This entry is necessary because the `MethodName` type alias is defined as a `typing.Literal` in the implementation, but it is simplified to `str` in the corresponding stub file (`.pyi`). This simplification is intentional to avoid duplicating the literal values in the stub, which would make it harder to maintain. (An equivalent entry for the `ellphi.solver` re-export was needed with older mypy versions but is reported as unused since mypy 1.20.) +* `ellphi.minimax.MethodName` + +**Reason:** The stub declares the same seven-value `typing.Literal` alias as the implementation, but stubtest cannot verify multi-value `Literal` aliases: it expands the stub alias into a union of single-value literals and reports the runtime alias as "not a Union". Simplifying the stub to `str` does not avoid the report either, so the entry keeps the precise stub type. + #### Managing the Allowlist When adding a new entry to the `stubtest-allowlist.txt` file, you must also update the "Allowlist Justification" section in this document to include a clear and concise explanation for why the entry is needed. This ensures that the allowlist remains transparent and easy to manage. diff --git a/src/ellphi/__init__.py b/src/ellphi/__init__.py index fe3e6f0..1a584be 100644 --- a/src/ellphi/__init__.py +++ b/src/ellphi/__init__.py @@ -14,6 +14,8 @@ two ellipses. - `ellphi.visualization`: Helper functions for visualizing ellipses and ellipse clouds. +- `ellphi.minimax`, `ellphi.minimax_grad`: Many-body minimax filtration + values and their gradients (provisional names). """ import numpy as np @@ -46,6 +48,10 @@ from .grad import TangencyGrad, tangency_grad, pdist_tangency_grad, coef_from_cov_grad +# many-body minimax (provisional names) +from .minimax import MinimaxResult, solve_minimax, solve_minimax_from_coefs +from .minimax_grad import GradientResult, compute_gradient + FloatArray = NDArray[np.float64] @@ -76,6 +82,12 @@ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", + # many-body minimax (provisional) + "MinimaxResult", + "solve_minimax", + "solve_minimax_from_coefs", + "GradientResult", + "compute_gradient", "__version__", "version_info", ] diff --git a/src/ellphi/__init__.pyi b/src/ellphi/__init__.pyi index e608f45..e42786d 100644 --- a/src/ellphi/__init__.pyi +++ b/src/ellphi/__init__.pyi @@ -32,6 +32,15 @@ from .grad import ( pdist_tangency_grad as pdist_tangency_grad, coef_from_cov_grad as coef_from_cov_grad, ) +from .minimax import ( + MinimaxResult as MinimaxResult, + solve_minimax as solve_minimax, + solve_minimax_from_coefs as solve_minimax_from_coefs, +) +from .minimax_grad import ( + GradientResult as GradientResult, + compute_gradient as compute_gradient, +) from ._version import __version__ as __version__ def version_info() -> str: ... @@ -59,6 +68,11 @@ __all__ = [ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", + "MinimaxResult", + "solve_minimax", + "solve_minimax_from_coefs", + "GradientResult", + "compute_gradient", "FloatArray", "__version__", "version_info", diff --git a/src/ellphi/minimax.py b/src/ellphi/minimax.py new file mode 100644 index 0000000..9b55755 --- /dev/null +++ b/src/ellphi/minimax.py @@ -0,0 +1,1237 @@ +"""Many-body minimax solver for anisotropic filtration values (provisional). + +Provenance +---------- +Adapted from uda-lab/ellcech ``src/ellphi_alpha/minimax.py`` at commit +82d13e3e174f4903cdcd6adcee1f469348361c91, by Tomoki Uda (the author of +EllPHi). That file is byte-identical at ellcech ``main`` +893056409db56865b7432274562db2d863e0abce. Numerical behaviour, method +strings, defaults and tolerances are kept unchanged; the changes are +packaging-level only (intra-package import of ``unpack_conic``, type +annotations, documentation). Distributed as part of EllPHi under its MIT +license. The rights question for the ellcech source is tracked in +uda-lab/project-ellphi#26. The docstring corrections in items 1–3 +deliberately deviate from the ellcech 82d13e3 docstrings; code paths are +unchanged. + +The module name and the public names exported from ``ellphi`` are +provisional and may change. + +Mathematical background +----------------------- +Given vertices ``i = 0, ..., k-1`` with centers ``x_i`` in R^d and SPD +matrices ``A_i``, the exact filtration value is + + alpha = min_x max_i f_i(x), f_i(x) = (x - x_i)^T A_i (x - x_i). + +``alpha`` is a *squared* scale. In the pairwise case ``k = 2`` the exact +value equals ``ellphi.tangency(p, q).t ** 2``; the tangency time is +``sqrt(alpha)``. Every solver output is a finite-precision, finite-iteration +approximation of these mathematical quantities (within the tolerances and +subject to ``converged``). An *unadjusted* solve (``regularization == 0`` +and ``condition_number_limit is None``) approximates the exact problem +directly; passing ``condition_number_limit`` always applies at least a +machine-epsilon diagonal shift, and any positive ``regularization`` shifts +``A(mu)``, so adjusted solves approximate a stabilised problem instead. + +By strong duality, ``alpha = max_{mu in Delta^{k-1}} g(mu)`` with + + A(mu) = sum_i mu_i A_i + b(mu) = sum_i mu_i A_i x_i + g(mu) = sum_i mu_i x_i^T A_i x_i - b(mu)^T A(mu)^{-1} b(mu) + = sum_i mu_i f_i(x*(mu)), + +where ``x*(mu) = A(mu)^{-1} b(mu)`` is the circumcenter. The dual gradient is +``dg/dmu_i = f_i(x*(mu))`` and the Hessian is +``d2g/dmu_i dmu_j = -2 (x* - x_i)^T A_i A(mu)^{-1} A_j (x* - x_j)``. +These identities describe the unadjusted problem; with regularization or +conditioning the solver works on a stabilised ``A(mu)`` and its outputs +approximate that stabilised problem. + +Weight support versus tight set +------------------------------- +``MinimaxResult.active_set`` is the *weight support* +``{i : weights[i] > weight_tol}``. It is not the tight constraint set +``{i : f_i(circumcenter) == alpha}``. At an exact optimum the support of the +weights lies inside the tight set, but the tight set can be strictly larger: +for three unit balls centered at ``(0, 0)``, ``(2, 0)`` and ``(0, 2)``, all +three constraints are tight at the circumcenter ``(1, 1)`` with +``alpha = 2``, while the unique optimal weights are ``(0, 1/2, 1/2)``. + +Value versus derivative reliability +----------------------------------- +``MinimaxResult.converged`` reports whether the chosen method met its own +stopping test for the value. It is not a certificate that ``alpha`` is +differentiable at the input or that the returned weights are accurate enough +for derivatives; see :mod:`ellphi.minimax_grad` for the hypotheses under +which the gradient formula applies. + +Correspondence with the pairwise solver +--------------------------------------- +For ``k = 2`` the pairwise solver finds the root of +``F(mu) = f_i(x*(mu)) - f_j(x*(mu))``, while this module maximises ``g`` +over ``Delta^1``; both give the same ``x*`` and ``dg/dmu = -F(mu)``. The +pairwise scalar ``mu`` and the vector weights here are related primitives +with different result contracts. + +Packed coefficients store the linear term as ``b = -A x_bar``, so the center +is ``x_bar = -A^{-1} b``; :func:`solve_minimax_from_coefs` handles this. +""" + +from __future__ import annotations + +import warnings +from typing import Any, Literal, NamedTuple + +import numpy as np +import numpy.typing as npt +from scipy import linalg + +from .geometry import unpack_conic + +__all__ = [ + "MethodName", + "MinimaxResult", + "solve_minimax", + "solve_minimax_from_coefs", +] + +MethodName = Literal[ + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", +] + +_DEFAULT_TOL = 1e-9 +_DEFAULT_MAX_ITER = 2000 +_DEFAULT_WEIGHT_TOL = 1e-10 +_DEFAULT_MAX_COND_STEPS = 8 +_N_BISECT = 52 # ~machine precision for double + +_NEWTON_TOL = 1e-14 +_NEWTON_MAX_ITER = 20 + +# Brentq line search constants (analogous to ellphi _DEFAULT_HYBRID_BRACKET_MAXITER) +_DEFAULT_BRENTQ_MAXITER = 28 +# Retained unused for fidelity with the ellcech source. +_BRENTQ_FAILSAFE_MAXITER = 64 +_BRENTQ_XTOL = 1e-12 +_BRENTQ_RTOL = 4.0 * np.finfo(float).eps + +# Armijo backtracking constants +_ARMIJO_BETA = 0.5 +_ARMIJO_SIGMA = 1e-4 +_ARMIJO_MAX_BACKTRACK = 10 + +_VALID_METHODS: tuple[str, ...] = ( + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", +) + +# Legacy alias +_METHOD_ALIASES: dict[str, str] = { + "fw+newton": "fw+bisect+newton", +} + + +class MinimaxResult(NamedTuple): + """Result of the minimax solver. + + Attributes: + alpha: Filtration value ``max_i f_i(circumcenter)``, a squared scale. + A numerical approximation of the exact minimax value within the + solver tolerances (see ``converged``). For an unadjusted solve + (``regularization == 0`` and ``condition_number_limit is None``) + the target is the exact problem; otherwise it is the stabilised + problem. In the pairwise case the exact value is + ``ellphi.tangency(p, q).t ** 2``. + circumcenter: Point ``x* = A(mu)^{-1} b(mu)`` for the returned + weights, computed from the unadjusted ``A(mu)`` for an unadjusted + solve and from the stabilised ``A(mu)`` otherwise. + weights: Returned dual weights ``mu`` in the simplex, shape ``(k,)``. + active_set: Weight support ``{i : weights[i] > weight_tol}``. This is + not the tight constraint set ``{i : f_i(x*) == alpha}``, which can + be strictly larger (see the module docstring). + converged: Whether the method met its stopping test for the value. + It is not a derivative certificate. + n_iter: Number of iterations performed. + method: Canonical solver method used (e.g. ``"fw+bisect"``). + metadata: Optional dict with method-specific diagnostics + (``fw_iters``, ``newton_iters``, ``hessian_cond``, ...). + """ + + alpha: float + circumcenter: np.ndarray + weights: np.ndarray + active_set: list[int] + converged: bool + n_iter: int + method: str = "fw+bisect" + metadata: dict[str, Any] | None = None + + +# --------------------------------------------------------------------------- +# Low-level helpers (shared across methods) +# --------------------------------------------------------------------------- + + +def _condition_matrix( + A: np.ndarray, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> np.ndarray: + """Optionally regularise A to improve conditioning.""" + if regularization < 0.0: + raise ValueError("regularization must be non-negative") + if condition_number_limit is not None and condition_number_limit <= 1.0: + raise ValueError("condition_number_limit must be > 1 when provided") + if max_conditioning_steps < 0: + raise ValueError("max_conditioning_steps must be non-negative") + + if regularization == 0.0 and condition_number_limit is None: + return A + + eye = np.eye(A.shape[0], dtype=A.dtype) + if condition_number_limit is None: + return A + regularization * eye + + spectral_scale = float(np.linalg.norm(A, ord=2)) + eps_floor = np.finfo(A.dtype).eps * max(1.0, spectral_scale) + reg = max(regularization, eps_floor) + A_reg = A + reg * eye + + cond = np.linalg.cond(A_reg) + if np.isfinite(cond) and cond <= condition_number_limit: + return A_reg + + # Strict cap: perform at most max_conditioning_steps escalations. + for _ in range(max_conditioning_steps): + reg *= 10.0 + A_reg = A + reg * eye + cond = np.linalg.cond(A_reg) + if np.isfinite(cond) and cond <= condition_number_limit: + return A_reg + return A_reg + + +def _cholesky_solve( + A: np.ndarray, + b: np.ndarray, + *, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, +) -> np.ndarray: + """Solve A x = b with optional conditioning safeguards.""" + A = _condition_matrix( + A, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + try: + chol = linalg.cho_factor(A, check_finite=False) + return linalg.cho_solve(chol, b, check_finite=False) + except linalg.LinAlgError: + return np.linalg.lstsq(A, b, rcond=None)[0] + + +def _exact_linear_solve(A: np.ndarray, b: np.ndarray) -> np.ndarray: + """Solve A x = b without stability regularization adjustments.""" + try: + chol = linalg.cho_factor(A, check_finite=False) + return linalg.cho_solve(chol, b, check_finite=False) + except linalg.LinAlgError: + try: + return np.linalg.solve(A, b) + except np.linalg.LinAlgError: + return np.linalg.lstsq(A, b, rcond=None)[0] + + +def _eval_f( + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[np.ndarray, np.ndarray]: + """Compute circumcenter x*(mu) and f_i(x*(mu)) for all i. + + Also note: g(mu) = sum_i mu_i f_i(x*(mu)) = np.dot(mu, f). + """ + A_mu = np.einsum("k,kij->ij", mu, matrices) + b_mu = np.einsum("k,ki->i", mu, Ax) + xstar = _cholesky_solve( + A_mu, + b_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + diff = xstar[np.newaxis, :] - centers + f = np.einsum("ki,kij,kj->k", diff, matrices, diff) + return xstar, f + + +def _exact_line_search( + s: int, + v: int, + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + gamma_max: float, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> float: + """Find gamma* in [0, gamma_max] that maximises g along the pairwise direction. + + Bisects on h(gamma) = f_s(x*(mu + gamma*(e_s - e_v))) - f_v(...) = 0. + dg/dgamma = f_s(x*(gamma)) - f_v(x*(gamma)) (positive at 0, negative at gamma_max). + """ + if gamma_max <= 0.0: + return 0.0 + + def h(gamma: float) -> float: + mu_g = mu.copy() + mu_g[s] += gamma + mu_g[v] -= gamma + _, f_g = _eval_f( + mu_g, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + return float(f_g[s] - f_g[v]) + + h0 = h(0.0) + if h0 <= 0.0: + return 0.0 # already at or past optimum in this direction + + h_max = h(gamma_max) + if h_max >= 0.0: + return gamma_max # optimum is at the boundary + + lo, hi = 0.0, gamma_max + for _ in range(_N_BISECT): + mid = 0.5 * (lo + hi) + if h(mid) > 0.0: + lo = mid + else: + hi = mid + return 0.5 * (lo + hi) + + +def _ensure_finite(value: float, label: str) -> float: + """Raise RuntimeError if *value* is NaN or Inf (ellphi pattern).""" + if not np.isfinite(value): + raise RuntimeError(f"Non-finite {label} value: {value}") + return value + + +def _brentq_line_search( + s: int, + v: int, + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + gamma_max: float, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[float, int]: + """Brentq-based line search replacing fixed 52-step bisection. + + Returns: + (gamma, n_fevals): Optimal step and number of function evaluations. + """ + if gamma_max <= 0.0: + return 0.0, 0 + + n_fevals = [0] + + def h(gamma: float) -> float: + n_fevals[0] += 1 + mu_g = mu.copy() + mu_g[s] += gamma + mu_g[v] -= gamma + _, f_g = _eval_f( + mu_g, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + return float(f_g[s] - f_g[v]) + + h0 = h(0.0) + if h0 <= 0.0: + return 0.0, n_fevals[0] + + h_max = h(gamma_max) + if h_max >= 0.0: + return gamma_max, n_fevals[0] + + try: + from scipy.optimize import brentq + + gamma = brentq( + h, + 0.0, + gamma_max, + xtol=_BRENTQ_XTOL, + rtol=_BRENTQ_RTOL, + maxiter=_DEFAULT_BRENTQ_MAXITER, + ) + return float(gamma), n_fevals[0] + except (ValueError, RuntimeError): + # Fallback to fixed bisection + lo, hi = 0.0, gamma_max + for _ in range(_N_BISECT): + mid = 0.5 * (lo + hi) + if h(mid) > 0.0: + lo = mid + else: + hi = mid + return 0.5 * (lo + hi), n_fevals[0] + + +# --------------------------------------------------------------------------- +# Per-method internal runners +# --------------------------------------------------------------------------- + + +def _run_fw_bisect( + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + mu: np.ndarray, + *, + tol: float, + max_iter: int, + weight_tol: float, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[np.ndarray, bool, int]: + """Pairwise Frank-Wolfe with exact bisection line search. + + Returns: + (mu, converged, n_iter) + """ + converged = False + n_iter = 0 + + for n_iter in range(1, max_iter + 1): + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + + s = int(np.argmax(f)) + active_mask = mu > weight_tol + f_active = np.where(active_mask, f, np.inf) + v = int(np.argmin(f_active)) + + fw_gap = float(f[s] - np.dot(mu, f)) + if fw_gap < tol: + converged = True + break + + if s == v: + converged = True + break + + gamma_max = float(mu[v]) + gamma = _exact_line_search( + s, + v, + mu, + matrices, + Ax, + centers, + gamma_max, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + + mu = mu.copy() + mu[s] += gamma + mu[v] -= gamma + mu = np.clip(mu, 0.0, None) + mu /= mu.sum() + + return mu, converged, n_iter + + +def _run_fw_brentq( + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + mu: np.ndarray, + *, + tol: float, + max_iter: int, + weight_tol: float, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[np.ndarray, bool, int, dict]: + """Pairwise Frank-Wolfe with brentq line search. + + Returns: + (mu, converged, n_iter, metadata) + """ + converged = False + n_iter = 0 + total_line_search_evals = 0 + total_fevals = 0 + + for n_iter in range(1, max_iter + 1): + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + total_fevals += 1 + + s = int(np.argmax(f)) + active_mask = mu > weight_tol + f_active = np.where(active_mask, f, np.inf) + v = int(np.argmin(f_active)) + + fw_gap = float(f[s] - np.dot(mu, f)) + if fw_gap < tol: + converged = True + break + + if s == v: + converged = True + break + + gamma_max = float(mu[v]) + gamma, ls_evals = _brentq_line_search( + s, + v, + mu, + matrices, + Ax, + centers, + gamma_max, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + total_line_search_evals += ls_evals + + mu = mu.copy() + mu[s] += gamma + mu[v] -= gamma + mu = np.clip(mu, 0.0, None) + mu /= mu.sum() + + metadata = { + "fw_iters": n_iter, + "n_fevals": total_fevals + total_line_search_evals, + "line_search_evals": total_line_search_evals, + } + return mu, converged, n_iter, metadata + + +def _hessian_g_negative( + active: list[int], + xstar: np.ndarray, + matrices: np.ndarray, + Amu_inv: np.ndarray, + centers: np.ndarray, +) -> np.ndarray: + """Negative Hessian of g on the active face (positive semidefinite). + + neg_H[l, l'] = 2 (x* - x_{i_l})^T A_{i_l} A(mu)^{-1} A_{i_{l'}} (x* - x_{i_{l'}}) + + Equivalently neg_H = 2 * Ad @ Amu_inv @ Ad.T + where Ad[l] = A_{i_l} (x* - x_{i_l}) (shape m x d). + """ + diff = xstar[np.newaxis, :] - centers[active] # (m, d) + Ad = np.einsum("lij,lj->li", matrices[active], diff) # (m, d) + return 2.0 * (Ad @ Amu_inv @ Ad.T) # (m, m) + + +def _newton_polish( + mu: np.ndarray, + active_set: list[int], + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + *, + max_iter: int = _NEWTON_MAX_ITER, + tol: float = _NEWTON_TOL, +) -> tuple[np.ndarray, int]: + """Newton polishing on the dual restricted to the current active face. + + Solves the KKT conditions r_l = f_{i_l}(x*) - f_{i_{m-1}}(x*) = 0 + using the exact (negative) Hessian of g via the reduced system: + + neg_H_r delta = r + neg_H_r[l, l'] = neg_H[l,l'] - neg_H[l, m-1] - neg_H[m-1, l'] + neg_H[m-1, m-1] + + Then mu_{i_l} += delta[l], mu_{i_{m-1}} -= sum(delta), + followed by simplex projection. + + Returns: + (mu, n_iter): Updated weights and number of Newton steps performed. + """ + m = len(active_set) + if m <= 1: + return mu, 0 + + mu = mu.copy() + n_iter = 0 + + for n_iter in range(1, max_iter + 1): + A_mu = np.einsum("k,kij->ij", mu, matrices) + b_mu = np.einsum("k,ki->i", mu, Ax) + + try: + chol = linalg.cho_factor(A_mu, check_finite=False) + xstar = linalg.cho_solve(chol, b_mu, check_finite=False) + d = A_mu.shape[0] + Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) + except linalg.LinAlgError: + break + + diff = xstar[np.newaxis, :] - centers[active_set] # (m, d) + f = np.einsum("ki,kij,kj->k", diff, matrices[active_set], diff) # (m,) + + # Residual: r_l = f_{i_l} - f_{i_{m-1}} + r = f[:-1] - f[-1] # (m-1,) + if float(np.max(np.abs(r))) < tol: + break + + neg_H = _hessian_g_negative( + active_set, xstar, matrices, Amu_inv, centers + ) # (m, m) + + # Reduced system (eliminate last variable via sum=1 constraint) + neg_H_r = ( + neg_H[:-1, :-1] - neg_H[:-1, -1:] - neg_H[-1:, :-1] + neg_H[-1, -1] + ) # (m-1, m-1) + + try: + delta = np.linalg.solve(neg_H_r, r) + except np.linalg.LinAlgError: + break + + mu_new = mu.copy() + for pos, idx in enumerate(active_set[:-1]): + mu_new[idx] += delta[pos] + mu_new[active_set[-1]] -= float(delta.sum()) + + # Project back to simplex + mu_new = np.clip(mu_new, 0.0, None) + s = mu_new.sum() + if s <= 0.0: + break + mu_new /= s + mu = mu_new + + return mu, n_iter + + +def _damped_newton_polish( + mu: np.ndarray, + active_set: list[int], + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + *, + max_iter: int = _NEWTON_MAX_ITER, + tol: float = _NEWTON_TOL, +) -> tuple[np.ndarray, int, dict]: + """Newton polishing with Armijo backtracking and conditioning safeguards. + + Like ``_newton_polish`` but adds: + - Condition number check on the reduced Hessian (regularize if > 1e12) + - Armijo backtracking line search on the Newton step + - ``_ensure_finite`` guards against NaN propagation + + Returns: + (mu, n_iter, metadata) + """ + m = len(active_set) + if m <= 1: + return mu, 0, {"newton_iters": 0, "hessian_cond": 0.0} + + mu = mu.copy() + n_iter = 0 + max_hessian_cond = 0.0 + + for n_iter in range(1, max_iter + 1): + A_mu = np.einsum("k,kij->ij", mu, matrices) + b_mu = np.einsum("k,ki->i", mu, Ax) + + try: + chol = linalg.cho_factor(A_mu, check_finite=False) + xstar = linalg.cho_solve(chol, b_mu, check_finite=False) + d = A_mu.shape[0] + Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) + except linalg.LinAlgError: + break + + diff = xstar[np.newaxis, :] - centers[active_set] + f = np.einsum("ki,kij,kj->k", diff, matrices[active_set], diff) + + # Residual + r = f[:-1] - f[-1] + try: + _ensure_finite(float(np.max(np.abs(r))), "Newton residual") + except RuntimeError: + break + if float(np.max(np.abs(r))) < tol: + break + + neg_H = _hessian_g_negative(active_set, xstar, matrices, Amu_inv, centers) + + neg_H_r = neg_H[:-1, :-1] - neg_H[:-1, -1:] - neg_H[-1:, :-1] + neg_H[-1, -1] + + # Conditioning check + hess_cond = float(np.linalg.cond(neg_H_r)) + max_hessian_cond = max(max_hessian_cond, hess_cond) + if hess_cond > 1e12: + # Diagonal regularization + reg = float(np.trace(neg_H_r)) / neg_H_r.shape[0] * 1e-10 + reg = max(reg, 1e-14) + neg_H_r = neg_H_r + reg * np.eye(neg_H_r.shape[0]) + + try: + delta = np.linalg.solve(neg_H_r, r) + except np.linalg.LinAlgError: + break + + if not np.all(np.isfinite(delta)): + break + + # Current objective: g(mu) = dot(mu, f_full) + _, f_full = _eval_f( + mu, + matrices, + Ax, + centers, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=0, + ) + g_current = float(np.dot(mu, f_full)) + + # Armijo backtracking + step = 1.0 + accepted = False + for _ in range(_ARMIJO_MAX_BACKTRACK): + mu_trial = mu.copy() + for pos, idx in enumerate(active_set[:-1]): + mu_trial[idx] += step * delta[pos] + mu_trial[active_set[-1]] -= step * float(delta.sum()) + + # Project to simplex + mu_trial = np.clip(mu_trial, 0.0, None) + s = mu_trial.sum() + if s <= 0.0: + step *= _ARMIJO_BETA + continue + mu_trial /= s + + _, f_trial = _eval_f( + mu_trial, + matrices, + Ax, + centers, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=0, + ) + g_trial = float(np.dot(mu_trial, f_trial)) + + # Armijo sufficient increase (maximizing g) + if g_trial >= g_current + _ARMIJO_SIGMA * step * float(r @ delta): + mu = mu_trial + accepted = True + break + step *= _ARMIJO_BETA + + if not accepted: + # Accept full step anyway (like undamped Newton) + mu_new = mu.copy() + for pos, idx in enumerate(active_set[:-1]): + mu_new[idx] += delta[pos] + mu_new[active_set[-1]] -= float(delta.sum()) + mu_new = np.clip(mu_new, 0.0, None) + s = mu_new.sum() + if s <= 0.0: + break + mu_new /= s + mu = mu_new + + metadata = { + "newton_iters": n_iter, + "hessian_cond": max_hessian_cond, + } + return mu, n_iter, metadata + + +def _simplex_residual(mu: npt.NDArray[np.float64]) -> float: + """Equality constraint ``sum(mu) - 1`` for SLSQP.""" + return float(mu.sum() - 1.0) + + +def _run_scipy_slsqp( + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + k: int, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[np.ndarray, bool, int]: + """Maximize g(mu) over the simplex using scipy SLSQP. + + Returns: + (mu, converged, n_iter) + """ + from scipy.optimize import minimize + + n_eval = [0] + + def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: + n_eval[0] += 1 + _, f = _eval_f( + mu, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + # g(mu) = dot(mu, f); gradient dg/dmu_i = f_i(x*(mu)) + return -float(np.dot(mu, f)), -f + + x0 = np.full(k, 1.0 / k) + bounds = [(0.0, None)] * k + + res = minimize( + neg_g_and_grad, + x0, + jac=True, + method="SLSQP", + bounds=bounds, + constraints={"type": "eq", "fun": _simplex_residual}, + options={"ftol": 1e-14, "maxiter": 500}, + ) + + mu = np.clip(res.x, 0.0, None) + s = mu.sum() + if s > 0.0: + mu /= s + + return mu, bool(res.success), n_eval[0] + + +# --------------------------------------------------------------------------- +# Public API +# --------------------------------------------------------------------------- + + +def _check_newton_convergence( + mu: np.ndarray, + active_set_fw: list[int], + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + converged: bool, + newton_tol: float, +) -> bool: + """Recheck convergence after Newton polishing.""" + if len(active_set_fw) <= 1: + return converged + try: + A_mu = np.einsum("k,kij->ij", mu, matrices) + b_mu = np.einsum("k,ki->i", mu, Ax) + chol = linalg.cho_factor(A_mu, check_finite=False) + xstar_check = linalg.cho_solve(chol, b_mu, check_finite=False) + d_check = xstar_check[np.newaxis, :] - centers[active_set_fw] + f_check = np.einsum("ki,kij,kj->k", d_check, matrices[active_set_fw], d_check) + r_check = f_check[:-1] - f_check[-1] + return converged and float(np.max(np.abs(r_check))) < newton_tol * 1e4 + except linalg.LinAlgError: + return converged + + +def solve_minimax( + matrices: np.ndarray, + centers: np.ndarray, + *, + method: MethodName | str = "fw+bisect", + tol: float = _DEFAULT_TOL, + max_iter: int = _DEFAULT_MAX_ITER, + weight_tol: float = _DEFAULT_WEIGHT_TOL, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, + newton_tol: float = _NEWTON_TOL, + newton_max_iter: int = _NEWTON_MAX_ITER, +) -> MinimaxResult: + """Compute a numerical approximation of the filtration value. + + The mathematical target is ``alpha = max_{mu in Delta} g(mu)``. The + returned value and circumcenter are finite-iteration approximations + within the solver tolerances; check ``converged``. For an unadjusted + solve (``regularization == 0`` and ``condition_number_limit is None``) + the target is the exact problem. Otherwise ``A(mu)`` is stabilised + (``condition_number_limit`` alone already applies at least a + machine-epsilon diagonal shift) and the outputs approximate the + stabilised problem. + + Seven solver back-ends are available via ``method``: + + * ``"fw+bisect"`` (default): Pairwise FW with 52-step bisection line search. + * ``"fw+brentq"``: Pairwise FW with adaptive brentq line search. + * ``"fw+bisect+newton"``: FW(bisect) warm-start + Newton polishing. + * ``"fw+brentq+newton"``: FW(brentq) warm-start + damped Newton polishing. + * ``"fw+bisect+damped-newton"``: FW(bisect) + Armijo-damped Newton. + * ``"scipy-slsqp"``: Direct SLSQP solve via scipy. + * ``"newton-cold"``: Newton from uniform mu=1/k (stability baseline). + + The legacy name ``"fw+newton"`` is accepted as an alias for + ``"fw+bisect+newton"`` with a deprecation warning. + + Args: + matrices: SPD matrices ``A_i``, shape ``(k, d, d)``, or ``(d, d)`` for + a single vertex. + centers: Centers ``x_i``, shape ``(k, d)``, or ``(d,)`` for a single + vertex. + method: One of the seven canonical method names above. + tol: Frank-Wolfe gap tolerance for the FW-based methods. + max_iter: Maximum number of Frank-Wolfe iterations. + weight_tol: Threshold defining the weight support ``active_set``. It + also selects the face used by Newton polishing. + regularization: Non-negative diagonal shift applied to ``A(mu)`` in + Frank-Wolfe evaluations and line searches, SLSQP evaluations, and + the final evaluation. Newton-polishing solves use the unshifted + ``A(mu)``. + condition_number_limit: Optional target for ``cond(A(mu))``. If the + target is exceeded, the diagonal shift is escalated by factors of + 10 for at most ``max_conditioning_steps`` attempts; the target is + not guaranteed after the cap. + max_conditioning_steps: Maximum number of attempted conditioning + escalations. + newton_tol: Residual tolerance for Newton polishing. + newton_max_iter: Maximum number of Newton steps. + + Returns: + MinimaxResult with ``.method`` recording the canonical solver name + and ``.metadata`` containing method-specific diagnostics. ``alpha`` + and ``circumcenter`` approximate the exact minimax value and + circumcenter for an unadjusted solve (``regularization == 0`` and + ``condition_number_limit is None``), and the stabilised problem + otherwise; in the pairwise case the exact value is + ``ellphi.tangency(p, q).t ** 2``. For ``k = 1`` the result is the + trivial ``alpha = 0`` at the center. + + Raises: + ValueError: For an unknown method, an empty simplex or invalid + conditioning parameters. + """ + # Handle legacy alias + if method in _METHOD_ALIASES: + canonical = _METHOD_ALIASES[method] + warnings.warn( + f"Method {method!r} is deprecated, use {canonical!r} instead.", + DeprecationWarning, + stacklevel=2, + ) + method = canonical + + if method not in _VALID_METHODS: + raise ValueError(f"Unknown method {method!r}. Valid methods: {_VALID_METHODS}") + + matrices = np.asarray(matrices, dtype=float) + centers = np.asarray(centers, dtype=float) + if regularization < 0.0: + raise ValueError("regularization must be non-negative") + if condition_number_limit is not None and condition_number_limit <= 1.0: + raise ValueError("condition_number_limit must be > 1 when provided") + if max_conditioning_steps < 0: + raise ValueError("max_conditioning_steps must be non-negative") + + # Accept single-simplex input (2D matrix, 1D center) + if matrices.ndim == 2: + matrices = matrices[np.newaxis] + centers = centers[np.newaxis] + + k, d = centers.shape + + if k == 0: + raise ValueError("simplex must contain at least one vertex (k=0 given)") + + # --- Trivial case: single point --- + if k == 1: + return MinimaxResult( + alpha=0.0, + circumcenter=centers[0].copy(), + weights=np.array([1.0]), + active_set=[0], + converged=True, + n_iter=0, + method=method, + ) + + # Precompute A_i x_bar_i (shape: k x d) + Ax = np.einsum("kij,kj->ki", matrices, centers) + + # Uniform initialisation for FW-based methods + mu_init = np.full(k, 1.0 / k) + + _fw_kwargs: dict[str, Any] = dict( + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + + metadata: dict[str, Any] = {} + + # --- Dispatch --- + if method == "fw+bisect": + mu, converged, n_iter = _run_fw_bisect( + matrices, Ax, centers, mu_init, **_fw_kwargs + ) + metadata["fw_iters"] = n_iter + + elif method == "fw+brentq": + mu, converged, n_iter, meta_fw = _run_fw_brentq( + matrices, Ax, centers, mu_init, **_fw_kwargs + ) + metadata.update(meta_fw) + + elif method == "fw+bisect+newton": + mu, converged, n_iter_fw = _run_fw_bisect( + matrices, Ax, centers, mu_init, **_fw_kwargs + ) + active_set_fw = [i for i in range(k) if mu[i] > weight_tol] + mu, n_iter_newton = _newton_polish( + mu, + active_set_fw, + matrices, + Ax, + centers, + max_iter=newton_max_iter, + tol=newton_tol, + ) + n_iter = n_iter_fw + n_iter_newton + converged = _check_newton_convergence( + mu, + active_set_fw, + matrices, + Ax, + centers, + converged, + newton_tol, + ) + metadata["fw_iters"] = n_iter_fw + metadata["newton_iters"] = n_iter_newton + + elif method == "fw+brentq+newton": + mu, converged, n_iter_fw, meta_fw = _run_fw_brentq( + matrices, Ax, centers, mu_init, **_fw_kwargs + ) + active_set_fw = [i for i in range(k) if mu[i] > weight_tol] + mu, n_iter_newton, meta_newton = _damped_newton_polish( + mu, + active_set_fw, + matrices, + Ax, + centers, + max_iter=newton_max_iter, + tol=newton_tol, + ) + n_iter = n_iter_fw + n_iter_newton + converged = _check_newton_convergence( + mu, + active_set_fw, + matrices, + Ax, + centers, + converged, + newton_tol, + ) + metadata.update(meta_fw) + metadata.update(meta_newton) + + elif method == "fw+bisect+damped-newton": + mu, converged, n_iter_fw = _run_fw_bisect( + matrices, Ax, centers, mu_init, **_fw_kwargs + ) + active_set_fw = [i for i in range(k) if mu[i] > weight_tol] + mu, n_iter_newton, meta_newton = _damped_newton_polish( + mu, + active_set_fw, + matrices, + Ax, + centers, + max_iter=newton_max_iter, + tol=newton_tol, + ) + n_iter = n_iter_fw + n_iter_newton + converged = _check_newton_convergence( + mu, + active_set_fw, + matrices, + Ax, + centers, + converged, + newton_tol, + ) + metadata["fw_iters"] = n_iter_fw + metadata.update(meta_newton) + + elif method == "newton-cold": + # Newton from uniform start (no FW warm-up) + active_set_cold = list(range(k)) + mu, n_iter_newton, meta_newton = _damped_newton_polish( + mu_init.copy(), + active_set_cold, + matrices, + Ax, + centers, + max_iter=newton_max_iter, + tol=newton_tol, + ) + n_iter = n_iter_newton + converged = _check_newton_convergence( + mu, + active_set_cold, + matrices, + Ax, + centers, + True, + newton_tol, + ) + metadata.update(meta_newton) + + elif method == "scipy-slsqp": + mu, converged, n_iter = _run_scipy_slsqp( + matrices, + Ax, + centers, + k, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + metadata["n_fevals"] = n_iter + + # --- Final evaluation --- + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + alpha = float(np.max(f)) + if not (np.isfinite(alpha) and np.all(np.isfinite(xstar))): + converged = False + active_set = [i for i in range(k) if mu[i] > weight_tol] + + return MinimaxResult( + alpha=alpha, + circumcenter=xstar, + weights=mu, + active_set=active_set, + converged=converged, + n_iter=n_iter, + method=method, + metadata=metadata or None, + ) + + +def solve_minimax_from_coefs( + coefs: np.ndarray, + **kwargs: Any, +) -> MinimaxResult: + """Convenience wrapper: accept ellphi packed conic coefficient vectors. + + Converts ellphi's packed representation (A, b_ellphi, c) to (A_i, x_bar_i) + and calls solve_minimax. + + Sign convention: + ellphi stores ``b_ellphi = -A x_bar`` (linear term of + ``x^T A x + 2 b^T x + c``), so ``x_bar = -A^{-1} b_ellphi``. + + Value correspondence: + In the pairwise case ``result.alpha`` approximates + ``ellphi.tangency(coefs[0], coefs[1]).t ** 2`` (exactly equal in the + mathematical problem; numerically within solver tolerances for an + unadjusted solve, i.e. ``regularization == 0`` and + ``condition_number_limit is None``). + + Args: + coefs: Packed conic coefficient array, shape (k, m) or (m,) for k=1. + **kwargs: Forwarded to solve_minimax (method, tol, max_iter, weight_tol, + regularization, condition_number_limit, max_conditioning_steps, + newton_tol, newton_max_iter). + + Returns: + MinimaxResult. + """ + coefs = np.asarray(coefs, dtype=float) + if coefs.ndim == 1: + coefs = coefs[np.newaxis] + + A_arr, b_arr, _ = unpack_conic(coefs) # (k,d,d), (k,d), (k,) + + # x_bar_i = -A_i^{-1} b_i (ellphi sign convention: b = -A x_bar) + k = A_arr.shape[0] + centers = np.empty_like(b_arr) + for i in range(k): + centers[i] = _exact_linear_solve(A_arr[i], -b_arr[i]) + + return solve_minimax(A_arr, centers, **kwargs) diff --git a/src/ellphi/minimax.pyi b/src/ellphi/minimax.pyi new file mode 100644 index 0000000..3668751 --- /dev/null +++ b/src/ellphi/minimax.pyi @@ -0,0 +1,49 @@ +from typing import Any, Literal, NamedTuple, TypeAlias + +import numpy as np + +__all__ = [ + "MethodName", + "MinimaxResult", + "solve_minimax", + "solve_minimax_from_coefs", +] + +MethodName: TypeAlias = Literal[ + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", +] + +class MinimaxResult(NamedTuple): + alpha: float + circumcenter: np.ndarray + weights: np.ndarray + active_set: list[int] + converged: bool + n_iter: int + method: str = "fw+bisect" + metadata: dict[str, Any] | None = None + +def solve_minimax( + matrices: np.ndarray, + centers: np.ndarray, + *, + method: MethodName | str = "fw+bisect", + tol: float = 1e-09, + max_iter: int = 2000, + weight_tol: float = 1e-10, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = 8, + newton_tol: float = 1e-14, + newton_max_iter: int = 20, +) -> MinimaxResult: ... +def solve_minimax_from_coefs( + coefs: np.ndarray, + **kwargs: Any, +) -> MinimaxResult: ... diff --git a/src/ellphi/minimax_grad.py b/src/ellphi/minimax_grad.py new file mode 100644 index 0000000..386f8ad --- /dev/null +++ b/src/ellphi/minimax_grad.py @@ -0,0 +1,156 @@ +"""Gradient of the many-body minimax filtration value (provisional). + +Provenance +---------- +Adapted from uda-lab/ellcech ``src/ellphi_alpha/minimax_grad.py`` at commit +82d13e3e174f4903cdcd6adcee1f469348361c91, by Tomoki Uda (the author of +EllPHi). The only later change to that file on ellcech ``main`` (commit +ebe63a42060ac6420ad42d90b3ffe942969d54ec) is documentation-only. This +docstring is written for EllPHi rather than copied from either revision: it +adopts the ebe63a4 remark that zero weights give zero gradient blocks, but +not its characterization of differentiability. The code is unchanged. +Distributed as part of EllPHi under its MIT license. The rights question for +the ellcech source is tracked in uda-lab/project-ellphi#26. + +The module name and the public names exported from ``ellphi`` are +provisional and may change. + +Formula +------- +Given a :class:`~ellphi.minimax.MinimaxResult` with weights ``mu`` and +circumcenter ``x*``, the envelope theorem applied to the dual gives + + d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*) + d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*) + +with centers ``xbar_i`` and matrices ``A_i`` treated as independent +parameters. For ``k = 2`` these are the pairwise gradients of ``t ** 2``. +Indices with zero weight get zero blocks; a zero weight alone is not +evidence that ``alpha`` fails to be differentiable. + +Hypotheses +---------- +The returned arrays are the formula evaluated at the solver output. They +approximate the true gradient of ``alpha`` only under the following +hypotheses: + +* the input configuration is non-degenerate; +* at least two indices are active; +* the returned weights are close to the optimal multipliers and are + supported on the active set; +* the weighted linear solve for ``x*`` is exact. A floating-point solve + leaves an additional residual. + +"Active" in these hypotheses refers to the exact optimization problem, not +to the thresholded ``result.active_set``. + +``MinimaxResult.converged`` and the value of ``alpha`` do not certify these +hypotheses. The formula scales each block by ``result.weights[i]`` directly; +it does not use ``result.active_set`` or ``weight_tol``. +""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import Sequence + +import numpy as np + +from .minimax import MinimaxResult + +__all__ = [ + "GradientResult", + "compute_gradient", +] + + +@dataclass +class GradientResult: + """Gradient of ``alpha`` with respect to centers and metric matrices. + + Attributes: + d_xbar: Gradients with respect to the centers ``xbar_i``, one array + of shape ``(d,)`` per vertex. + d_A: Gradients with respect to the matrices ``A_i``, one symmetric + array of shape ``(d, d)`` per vertex. + alpha: The filtration value from the forward pass. + circumcenter: The circumcenter ``x*`` from the forward pass. + weights: The weights ``mu`` from the forward pass. + """ + + d_xbar: list[np.ndarray] + d_A: list[np.ndarray] + alpha: float + circumcenter: np.ndarray + weights: np.ndarray + + +def compute_gradient( + result: MinimaxResult, + centers: np.ndarray | Sequence[np.ndarray], + matrices: np.ndarray | Sequence[np.ndarray], +) -> GradientResult: + """Evaluate the envelope-theorem gradient of ``alpha`` at a solver result. + + Computes ``d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*)`` and + ``d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*)``. See the module + docstring for the hypotheses under which these approximate the true + gradient. + + Args: + result: A MinimaxResult from :func:`ellphi.minimax.solve_minimax` + computed for the same ``centers`` and ``matrices``. + centers: Centers ``xbar_i``, shape ``(k, d)``. + matrices: SPD matrices ``A_i``, shape ``(k, d, d)``. + + Returns: + GradientResult with ``d_xbar`` and ``d_A`` lists of length ``k``. + + Raises: + ValueError: If the shapes of ``centers``, ``matrices`` and + ``result.weights`` are inconsistent. + """ + centers = np.asarray(centers, dtype=float) + matrices = np.asarray(matrices, dtype=float) + + if centers.ndim == 1: + centers = centers[np.newaxis] + matrices = matrices[np.newaxis] + + k, d = centers.shape + if matrices.shape != (k, d, d): + raise ValueError( + f"matrices shape {matrices.shape} inconsistent with " + f"centers shape {centers.shape}" + ) + if len(result.weights) != k: + raise ValueError( + f"result.weights length {len(result.weights)} does not match k={k}" + ) + + xstar = result.circumcenter # shape (d,) + mu = result.weights # shape (k,) + + d_xbar = [] + d_A = [] + + for i in range(k): + diff = centers[i] - xstar # xbar_i - x*, shape (d,) + mu_i = float(mu[i]) + + # d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*) + grad_xbar_i = 2.0 * mu_i * (matrices[i] @ diff) # shape (d,) + + # d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*) + grad_A_i = mu_i * np.outer(diff, diff) # shape (d, d) + + d_xbar.append(grad_xbar_i) + d_A.append(grad_A_i) + + return GradientResult( + d_xbar=d_xbar, + d_A=d_A, + alpha=result.alpha, + circumcenter=xstar.copy(), + weights=mu.copy(), + ) diff --git a/src/ellphi/minimax_grad.pyi b/src/ellphi/minimax_grad.pyi new file mode 100644 index 0000000..393971f --- /dev/null +++ b/src/ellphi/minimax_grad.pyi @@ -0,0 +1,25 @@ +from dataclasses import dataclass +from typing import Sequence + +import numpy as np + +from .minimax import MinimaxResult + +__all__ = [ + "GradientResult", + "compute_gradient", +] + +@dataclass +class GradientResult: + d_xbar: list[np.ndarray] + d_A: list[np.ndarray] + alpha: float + circumcenter: np.ndarray + weights: np.ndarray + +def compute_gradient( + result: MinimaxResult, + centers: np.ndarray | Sequence[np.ndarray], + matrices: np.ndarray | Sequence[np.ndarray], +) -> GradientResult: ... diff --git a/stubtest-allowlist.txt b/stubtest-allowlist.txt index 58954b0..9a3f320 100644 --- a/stubtest-allowlist.txt +++ b/stubtest-allowlist.txt @@ -1 +1,2 @@ ellphi._solver_python.MethodName +ellphi.minimax.MethodName diff --git a/tests/factories.py b/tests/factories.py index 462759a..e8d860d 100644 --- a/tests/factories.py +++ b/tests/factories.py @@ -47,3 +47,23 @@ def random_cloud( coefs = coef_from_cov(means, covs) dummy_nbd = np.empty((n_ellipses, 0), dtype=int) return EllipseCloud(coef=coefs, mean=means, cov=covs, k=0, nbd=dummy_nbd) + + +def random_simplex( + k: int, + d: int, + *, + rng: np.random.Generator, + cond_bound: float = 10.0, +) -> tuple[NDArray[np.float64], NDArray[np.float64]]: + """Random centers and SPD matrices with ``cond(A_i) <= cond_bound``. + + Same sampling as ellcech's ``benchmarks.make_random_simplex``. + """ + centers = rng.standard_normal((k, d)) + matrices = np.empty((k, d, d)) + for i in range(k): + U = np.linalg.qr(rng.standard_normal((d, d)))[0] + eigvals = rng.uniform(1.0, cond_bound, size=d) + matrices[i] = U @ np.diag(eigvals) @ U.T + return matrices, centers diff --git a/tests/test_minimax.py b/tests/test_minimax.py new file mode 100644 index 0000000..45ec49b --- /dev/null +++ b/tests/test_minimax.py @@ -0,0 +1,410 @@ +"""Tests for the many-body minimax solver. + +Adapted from uda-lab/ellcech ``tests/test_minimax.py`` at commit +82d13e3e174f4903cdcd6adcee1f469348361c91. + +Key validation: + For |σ| = 2, alpha(σ) must equal ellphi.tangency(p, q).t ** 2. + This cross-validates the Frank-Wolfe solver against ellphi's 1D root-finding, + which is the established reference implementation for the pairwise case. +""" + +from typing import get_args + +import numpy as np +import pytest + +import ellphi +import ellphi.minimax as minimax_mod +from ellphi.geometry import unpack_conic +from ellphi.minimax import solve_minimax, solve_minimax_from_coefs + +from .factories import random_coef_pair + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_spd(rng, d): + """Return a random d×d SPD matrix.""" + L = rng.standard_normal((d, d)) + return L @ L.T + np.eye(d) * 0.5 + + +def _pairwise_alpha_ellphi(pcoef, qcoef): + """Ground truth: α({i,j}) = t² from ellphi.""" + return ellphi.tangency(pcoef, qcoef).t ** 2 + + +# --------------------------------------------------------------------------- +# Trivial cases +# --------------------------------------------------------------------------- + + +class TestTrivialCases: + def test_empty_simplex_raises(self): + with pytest.raises(ValueError, match="k=0"): + solve_minimax( + np.zeros((0, 2, 2)), + np.zeros((0, 2)), + ) + + def test_single_point_alpha_zero(self): + A = np.eye(2) + x = np.array([1.0, 2.0]) + res = solve_minimax(A[np.newaxis], x[np.newaxis]) + assert res.alpha == pytest.approx(0.0, abs=1e-12) + np.testing.assert_allclose(res.circumcenter, x) + assert res.converged + assert res.n_iter == 0 + + def test_single_point_3d(self): + rng = np.random.default_rng(0) + A = _make_spd(rng, 3) + x = rng.standard_normal(3) + res = solve_minimax(A[np.newaxis], x[np.newaxis]) + assert res.alpha == pytest.approx(0.0, abs=1e-12) + + +# --------------------------------------------------------------------------- +# Isotropic (A_i = I) special cases +# --------------------------------------------------------------------------- + + +class TestIsotropic: + def test_two_points_midpoint(self): + """With A_i = I, x* is the midpoint of two equidistant points.""" + x0 = np.array([-1.0, 0.0]) + x1 = np.array([+1.0, 0.0]) + A = np.eye(2)[np.newaxis].repeat(2, axis=0) + centers = np.stack([x0, x1]) + res = solve_minimax(A, centers) + assert res.alpha == pytest.approx(1.0, rel=1e-6) + np.testing.assert_allclose(res.circumcenter, [0.0, 0.0], atol=1e-6) + assert res.converged + + def test_two_points_alpha_is_half_sq_distance(self): + """For A=I, α({i,j}) = ||x̄_i - x̄_j||² / 4 (midpoint equidistant).""" + rng = np.random.default_rng(42) + x0, x1 = rng.standard_normal((2, 3)) + A = np.eye(3)[np.newaxis].repeat(2, axis=0) + centers = np.stack([x0, x1]) + res = solve_minimax(A, centers) + expected = np.sum((x0 - x1) ** 2) / 4.0 + assert res.alpha == pytest.approx(expected, rel=1e-6) + + def test_three_points_circumcenter_equidistant(self): + """With A_i = I, x* is the circumcenter (equidistant from all points).""" + # Equilateral triangle + c = 2.0 * np.pi / 3.0 + x0 = np.array([1.0, 0.0]) + x1 = np.array([np.cos(c), np.sin(c)]) + x2 = np.array([np.cos(2 * c), np.sin(2 * c)]) + A = np.eye(2)[np.newaxis].repeat(3, axis=0) + centers = np.stack([x0, x1, x2]) + res = solve_minimax(A, centers, tol=1e-10) + # All f_i should be equal + diff = res.circumcenter[np.newaxis] - centers + f = np.einsum("ki,kij,kj->k", diff, A, diff) + assert np.max(f) - np.min(f) == pytest.approx(0.0, abs=1e-6) + assert res.converged + + +# --------------------------------------------------------------------------- +# Cross-validation with ellphi (pairwise case |σ| = 2) +# --------------------------------------------------------------------------- + + +class TestCrossValidationEllphi: + """For |σ| = 2, alpha must match ellphi.tangency(p, q).t**2.""" + + @pytest.mark.parametrize("seed", [0, 1, 2, 7, 42]) + def test_pairwise_random_2d(self, seed): + rng = np.random.default_rng(seed) + x0, x1 = rng.standard_normal((2, 2)) + cov0 = _make_spd(rng, 2) + cov1 = _make_spd(rng, 2) + pcoef = ellphi.coef_from_cov(x0, cov0)[0] + qcoef = ellphi.coef_from_cov(x1, cov1)[0] + coefs = np.stack([pcoef, qcoef]) + + res = solve_minimax_from_coefs(coefs, tol=1e-10) + expected = _pairwise_alpha_ellphi(pcoef, qcoef) + + assert res.alpha == pytest.approx( + expected, rel=1e-5 + ), f"seed={seed}: alpha={res.alpha:.8f}, expected={expected:.8f}" + assert res.converged, f"seed={seed}: did not converge in {res.n_iter} iters" + + @pytest.mark.parametrize("seed", [0, 1, 5]) + def test_pairwise_random_3d(self, seed): + rng = np.random.default_rng(seed + 100) + x0, x1 = rng.standard_normal((2, 3)) + cov0 = _make_spd(rng, 3) + cov1 = _make_spd(rng, 3) + pcoef = ellphi.coef_from_cov(x0, cov0)[0] + qcoef = ellphi.coef_from_cov(x1, cov1)[0] + coefs = np.stack([pcoef, qcoef]) + + res = solve_minimax_from_coefs(coefs, tol=1e-10) + expected = _pairwise_alpha_ellphi(pcoef, qcoef) + + assert res.alpha == pytest.approx( + expected, rel=1e-5 + ), f"seed={seed}: alpha={res.alpha:.8f}, expected={expected:.8f}" + + def test_pairwise_identical_ellipses(self): + """Two identical ellipses: α = 0, x* = center.""" + x = np.array([1.0, 2.0]) + cov = np.diag([0.5, 2.0]) + coef = ellphi.coef_from_cov(x, cov)[0] + coefs = np.stack([coef, coef]) + res = solve_minimax_from_coefs(coefs, tol=1e-10) + assert res.alpha == pytest.approx(0.0, abs=1e-7) + np.testing.assert_allclose(res.circumcenter, x, atol=1e-6) + + def test_pairwise_tangent_point_location(self): + """The circumcenter x* should satisfy f_i(x*) = f_j(x*) = alpha.""" + rng = np.random.default_rng(99) + x0, x1 = rng.standard_normal((2, 2)) + cov0 = _make_spd(rng, 2) + cov1 = _make_spd(rng, 2) + pcoef = ellphi.coef_from_cov(x0, cov0)[0] + qcoef = ellphi.coef_from_cov(x1, cov1)[0] + coefs = np.stack([pcoef, qcoef]) + + A_arr, b_arr, _ = unpack_conic(coefs) + centers = np.stack([-np.linalg.solve(A_arr[i], b_arr[i]) for i in range(2)]) + + res = solve_minimax(A_arr, centers, tol=1e-12) + xstar = res.circumcenter + diff = xstar[np.newaxis] - centers + f = np.einsum("ki,kij,kj->k", diff, A_arr, diff) + + assert f[0] == pytest.approx(f[1], rel=1e-5) + assert f[0] == pytest.approx(res.alpha, rel=1e-5) + + +# --------------------------------------------------------------------------- +# Higher-dimensional simplex (|σ| ≥ 3) +# --------------------------------------------------------------------------- + + +class TestHigherOrder: + def test_triangle_active_set(self): + """For a centered equilateral triangle, all 3 weights should be active.""" + c = 2.0 * np.pi / 3.0 + pts = np.array( + [ + [1.0, 0.0], + [np.cos(c), np.sin(c)], + [np.cos(2 * c), np.sin(2 * c)], + ] + ) + A = np.eye(2)[np.newaxis].repeat(3, axis=0) + res = solve_minimax(A, pts, tol=1e-10) + assert len(res.active_set) == 3 + assert res.converged + + def test_degenerate_triangle_reduces_to_edge(self): + """If one point is much closer, its weight should be near zero (inactive).""" + # x2 is very close to x* of {x0, x1}, so active set should be {0, 1} + pts = np.array([[0.0, 0.0], [2.0, 0.0], [1.0, 1e-6]]) + A = np.eye(2)[np.newaxis].repeat(3, axis=0) + res = solve_minimax(A, pts, tol=1e-8) + # alpha should be close to alpha({0, 1}) = 1.0 + assert res.alpha == pytest.approx(1.0, rel=1e-3) + + @pytest.mark.parametrize("k,d", [(3, 2), (4, 3), (5, 4)]) + def test_random_simplex_convergence(self, k, d): + """Frank-Wolfe should converge for random k-simplex in R^d.""" + rng = np.random.default_rng(k * 100 + d) + centers = rng.standard_normal((k, d)) + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + res = solve_minimax(matrices, centers, tol=1e-8, max_iter=5000) + assert res.converged, f"k={k}, d={d}: did not converge in {res.n_iter} iters" + assert res.alpha >= 0.0 + assert len(res.active_set) >= 1 + + +# --------------------------------------------------------------------------- +# Numerical stability controls (Gap F) +# --------------------------------------------------------------------------- + + +class TestNumericalStabilityControls: + def test_explicit_default_controls_match_previous_behaviour(self): + rng = np.random.default_rng(321) + centers = rng.standard_normal((4, 3)) + matrices = np.stack([_make_spd(rng, 3) for _ in range(4)]) + + baseline = solve_minimax(matrices, centers, tol=1e-10) + with_explicit_defaults = solve_minimax( + matrices, + centers, + tol=1e-10, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert with_explicit_defaults.alpha == pytest.approx( + baseline.alpha, rel=1e-12, abs=1e-12 + ) + np.testing.assert_allclose( + with_explicit_defaults.circumcenter, + baseline.circumcenter, + atol=1e-12, + rtol=1e-12, + ) + np.testing.assert_allclose( + with_explicit_defaults.weights, + baseline.weights, + atol=1e-12, + rtol=1e-12, + ) + + def test_regularization_and_conditioning_produce_finite_solution(self): + matrices = np.array( + [ + [[1e-12, 0.0], [0.0, 1.0]], + [[1e12, 0.0], [0.0, 1.0]], + [[1.0, 0.0], [0.0, 1e-12]], + ] + ) + centers = np.array( + [ + [0.0, 0.0], + [1.0, 0.0], + [0.5, 1.0], + ] + ) + + res = solve_minimax( + matrices, + centers, + regularization=1e-8, + condition_number_limit=1e8, + max_conditioning_steps=4, + tol=1e-9, + max_iter=4000, + ) + assert np.isfinite(res.alpha) + assert np.all(np.isfinite(res.circumcenter)) + assert np.all(np.isfinite(res.weights)) + assert np.sum(res.weights) == pytest.approx(1.0, abs=1e-8) + + def test_stability_control_parameter_validation(self): + A = np.eye(2)[np.newaxis].repeat(2, axis=0) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + with pytest.raises(ValueError): + solve_minimax(A, centers, regularization=-1.0) + with pytest.raises(ValueError): + solve_minimax(A, centers, condition_number_limit=1.0) + with pytest.raises(ValueError): + solve_minimax(A, centers, max_conditioning_steps=-1) + + def test_conditioning_steps_cap_is_strict(self): + A = np.diag([1e-12, 1.0]) + eye = np.eye(2) + limited0 = minimax_mod._condition_matrix( + A, + regularization=1e-6, + condition_number_limit=2.0, + max_conditioning_steps=0, + ) + limited1 = minimax_mod._condition_matrix( + A, + regularization=1e-6, + condition_number_limit=2.0, + max_conditioning_steps=1, + ) + + np.testing.assert_allclose(limited0, A + 1e-6 * eye) + np.testing.assert_allclose(limited1, A + 1e-5 * eye) + + def test_from_coefs_matches_direct_minimax_with_non_default_stability(self): + rng = np.random.default_rng(77) + x0, x1 = rng.standard_normal((2, 2)) + cov0 = _make_spd(rng, 2) + cov1 = _make_spd(rng, 2) + pcoef = ellphi.coef_from_cov(x0, cov0)[0] + qcoef = ellphi.coef_from_cov(x1, cov1)[0] + coefs = np.stack([pcoef, qcoef]) + + A_arr, b_arr, _ = unpack_conic(coefs) + centers = np.stack([-np.linalg.solve(A_arr[i], b_arr[i]) for i in range(2)]) + + kwargs = { + "regularization": 1e-6, + "condition_number_limit": 1e6, + "max_conditioning_steps": 2, + "tol": 1e-10, + } + direct = solve_minimax(A_arr, centers, **kwargs) + from_coefs = solve_minimax_from_coefs(coefs, **kwargs) + + assert from_coefs.alpha == pytest.approx(direct.alpha, rel=1e-10, abs=1e-12) + np.testing.assert_allclose( + from_coefs.circumcenter, + direct.circumcenter, + rtol=1e-10, + atol=1e-12, + ) + np.testing.assert_allclose( + from_coefs.weights, direct.weights, rtol=1e-10, atol=1e-12 + ) + + +# --------------------------------------------------------------------------- +# Pairwise compatibility with ellphi.tangency (both backends) +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("dim", [2, 3]) +def test_pairwise_alpha_is_squared_tangency_time(solver_backend, rng, dim): + """For k = 2, ``solve_minimax(...).alpha == tangency(p, q).t ** 2``.""" + for _ in range(5): + pcoef, qcoef = random_coef_pair(rng, dim=dim) + t = ellphi.tangency(pcoef, qcoef, backend=solver_backend).t + + A_arr, b_arr, _ = unpack_conic(np.stack([pcoef, qcoef])) + centers = np.stack([-np.linalg.solve(A_arr[i], b_arr[i]) for i in range(2)]) + res = solve_minimax(A_arr, centers) + + assert res.converged + assert res.alpha == pytest.approx(t**2, rel=1e-9) + assert res.weights.sum() == pytest.approx(1.0, abs=1e-12) + + +# --------------------------------------------------------------------------- +# Regression fixture: weight support versus tight constraint set +# --------------------------------------------------------------------------- + + +@pytest.mark.parametrize("method", list(get_args(minimax_mod.MethodName))) +def test_right_triangle_support_differs_from_tight_set(method): + """Support-vs-tight-set fixture: three unit balls on a right triangle. + + The centers ``(2, 0)``, ``(0, 2)`` and ``(0, 0)`` give ``alpha = 2`` at the + circumcenter ``(1, 1)``. All three constraints are tight there, but the + unique optimal weights are ``(1/2, 1/2, 0)``, so ``active_set`` (the + weight support) has two elements while the tight set has three. + """ + centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) + matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) + + res = solve_minimax(matrices, centers, method=method) + + assert res.converged + assert res.alpha == pytest.approx(2.0, rel=1e-12) + np.testing.assert_allclose(res.circumcenter, [1.0, 1.0], atol=1e-12) + np.testing.assert_allclose(res.weights, [0.5, 0.5, 0.0], atol=1e-10) + assert res.active_set == [0, 1] + + diff = res.circumcenter[np.newaxis] - centers + f = np.einsum("ki,kij,kj->k", diff, matrices, diff) + tight = [i for i in range(3) if abs(f[i] - res.alpha) <= 1e-12 * res.alpha] + assert tight == [0, 1, 2] diff --git a/tests/test_minimax_grad.py b/tests/test_minimax_grad.py new file mode 100644 index 0000000..62f5d91 --- /dev/null +++ b/tests/test_minimax_grad.py @@ -0,0 +1,290 @@ +"""Tests for the minimax gradient with respect to centers and metric matrices. + +Adapted from uda-lab/ellcech ``tests/test_minimax_grad.py`` at commit +82d13e3e174f4903cdcd6adcee1f469348361c91. + +Validation strategy: finite-difference check with relative error < 1e-5. + +The gradient formulas: + d alpha / d xbar_k = 2 mu_k* A_k (xbar_k - x*) + d alpha / d A_k = mu_k* outer(xbar_k - x*, xbar_k - x*) +""" + +from __future__ import annotations + +import numpy as np +import pytest + +from ellphi.minimax import solve_minimax +from ellphi.minimax_grad import GradientResult, compute_gradient + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _make_spd(rng: np.random.Generator, d: int, scale: float = 1.0) -> np.ndarray: + """Return a random d×d SPD matrix.""" + L = rng.standard_normal((d, d)) + return scale * (L @ L.T) + np.eye(d) * 0.5 + + +def _solve_alpha(matrices: np.ndarray, centers: np.ndarray) -> float: + """Compute alpha via fw+brentq+newton (recommended method).""" + res = solve_minimax(matrices, centers, method="fw+brentq+newton") + return res.alpha + + +def _fd_grad_xbar(matrices, centers, k, h=1e-5): + """Finite-difference gradient of alpha w.r.t. centers[k], shape (d,).""" + d = centers.shape[1] + grad = np.zeros(d) + for j in range(d): + c_plus = centers.copy() + c_plus[k, j] += h + c_minus = centers.copy() + c_minus[k, j] -= h + alpha_plus = _solve_alpha(matrices, c_plus) + alpha_minus = _solve_alpha(matrices, c_minus) + grad[j] = (alpha_plus - alpha_minus) / (2 * h) + return grad + + +def _fd_grad_A(matrices, centers, k, h=1e-6): + """Finite-difference gradient of alpha w.r.t. matrices[k], shape (d,d).""" + d = centers.shape[1] + grad = np.zeros((d, d)) + for i in range(d): + for j in range(d): + m_plus = matrices.copy() + m_minus = matrices.copy() + # Symmetric perturbation + m_plus[k, i, j] += h + m_plus[k, j, i] += h + m_minus[k, i, j] -= h + m_minus[k, j, i] -= h + # Ensure still SPD (perturbation is small) + alpha_plus = _solve_alpha(m_plus, centers) + alpha_minus = _solve_alpha(m_minus, centers) + grad[i, j] = (alpha_plus - alpha_minus) / (4 * h) # factor 2 from symmetry + return grad + + +def _rel_err(analytical, fd): + """Relative error between analytical and finite-difference gradients.""" + denom = max(np.linalg.norm(fd), 1e-10) + return float(np.linalg.norm(analytical - fd) / denom) + + +# --------------------------------------------------------------------------- +# Basic functionality tests +# --------------------------------------------------------------------------- + + +class TestGradientResult: + def test_returns_gradient_result(self): + rng = np.random.default_rng(0) + d, k = 2, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + assert isinstance(grad, GradientResult) + + def test_output_shapes(self): + rng = np.random.default_rng(1) + d, k = 3, 4 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + assert len(grad.d_xbar) == k + assert len(grad.d_A) == k + for i in range(k): + assert grad.d_xbar[i].shape == (d,) + assert grad.d_A[i].shape == (d, d) + + def test_passive_vertices_zero(self): + """Inactive vertices (mu_k=0) should have zero gradient.""" + rng = np.random.default_rng(2) + d = 2 + # k=2 pairwise: both vertices are active. Test k=4 where some may be inactive. + k = 4 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + for i in range(k): + if result.weights[i] < 1e-10: + np.testing.assert_allclose(grad.d_xbar[i], 0.0, atol=1e-14) + np.testing.assert_allclose(grad.d_A[i], 0.0, atol=1e-14) + + def test_d_A_symmetric(self): + """d alpha / d A_k = mu_k outer(diff, diff) is symmetric.""" + rng = np.random.default_rng(3) + d, k = 3, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + for i in range(k): + np.testing.assert_allclose(grad.d_A[i], grad.d_A[i].T, atol=1e-15) + + def test_alpha_matches_result(self): + rng = np.random.default_rng(4) + d, k = 2, 2 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + assert grad.alpha == pytest.approx(result.alpha, rel=1e-12) + + def test_weights_match_result(self): + rng = np.random.default_rng(5) + d, k = 2, 2 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + np.testing.assert_allclose(grad.weights, result.weights, atol=1e-15) + + +# --------------------------------------------------------------------------- +# Finite-difference validation tests +# --------------------------------------------------------------------------- + + +class TestFiniteDifferenceValidation: + """Validate analytical gradients against finite differences. + + Target: relative error < 1e-5 for all cases. + """ + + @pytest.mark.parametrize( + "k,d,seed", + [ + (2, 2, 10), + (2, 3, 11), + (3, 2, 12), + (3, 3, 13), + (4, 2, 14), + ], + ) + def test_grad_xbar_fd(self, k, d, seed): + """d alpha / d xbar_k matches finite differences.""" + rng = np.random.default_rng(seed) + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + + for i in range(k): + if result.weights[i] < 1e-8: + continue # skip genuinely inactive + fd = _fd_grad_xbar(matrices, centers, i) + err = _rel_err(grad.d_xbar[i], fd) + assert err < 1e-5, ( + f"k={k},d={d},i={i}: d_xbar rel_err={err:.2e} " + f"analytical={grad.d_xbar[i]}, fd={fd}" + ) + + @pytest.mark.parametrize( + "k,d,seed", + [ + (2, 2, 20), + (2, 3, 21), + (3, 2, 22), + ], + ) + def test_grad_A_fd(self, k, d, seed): + """d alpha / d A_k matches finite differences.""" + rng = np.random.default_rng(seed) + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + + for i in range(k): + if result.weights[i] < 1e-8: + continue # skip inactive + fd = _fd_grad_A(matrices, centers, i) + err = _rel_err(grad.d_A[i], fd) + assert err < 1e-5, f"k={k},d={d},i={i}: d_A rel_err={err:.2e}" + + def test_pairwise_matches_ellphi_direction(self): + """For k=2, gradient direction should be consistent with ellphi's formula.""" + rng = np.random.default_rng(30) + d = 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(2)]) + centers = rng.standard_normal((2, d)) + + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + grad = compute_gradient(result, centers, matrices) + + # Verify against FD + for i in range(2): + fd = _fd_grad_xbar(matrices, centers, i) + err = _rel_err(grad.d_xbar[i], fd) + assert err < 1e-5, f"pairwise xbar[{i}] rel_err={err:.2e}" + + +# --------------------------------------------------------------------------- +# Input validation tests +# --------------------------------------------------------------------------- + + +class TestInputValidation: + def test_shape_mismatch_raises(self): + rng = np.random.default_rng(40) + d, k = 2, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + result = solve_minimax(matrices, centers, method="fw+brentq+newton") + # Wrong: pass centers with k+1 rows but same matrices (k rows) → shape mismatch + bad_centers = rng.standard_normal((k + 1, d)) + bad_matrices = np.stack([_make_spd(rng, d) for _ in range(k + 1)]) + with pytest.raises(ValueError, match="weights length"): + compute_gradient(result, bad_centers, bad_matrices) + + def test_single_point_zero_gradient(self): + """Single-vertex simplex: circumcenter = xbar, weights=[1], grad=0.""" + rng = np.random.default_rng(41) + d = 2 + A = _make_spd(rng, d)[np.newaxis] + center = rng.standard_normal((1, d)) + result = solve_minimax(A, center, method="fw+brentq+newton") + grad = compute_gradient(result, center, A) + # xstar = xbar, so diff = 0, grad = 0 + np.testing.assert_allclose(grad.d_xbar[0], 0.0, atol=1e-14) + np.testing.assert_allclose(grad.d_A[0], 0.0, atol=1e-14) + + def test_all_methods_give_same_gradient(self): + """Gradient should be consistent across solver methods.""" + rng = np.random.default_rng(42) + d, k = 2, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + + methods = ["fw+bisect", "fw+brentq", "fw+bisect+newton", "fw+brentq+newton"] + grads = [] + for method in methods: + result = solve_minimax(matrices, centers, method=method) + grad = compute_gradient(result, centers, matrices) + grads.append(grad) + + # All methods should agree to ~1e-6 + ref = grads[0] + for g in grads[1:]: + for i in range(k): + np.testing.assert_allclose( + g.d_xbar[i], + ref.d_xbar[i], + atol=1e-6, + err_msg=f"d_xbar[{i}] mismatch", + ) + np.testing.assert_allclose( + g.d_A[i], ref.d_A[i], atol=1e-6, err_msg=f"d_A[{i}] mismatch" + ) diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py new file mode 100644 index 0000000..90380a1 --- /dev/null +++ b/tests/test_minimax_methods.py @@ -0,0 +1,356 @@ +"""Tests for multi-method dispatch in the minimax solver. + +Adapted from uda-lab/ellcech ``tests/test_minimax_methods.py`` at commit +82d13e3e174f4903cdcd6adcee1f469348361c91. The benchmark smoke tests are not +ported because the benchmark module is not part of ellphi. + +All methods must agree on alpha to tight tolerances. +fw+bisect is the reference (validated against ellphi in test_minimax.py). +""" + +from __future__ import annotations + +import warnings +from typing import get_args + +import numpy as np +import pytest + +from ellphi.minimax import MethodName, MinimaxResult, solve_minimax + +from .factories import random_simplex + + +# --------------------------------------------------------------------------- +# Helpers +# --------------------------------------------------------------------------- + + +def _random_simplex(k: int, d: int, seed: int = 0): + return random_simplex(k, d, rng=np.random.default_rng(seed)) + + +ALL_METHODS: list[str] = list(get_args(MethodName)) + +CANONICAL_METHODS = ( + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", +) + + +# --------------------------------------------------------------------------- +# Basic dispatch / API +# --------------------------------------------------------------------------- + + +class TestMethodDispatch: + def test_exactly_seven_canonical_methods(self): + assert tuple(ALL_METHODS) == CANONICAL_METHODS + assert "fw+newton" not in ALL_METHODS + + def test_invalid_method_raises(self): + A = np.eye(2)[np.newaxis] + x = np.zeros((1, 2)) + with pytest.raises(ValueError, match="Unknown method"): + solve_minimax(A, x, method="not-a-method") # type: ignore[arg-type] + + @pytest.mark.parametrize("method", ALL_METHODS) + def test_result_has_method_field(self, method): + matrices, centers = _random_simplex(3, 2, seed=7) + res = solve_minimax(matrices, centers, method=method) + assert res.method == method + + @pytest.mark.parametrize("method", ALL_METHODS) + def test_single_point_trivial(self, method): + A = np.eye(3)[np.newaxis] + x = np.array([[1.0, 2.0, 3.0]]) + res = solve_minimax(A, x, method=method) + assert res.alpha == pytest.approx(0.0, abs=1e-12) + assert res.converged + + @pytest.mark.parametrize("method", ALL_METHODS) + def test_k0_raises(self, method): + with pytest.raises(ValueError, match="k=0"): + solve_minimax(np.zeros((0, 2, 2)), np.zeros((0, 2)), method=method) + + def test_default_method_is_fw_bisect(self): + matrices, centers = _random_simplex(2, 2) + res = solve_minimax(matrices, centers) + assert res.method == "fw+bisect" + + +# --------------------------------------------------------------------------- +# Numerical agreement across methods +# --------------------------------------------------------------------------- + + +class TestMethodAgreement: + """All methods must agree on alpha to within reasonable tolerances.""" + + @pytest.mark.parametrize("seed", [0, 1, 2, 3, 4]) + def test_pairwise_k2_d2(self, seed): + """k=2: all methods should agree to 1e-7 with fw+bisect reference.""" + matrices, centers = _random_simplex(2, 2, seed=seed) + ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-12) + for m in ALL_METHODS: + if m == "fw+bisect": + continue + res = solve_minimax(matrices, centers, method=m) + assert res.alpha == pytest.approx( + ref.alpha, rel=1e-7 + ), f"method={m}, seed={seed}: alpha={res.alpha}, ref={ref.alpha}" + + @pytest.mark.parametrize( + "k,d,seed", + [ + (3, 2, 10), + (4, 3, 11), + (5, 3, 12), + (3, 5, 13), + ], + ) + def test_general_k_d(self, k, d, seed): + """General k: all methods (except newton-cold) agree to 1e-5.""" + matrices, centers = _random_simplex(k, d, seed=seed) + ref = solve_minimax( + matrices, centers, method="fw+bisect", tol=1e-11, max_iter=5000 + ) + for m in ALL_METHODS: + if m in ("fw+bisect", "newton-cold"): + continue + res = solve_minimax(matrices, centers, method=m) + assert res.alpha == pytest.approx(ref.alpha, rel=1e-5), ( + f"method={m}, k={k}, d={d}, seed={seed}: " + f"alpha={res.alpha}, ref={ref.alpha}" + ) + + +# --------------------------------------------------------------------------- +# fw+brentq specific +# --------------------------------------------------------------------------- + + +class TestFwBrentq: + @pytest.mark.parametrize("seed", range(5)) + def test_alpha_agrees_with_fw_bisect(self, seed): + """fw+brentq alpha should match fw+bisect to 1e-7.""" + matrices, centers = _random_simplex(4, 3, seed=seed) + ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-11) + res = solve_minimax(matrices, centers, method="fw+brentq", tol=1e-11) + assert res.alpha == pytest.approx( + ref.alpha, rel=1e-7 + ), f"seed={seed}: brentq={res.alpha}, bisect={ref.alpha}" + + def test_metadata_has_line_search_evals(self): + matrices, centers = _random_simplex(4, 3, seed=42) + res = solve_minimax(matrices, centers, method="fw+brentq") + assert res.metadata is not None + assert "line_search_evals" in res.metadata + assert res.metadata["line_search_evals"] > 0 + + +# --------------------------------------------------------------------------- +# fw+brentq+newton specific +# --------------------------------------------------------------------------- + + +class TestFwBrentqNewton: + @pytest.mark.parametrize("seed", range(5)) + def test_alpha_precision(self, seed): + """fw+brentq+newton should achieve high precision.""" + matrices, centers = _random_simplex(4, 3, seed=seed) + ref = solve_minimax( + matrices, + centers, + method="fw+bisect", + tol=1e-14, + max_iter=10000, + ) + res = solve_minimax(matrices, centers, method="fw+brentq+newton") + assert res.alpha == pytest.approx(ref.alpha, rel=1e-7) + + def test_metadata_has_newton_info(self): + matrices, centers = _random_simplex(4, 3, seed=42) + res = solve_minimax(matrices, centers, method="fw+brentq+newton") + assert res.metadata is not None + assert "newton_iters" in res.metadata + assert "hessian_cond" in res.metadata + + +# --------------------------------------------------------------------------- +# newton-cold specific +# --------------------------------------------------------------------------- + + +class TestNewtonCold: + @pytest.mark.parametrize("seed", range(5)) + def test_pairwise_converges(self, seed): + """newton-cold should converge for k=2 (pairwise case).""" + matrices, centers = _random_simplex(2, 2, seed=seed) + res = solve_minimax(matrices, centers, method="newton-cold") + ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-12) + assert res.alpha == pytest.approx( + ref.alpha, rel=1e-4 + ), f"seed={seed}: cold={res.alpha}, ref={ref.alpha}" + + @pytest.mark.parametrize("seed", range(5)) + def test_result_finite(self, seed): + """newton-cold should produce finite results even if not converged.""" + matrices, centers = _random_simplex(5, 3, seed=seed) + res = solve_minimax(matrices, centers, method="newton-cold") + assert np.isfinite(res.alpha) + assert np.all(np.isfinite(res.circumcenter)) + + +# --------------------------------------------------------------------------- +# fw+bisect+damped-newton specific +# --------------------------------------------------------------------------- + + +class TestDampedNewton: + @pytest.mark.parametrize("seed", range(5)) + def test_converges(self, seed): + matrices, centers = _random_simplex(4, 3, seed=seed) + res = solve_minimax(matrices, centers, method="fw+bisect+damped-newton") + ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-12) + assert res.alpha == pytest.approx(ref.alpha, rel=1e-7) + + def test_metadata_has_hessian_cond(self): + matrices, centers = _random_simplex(4, 3, seed=42) + res = solve_minimax(matrices, centers, method="fw+bisect+damped-newton") + assert res.metadata is not None + assert "hessian_cond" in res.metadata + + +# --------------------------------------------------------------------------- +# fw+bisect+newton specific +# --------------------------------------------------------------------------- + + +class TestFwBisectNewton: + def test_pairwise_higher_precision_than_fw_bisect(self): + """fw+bisect+newton should achieve tighter residual than fw+bisect alone.""" + matrices, centers = _random_simplex(3, 3, seed=99) + + ref_tight = solve_minimax( + matrices, centers, method="fw+bisect", tol=1e-14, max_iter=10000 + ) + res_newton = solve_minimax(matrices, centers, method="fw+bisect+newton") + + assert ( + abs(res_newton.alpha - ref_tight.alpha) + <= abs( + solve_minimax(matrices, centers, method="fw+bisect").alpha + - ref_tight.alpha + ) + + 1e-12 + ) + + @pytest.mark.parametrize("seed", range(5)) + def test_converged(self, seed): + matrices, centers = _random_simplex(4, 3, seed=seed) + res = solve_minimax(matrices, centers, method="fw+bisect+newton") + assert res.converged, f"fw+bisect+newton did not converge for seed={seed}" + + def test_active_set_all_equal_fi_at_circumcenter(self): + """At Newton-polished optimum, all active f_i(x*) should be equal.""" + matrices, centers = _random_simplex(4, 3, seed=42) + res = solve_minimax(matrices, centers, method="fw+bisect+newton") + x = res.circumcenter + active = res.active_set + f_vals = np.array( + [ + float( + np.einsum("i,ij,j->", x - centers[i], matrices[i], x - centers[i]) + ) + for i in active + ] + ) + np.testing.assert_allclose(f_vals, res.alpha, rtol=1e-7, atol=1e-10) + + +# --------------------------------------------------------------------------- +# Backward compatibility: "fw+newton" alias +# --------------------------------------------------------------------------- + + +class TestBackwardCompat: + def test_fw_newton_alias_works(self): + """'fw+newton' should work as alias for 'fw+bisect+newton'.""" + matrices, centers = _random_simplex(3, 2, seed=0) + with warnings.catch_warnings(): + warnings.simplefilter("ignore", DeprecationWarning) + res = solve_minimax(matrices, centers, method="fw+newton") + assert res.method == "fw+bisect+newton" + + def test_fw_newton_alias_warns(self): + matrices, centers = _random_simplex(3, 2, seed=0) + with pytest.warns(DeprecationWarning, match="deprecated"): + solve_minimax(matrices, centers, method="fw+newton") + + +# --------------------------------------------------------------------------- +# scipy-slsqp specific +# --------------------------------------------------------------------------- + + +class TestScipySlsqp: + @pytest.mark.parametrize("k", [2, 3, 5]) + def test_alpha_agrees_with_reference(self, k): + matrices, centers = _random_simplex(k, 3, seed=k * 7) + ref = solve_minimax( + matrices, centers, method="fw+bisect", tol=1e-12, max_iter=5000 + ) + res = solve_minimax(matrices, centers, method="scipy-slsqp") + assert res.alpha == pytest.approx( + ref.alpha, rel=1e-6 + ), f"scipy-slsqp alpha mismatch for k={k}: {res.alpha} vs ref {ref.alpha}" + + def test_weights_on_simplex(self): + matrices, centers = _random_simplex(5, 4, seed=55) + res = solve_minimax(matrices, centers, method="scipy-slsqp") + assert res.weights.sum() == pytest.approx(1.0, abs=1e-10) + assert np.all(res.weights >= -1e-12) + + +# --------------------------------------------------------------------------- +# MinimaxResult backward compatibility +# --------------------------------------------------------------------------- + + +class TestMinimaxResultBackwardCompat: + def test_default_method_field(self): + r = MinimaxResult( + alpha=1.0, + circumcenter=np.zeros(2), + weights=np.array([0.5, 0.5]), + active_set=[0, 1], + converged=True, + n_iter=3, + ) + assert r.method == "fw+bisect" + assert r.metadata is None + + def test_namedtuple_positional(self): + r = MinimaxResult(2.0, np.zeros(2), np.ones(2) * 0.5, [0, 1], True, 5) + assert r.alpha == 2.0 + assert r.method == "fw+bisect" + assert r.metadata is None + + def test_metadata_field(self): + r = MinimaxResult( + alpha=1.0, + circumcenter=np.zeros(2), + weights=np.array([0.5, 0.5]), + active_set=[0, 1], + converged=True, + n_iter=3, + method="fw+brentq", + metadata={"fw_iters": 10}, + ) + assert r.metadata == {"fw_iters": 10} From c4685b7b9938f88616fe2171acc66316bbf8251b Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 15:59:15 +0900 Subject: [PATCH 02/29] docs: record owner MIT decision for the ellcech source in provenance headers Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/minimax.py | 8 ++++---- src/ellphi/minimax_grad.py | 5 +++-- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/src/ellphi/minimax.py b/src/ellphi/minimax.py index 9b55755..d207c7a 100644 --- a/src/ellphi/minimax.py +++ b/src/ellphi/minimax.py @@ -9,10 +9,10 @@ strings, defaults and tolerances are kept unchanged; the changes are packaging-level only (intra-package import of ``unpack_conic``, type annotations, documentation). Distributed as part of EllPHi under its MIT -license. The rights question for the ellcech source is tracked in -uda-lab/project-ellphi#26. The docstring corrections in items 1–3 -deliberately deviate from the ellcech 82d13e3 docstrings; code paths are -unchanged. +license; the ellcech source is MIT by owner decision +(uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. The docstring +corrections in items 1–3 deliberately deviate from the ellcech 82d13e3 +docstrings; code paths are unchanged. The module name and the public names exported from ``ellphi`` are provisional and may change. diff --git a/src/ellphi/minimax_grad.py b/src/ellphi/minimax_grad.py index 386f8ad..51d3511 100644 --- a/src/ellphi/minimax_grad.py +++ b/src/ellphi/minimax_grad.py @@ -9,8 +9,9 @@ docstring is written for EllPHi rather than copied from either revision: it adopts the ebe63a4 remark that zero weights give zero gradient blocks, but not its characterization of differentiability. The code is unchanged. -Distributed as part of EllPHi under its MIT license. The rights question for -the ellcech source is tracked in uda-lab/project-ellphi#26. +Distributed as part of EllPHi under its MIT license; the ellcech source is +MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with +EllPHi. The module name and the public names exported from ``ellphi`` are provisional and may change. From 225111e043ded8020dd61c281a38f8c7014ade3e Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 20:41:24 +0900 Subject: [PATCH 03/29] feat: add pairwise-aligned public many-body API (tangency_simplex, tangency_simplex_grad) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squash of local topic branch project26-pairwise-contract (6 commits) after two local Codex review rounds (gpt-5.6-sol, read-only): - round 1: REQUEST CHANGES — blocker: engine ignores the packed constant term, so t/point/dt_dcoef are valid only for normalised rows; major: SimplexTangencyGrad field order; minor: non-finite tolerances; minor: right-triangle fixture assertions. Fixed in 81b311c (gpt-5.6-luna): per-row normalisation gate (ValueError otherwise), documented normalisation-preserving derivative, field order, tolerance validation. - round 2: REQUEST CHANGES — blocker: catastrophic cancellation when evaluating the packed quadric at far-translated points (t from result.alpha, centred constraint evaluation); major: gate rejected valid coef_from_cov output for ill-conditioned covariances and d=1. Fixed in 9cca0ca: conditioning-aware bound max(norm_tol*max(1,|c|), 64*eps*cond2(A)*max(1,|c|,|b^T A^-1 b|)); d=1 packed conics are a pre-existing EllPHi limitation (unpack_conic), documented and reported with a clear error. Two-round cap reached; dispositions recorded here; checklist re-run independently (446 passed). Public contract: SimplexTangencyResult(t, point, mu, support, active_set) with active_set = tight constraints (paper sense) and support = weight support; raises on non-convergence; SimplexTangencyGrad(t, point, mu, dt_dcoef, support, active_set) in coef space. Engine moved to private _minimax_python / _minimax_grad_python modules (history preserved). General constants inside the solve are implemented on the engine branch and will lift the normalisation gate. Names provisional (#26). Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- AGENTS.md | 2 +- docs/guide/many_body_tangency.md | 54 +++ mkdocs.yml | 1 + src/ellphi/__init__.py | 25 +- src/ellphi/__init__.pyi | 22 +- ...inimax_grad.py => _minimax_grad_python.py} | 11 +- ...imax_grad.pyi => _minimax_grad_python.pyi} | 2 +- src/ellphi/{minimax.py => _minimax_python.py} | 6 +- .../{minimax.pyi => _minimax_python.pyi} | 0 src/ellphi/simplex.py | 309 ++++++++++++++++++ src/ellphi/simplex.pyi | 44 +++ stubtest-allowlist.txt | 2 +- tests/test_minimax.py | 6 +- tests/test_minimax_grad.py | 4 +- tests/test_minimax_methods.py | 2 +- tests/test_simplex.py | 277 ++++++++++++++++ 16 files changed, 726 insertions(+), 41 deletions(-) create mode 100644 docs/guide/many_body_tangency.md rename src/ellphi/{minimax_grad.py => _minimax_grad_python.py} (94%) rename src/ellphi/{minimax_grad.pyi => _minimax_grad_python.pyi} (91%) rename src/ellphi/{minimax.py => _minimax_python.py} (99%) rename src/ellphi/{minimax.pyi => _minimax_python.pyi} (100%) create mode 100644 src/ellphi/simplex.py create mode 100644 src/ellphi/simplex.pyi create mode 100644 tests/test_simplex.py diff --git a/AGENTS.md b/AGENTS.md index 5a46c04..7f5e53c 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -90,7 +90,7 @@ This section documents the reasons for each entry in the `stubtest-allowlist.txt **Reason:** This entry is necessary because the `MethodName` type alias is defined as a `typing.Literal` in the implementation, but it is simplified to `str` in the corresponding stub file (`.pyi`). This simplification is intentional to avoid duplicating the literal values in the stub, which would make it harder to maintain. (An equivalent entry for the `ellphi.solver` re-export was needed with older mypy versions but is reported as unused since mypy 1.20.) -* `ellphi.minimax.MethodName` +* `ellphi._minimax_python.MethodName` **Reason:** The stub declares the same seven-value `typing.Literal` alias as the implementation, but stubtest cannot verify multi-value `Literal` aliases: it expands the stub alias into a union of single-value literals and reports the runtime alias as "not a Union". Simplifying the stub to `str` does not avoid the report either, so the entry keeps the precise stub type. diff --git a/docs/guide/many_body_tangency.md b/docs/guide/many_body_tangency.md new file mode 100644 index 0000000..d177c8b --- /dev/null +++ b/docs/guide/many_body_tangency.md @@ -0,0 +1,54 @@ +# Many-body tangency + +The provisional `ellphi.simplex` API extends pairwise tangency to a simplex of +packed ellipsoid coefficient vectors. `tangency_simplex(coefs)` returns the +tangency time `t`, point, simplex multipliers `mu`, multiplier `support`, and +numerically determined `active_set`. Unlike the internal minimax engine, the +public API reports `t`, not the squared value `t**2`. + +The public result fields are ordered as `(t, point, mu, support, active_set)`. +The gradient result fields are ordered as +`(t, point, mu, dt_dcoef, support, active_set)`. + +`support` is the thresholded weight support +`{i : mu_i > weight_tol}`. `active_set` is the tight-constraint set at the +returned point, +`I = {i : t**2 - f_i(point) <= active_tol * max(1, t**2)}`. Up to numerical +tolerance, `support` is a subset of `active_set`; under strict complementarity +(ND1), they coincide. For three unit balls centred at `(0, 0)`, `(2, 0)`, and +`(0, 2)`, the point is `(1, 1)`, support has two indices, and `active_set` +has three. A solver that does not converge or produces non-finite output +raises `RuntimeError` with its diagnostics. + +The private engine's internal field named `active_set` is the weight support +(historical ellcech naming) and is not part of the public API. + +Every coefficient row must be a normalized conic. If `unpack_conic` returns +`(A_i, b_i, c_i)`, the required convention is +`b_i = -A_i xbar_i` and `c_i = xbar_i^T A_i xbar_i`, equivalently +`c_i = b_i^T A_i^{-1} b_i` within the maximum of +`norm_tol * max(1, abs(c_i))` and +`64 * eps * cond2(A_i) * max(1, abs(c_i), abs(b_i^T A_i^{-1} b_i))`, +where `eps` is machine epsilon and `norm_tol` defaults to `1e-9`. +`tangency_simplex` and `tangency_simplex_grad` reject an offending row with +`ValueError`; `ellphi.coef_from_cov` constructs coefficients in this form. +Packed input requires `d >= 2`, as for `ellphi.tangency`; d=1 packed conics +are not supported and raise `ValueError`. + +The private engine reconstructs each center from `(A_i, b_i)` and ignores +`c_i` during optimization. Thus `tangency_simplex_grad(coefs)` returns +`dt_dcoef`, a coefficient-space covector whose contraction with a packed +direction is the derivative of `t` only for normalization-preserving +perturbations. For the upper-triangular packed basis +`[x_i**2, 2*x_i*x_j (i < j), 2*x_i, 1]`, the formula is +`mu_i * basis(point) / (2*t)`. The constant-term component must be read in +this chain-rule sense, not as a derivative under an arbitrary independent +change to a packed constant. It assumes a non-degenerate input, at least two +indices in `active_set`, multipliers supported on `active_set`, and an exact +weighted linear solve. Convergence or a small residual alone is not a +derivative certificate, and the gradient is undefined at `t == 0`. +For far-translated inputs, the uncentred packed basis used by this derivative +can be poorly conditioned. + +Support for general independent constants inside the minimax solve is planned +engine work; it is not part of this wrapper contract. diff --git a/mkdocs.yml b/mkdocs.yml index 5503958..7b6dc48 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,6 +69,7 @@ nav: - User Guide: - TDA Workflow: guide/tda_workflow.md - Differentiable Tangency: guide/differentiable.md + - Many-body Tangency: guide/many_body_tangency.md - Notebook Examples: guide/notebooks.md - API Reference: - Overview: reference/index.md diff --git a/src/ellphi/__init__.py b/src/ellphi/__init__.py index 1a584be..4bbde31 100644 --- a/src/ellphi/__init__.py +++ b/src/ellphi/__init__.py @@ -14,8 +14,8 @@ two ellipses. - `ellphi.visualization`: Helper functions for visualizing ellipses and ellipse clouds. -- `ellphi.minimax`, `ellphi.minimax_grad`: Many-body minimax filtration - values and their gradients (provisional names). +- `ellphi.simplex`: Pairwise-aligned many-body tangency values and gradients + (provisional names). """ import numpy as np @@ -48,9 +48,13 @@ from .grad import TangencyGrad, tangency_grad, pdist_tangency_grad, coef_from_cov_grad -# many-body minimax (provisional names) -from .minimax import MinimaxResult, solve_minimax, solve_minimax_from_coefs -from .minimax_grad import GradientResult, compute_gradient +# many-body tangency (provisional names) +from .simplex import ( + SimplexTangencyResult, + SimplexTangencyGrad, + tangency_simplex, + tangency_simplex_grad, +) FloatArray = NDArray[np.float64] @@ -82,12 +86,11 @@ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", - # many-body minimax (provisional) - "MinimaxResult", - "solve_minimax", - "solve_minimax_from_coefs", - "GradientResult", - "compute_gradient", + # many-body tangency (provisional) + "SimplexTangencyResult", + "SimplexTangencyGrad", + "tangency_simplex", + "tangency_simplex_grad", "__version__", "version_info", ] diff --git a/src/ellphi/__init__.pyi b/src/ellphi/__init__.pyi index e42786d..23178b6 100644 --- a/src/ellphi/__init__.pyi +++ b/src/ellphi/__init__.pyi @@ -32,14 +32,11 @@ from .grad import ( pdist_tangency_grad as pdist_tangency_grad, coef_from_cov_grad as coef_from_cov_grad, ) -from .minimax import ( - MinimaxResult as MinimaxResult, - solve_minimax as solve_minimax, - solve_minimax_from_coefs as solve_minimax_from_coefs, -) -from .minimax_grad import ( - GradientResult as GradientResult, - compute_gradient as compute_gradient, +from .simplex import ( + SimplexTangencyGrad as SimplexTangencyGrad, + SimplexTangencyResult as SimplexTangencyResult, + tangency_simplex as tangency_simplex, + tangency_simplex_grad as tangency_simplex_grad, ) from ._version import __version__ as __version__ @@ -68,11 +65,10 @@ __all__ = [ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", - "MinimaxResult", - "solve_minimax", - "solve_minimax_from_coefs", - "GradientResult", - "compute_gradient", + "SimplexTangencyResult", + "SimplexTangencyGrad", + "tangency_simplex", + "tangency_simplex_grad", "FloatArray", "__version__", "version_info", diff --git a/src/ellphi/minimax_grad.py b/src/ellphi/_minimax_grad_python.py similarity index 94% rename from src/ellphi/minimax_grad.py rename to src/ellphi/_minimax_grad_python.py index 51d3511..fc4920b 100644 --- a/src/ellphi/minimax_grad.py +++ b/src/ellphi/_minimax_grad_python.py @@ -13,12 +13,12 @@ MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. -The module name and the public names exported from ``ellphi`` are -provisional and may change. +This numerical engine is internal. The provisional public interface is +:mod:`ellphi.simplex`. Formula ------- -Given a :class:`~ellphi.minimax.MinimaxResult` with weights ``mu`` and +Given a :class:`~ellphi._minimax_python.MinimaxResult` with weights ``mu`` and circumcenter ``x*``, the envelope theorem applied to the dual gives d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*) @@ -57,7 +57,7 @@ import numpy as np -from .minimax import MinimaxResult +from ._minimax_python import MinimaxResult __all__ = [ "GradientResult", @@ -99,7 +99,8 @@ def compute_gradient( gradient. Args: - result: A MinimaxResult from :func:`ellphi.minimax.solve_minimax` + result: A MinimaxResult from + :func:`ellphi._minimax_python.solve_minimax` computed for the same ``centers`` and ``matrices``. centers: Centers ``xbar_i``, shape ``(k, d)``. matrices: SPD matrices ``A_i``, shape ``(k, d, d)``. diff --git a/src/ellphi/minimax_grad.pyi b/src/ellphi/_minimax_grad_python.pyi similarity index 91% rename from src/ellphi/minimax_grad.pyi rename to src/ellphi/_minimax_grad_python.pyi index 393971f..b07e637 100644 --- a/src/ellphi/minimax_grad.pyi +++ b/src/ellphi/_minimax_grad_python.pyi @@ -3,7 +3,7 @@ from typing import Sequence import numpy as np -from .minimax import MinimaxResult +from ._minimax_python import MinimaxResult __all__ = [ "GradientResult", diff --git a/src/ellphi/minimax.py b/src/ellphi/_minimax_python.py similarity index 99% rename from src/ellphi/minimax.py rename to src/ellphi/_minimax_python.py index d207c7a..cb4c2cd 100644 --- a/src/ellphi/minimax.py +++ b/src/ellphi/_minimax_python.py @@ -14,8 +14,8 @@ corrections in items 1–3 deliberately deviate from the ellcech 82d13e3 docstrings; code paths are unchanged. -The module name and the public names exported from ``ellphi`` are -provisional and may change. +This numerical engine is internal. The provisional public interface is +:mod:`ellphi.simplex`. Mathematical background ----------------------- @@ -63,7 +63,7 @@ ``MinimaxResult.converged`` reports whether the chosen method met its own stopping test for the value. It is not a certificate that ``alpha`` is differentiable at the input or that the returned weights are accurate enough -for derivatives; see :mod:`ellphi.minimax_grad` for the hypotheses under +for derivatives; see :mod:`ellphi._minimax_grad_python` for the hypotheses under which the gradient formula applies. Correspondence with the pairwise solver diff --git a/src/ellphi/minimax.pyi b/src/ellphi/_minimax_python.pyi similarity index 100% rename from src/ellphi/minimax.pyi rename to src/ellphi/_minimax_python.pyi diff --git a/src/ellphi/simplex.py b/src/ellphi/simplex.py new file mode 100644 index 0000000..74d081c --- /dev/null +++ b/src/ellphi/simplex.py @@ -0,0 +1,309 @@ +"""Pairwise-aligned many-body tangency API (provisional names). + +The names in this module are provisional. ``tangency_simplex`` extends the +pairwise :func:`ellphi.tangency` contract to one or more packed ellipsoid +coefficient vectors while keeping the many-body numerical engine internal. +""" + +from __future__ import annotations + +from typing import Any, NamedTuple + +import numpy as np + +from ._minimax_python import MethodName, solve_minimax_from_coefs +from .geometry import unpack_conic + +__all__ = [ + "SimplexTangencyResult", + "SimplexTangencyGrad", + "tangency_simplex", + "tangency_simplex_grad", +] + + +_NORMALIZATION_ROUNDING_FACTOR = 64.0 +_MACHINE_EPSILON = np.finfo(float).eps + + +class SimplexTangencyResult(NamedTuple): + """Result of a many-body tangency calculation. + + ``support`` is the thresholded weight support ``{i: mu[i] > weight_tol}``. + ``active_set`` is the tight-constraint set at the returned point, + ``I = {i : t**2 - f_i(point) <= active_tol * max(1, t**2)}``. Up to + numerical tolerance, ``support`` is a subset of ``active_set``; under + strict complementarity (ND1), they coincide. In the degenerate example + of unit balls centred at ``(0, 0)``, ``(2, 0)``, and ``(0, 2)``, support + has two indices while ``active_set`` has three. + + The private engine's internal field named ``active_set`` is the weight + support (historical ellcech naming) and is not part of the public API. + + Attributes: + t: Tangency time ``sqrt(max_i f_i(point))``. + point: Tangency point, shape ``(d,)``. + mu: Simplex multipliers, shape ``(k,)``. + support: Indices with multiplier greater than ``weight_tol``. + active_set: Tight constraints satisfying the numerical active-set + test with ``active_tol``. + """ + + t: float + point: np.ndarray + mu: np.ndarray + support: tuple[int, ...] + active_set: tuple[int, ...] + + +class SimplexTangencyGrad(NamedTuple): + """Many-body tangency result and coefficient-space gradient. + + ``support`` and ``active_set`` have the definitions documented for + :class:`SimplexTangencyResult`. + + Attributes: + t: Tangency time. + point: Tangency point, shape ``(d,)``. + mu: Simplex multipliers, shape ``(k,)``. + dt_dcoef: Gradient of ``t`` for normalization-preserving packed + coefficient perturbations, shape ``(k, m)``. + support: Indices with multiplier greater than ``weight_tol``. + active_set: Tight constraints at ``point`` under ``active_tol``. + """ + + t: float + point: np.ndarray + mu: np.ndarray + dt_dcoef: np.ndarray + support: tuple[int, ...] + active_set: tuple[int, ...] + + +def _coefficient_basis(point: np.ndarray) -> np.ndarray: + """Return the packed conic monomial basis at ``point``.""" + tri_i, tri_j = np.triu_indices(point.shape[0]) + quadratic = np.where( + tri_i == tri_j, + point[tri_i] ** 2, + 2.0 * point[tri_i] * point[tri_j], + ) + return np.concatenate((quadratic, 2.0 * point, np.array([1.0]))) + + +def _validate_tolerance(name: str, value: float) -> None: + """Validate a finite, non-negative numerical tolerance.""" + if not np.isfinite(value) or value < 0.0: + raise ValueError(f"{name} must be finite and non-negative") + + +def _validate_normalized_coefs( + coefs: np.ndarray, norm_tol: float +) -> tuple[np.ndarray, np.ndarray]: + """Validate the normalized conic identity used by the private engine.""" + matrices, linear, constants = unpack_conic(coefs) + centers = np.empty_like(linear) + for row, (matrix, vector, constant) in enumerate(zip(matrices, linear, constants)): + try: + inverse_times_linear = np.linalg.solve(matrix, vector) + except np.linalg.LinAlgError as exc: + raise ValueError( + f"coefficient row {row} is not a normalised conic; use " + "ellphi.coef_from_cov for normalised conics" + ) from exc + + centered_constant = float(vector @ inverse_times_linear) + residual = abs(float(constant) - centered_constant) + condition_number = float(np.linalg.cond(matrix, 2)) + scale = max(1.0, abs(float(constant)), abs(centered_constant)) + bound = max( + norm_tol * max(1.0, abs(float(constant))), + _NORMALIZATION_ROUNDING_FACTOR + * _MACHINE_EPSILON + * condition_number + * scale, + ) + if not np.isfinite(residual) or residual > bound: + raise ValueError( + f"coefficient row {row} is not a normalised conic: " + f"|c_i - b_i^T A_i^-1 b_i|={residual} exceeds " + f"the normalization tolerance bound={bound}; use " + "ellphi.coef_from_cov for normalised conics" + ) + centers[row] = -inverse_times_linear + return matrices, centers + + +def _centered_constraint_values( + point: np.ndarray, matrices: np.ndarray, centers: np.ndarray +) -> np.ndarray: + """Evaluate all constraints using the engine's reconstructed centers.""" + differences = point[np.newaxis, :] - centers + return np.einsum("ki,kij,kj->k", differences, matrices, differences) + + +def tangency_simplex( + coefs: np.ndarray, + *, + method: MethodName | str = "fw+bisect", + tol: float = 1e-9, + max_iter: int = 2000, + weight_tol: float = 1e-10, + active_tol: float = 1e-9, + norm_tol: float = 1e-9, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = 8, + newton_tol: float = 1e-14, + newton_max_iter: int = 20, +) -> SimplexTangencyResult: + """Compute the common tangency time for a simplex of ellipsoids. + + Args: + coefs: Packed conic coefficient vectors, shape ``(k, m)``. + method: Internal many-body solver method. + tol: Frank-Wolfe gap tolerance. + max_iter: Maximum Frank-Wolfe iterations. + weight_tol: Threshold defining ``support``. + active_tol: Relative tolerance defining ``active_set`` as the + tight-constraint set at the returned point. + norm_tol: Relative tolerance for the required normalized-conic + identity. The accepted residual bound is the maximum of + ``norm_tol * max(1, |c_i|)`` and + ``64 * eps * cond2(A_i) * max(1, |c_i|, + |b_i^T A_i^{-1} b_i|)``. Each row must use the convention + ``b_i = -A_i xbar_i`` and ``c_i = xbar_i^T A_i xbar_i``. + regularization: Optional diagonal regularization of weighted matrices. + condition_number_limit: Optional weighted-matrix condition target. + max_conditioning_steps: Maximum conditioning-shift escalations. + newton_tol: Newton-polishing residual tolerance. + newton_max_iter: Maximum Newton-polishing iterations. + + Returns: + A result using tangency time rather than squared filtration value. + + Raises: + ValueError: If the coefficient array is not two-dimensional, is empty, + a tolerance is not finite and non-negative, or a coefficient row + is not a normalized conic. Packed input requires ``d >= 2``, as + for :func:`ellphi.tangency`. Use :func:`ellphi.coef_from_cov` to + construct normalized rows. + RuntimeError: If the internal solver does not converge or produces a + non-finite output. Solver diagnostics are included in the error. + """ + coefs = np.asarray(coefs, dtype=float) + if coefs.ndim != 2: + raise ValueError("Expected coefficient array with shape (k, m)") + if coefs.shape[0] == 0: + raise ValueError("simplex must contain at least one vertex (k=0 given)") + if coefs.shape[1] == 3: + raise ValueError( + "packed input requires d >= 2, as for ellphi.tangency; " + "one-dimensional packed conics are not supported" + ) + _validate_tolerance("active_tol", active_tol) + _validate_tolerance("weight_tol", weight_tol) + _validate_tolerance("norm_tol", norm_tol) + matrices, centers = _validate_normalized_coefs(coefs, norm_tol) + + result = solve_minimax_from_coefs( + coefs, + method=method, + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, + ) + finite = ( + np.isfinite(result.alpha) + and np.all(np.isfinite(result.circumcenter)) + and np.all(np.isfinite(result.weights)) + ) + if not result.converged or not finite: + reason = "did not converge" if not result.converged else "was non-finite" + raise RuntimeError( + "tangency_simplex " + f"{reason}: method={result.method!r}, n_iter={result.n_iter}, " + f"diagnostics={result.metadata!r}" + ) + + values = _centered_constraint_values(result.circumcenter, matrices, centers) + if not np.all(np.isfinite(values)): + raise RuntimeError( + "tangency_simplex was non-finite: " + f"method={result.method!r}, n_iter={result.n_iter}, " + f"diagnostics={result.metadata!r}" + ) + t_squared = float(max(result.alpha, 0.0)) + t = float(np.sqrt(max(0.0, t_squared))) + support = tuple(int(i) for i in np.flatnonzero(result.weights > weight_tol)) + active_threshold = active_tol * max(1.0, t_squared) + active_set = tuple( + int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) + ) + + return SimplexTangencyResult( + t=t, + point=result.circumcenter, + mu=result.weights, + support=support, + active_set=active_set, + ) + + +def tangency_simplex_grad( + coefs: np.ndarray, **solver_kwargs: Any +) -> SimplexTangencyGrad: + """Return many-body tangency and its normalized-coefficient gradient. + + For EllPHi's packed conic ``f_i(x) = coef_i @ basis(x)``, the basis is + ``[x_j**2 if j == l else 2*x_j*x_l for j <= l, 2*x_0, ..., 2*x_(d-1), 1]`` + in NumPy upper-triangle order. The envelope theorem gives + ``d(t**2)/d coef_i = mu_i * basis(point)`` and therefore + ``dt/d coef_i = mu_i * basis(point) / (2*t)``. + + The private engine reconstructs each center from ``A_i`` and ``b_i`` and + ignores ``c_i`` during optimization. Therefore ``dt_dcoef`` is the + coefficient-space covector for packed perturbations that preserve + ``b_i = -A_i xbar_i`` and ``c_i = xbar_i^T A_i xbar_i``. It is not a + derivative with respect to arbitrary independent packed-coordinate + perturbations; the constant component has this normalization-preserving + chain-rule meaning. + + This is a gradient of ``t``, not ``t**2``. Its hypotheses are a + non-degenerate input, at least two indices in ``active_set``, multipliers + supported on ``active_set``, and an exact weighted linear solve. Solver + convergence or a small residual alone is not a derivative certificate. + For far-translated inputs, evaluating this coefficient-space derivative in + the uncentred packed basis can itself be poorly conditioned. + + Args: + coefs: Packed conic coefficient vectors, shape ``(k, m)``. + **solver_kwargs: Forwarded to :func:`tangency_simplex`. + + Returns: + Tangency data and ``dt_dcoef`` with shape ``(k, m)``. + + Raises: + ZeroDivisionError: If the tangency time is zero. + RuntimeError: If the forward solve fails. + """ + coefs = np.asarray(coefs, dtype=float) + result = tangency_simplex(coefs, **solver_kwargs) + if result.t == 0.0: + raise ZeroDivisionError("tangency gradient is undefined when t == 0") + + basis = _coefficient_basis(result.point) + dt_dcoef = result.mu[:, np.newaxis] * basis[np.newaxis, :] / (2.0 * result.t) + return SimplexTangencyGrad( + t=result.t, + point=result.point, + mu=result.mu, + dt_dcoef=dt_dcoef, + support=result.support, + active_set=result.active_set, + ) diff --git a/src/ellphi/simplex.pyi b/src/ellphi/simplex.pyi new file mode 100644 index 0000000..7ff4a63 --- /dev/null +++ b/src/ellphi/simplex.pyi @@ -0,0 +1,44 @@ +from typing import Any, NamedTuple + +import numpy as np + +__all__ = [ + "SimplexTangencyResult", + "SimplexTangencyGrad", + "tangency_simplex", + "tangency_simplex_grad", +] + +class SimplexTangencyResult(NamedTuple): + t: float + point: np.ndarray + mu: np.ndarray + support: tuple[int, ...] + active_set: tuple[int, ...] + +class SimplexTangencyGrad(NamedTuple): + t: float + point: np.ndarray + mu: np.ndarray + dt_dcoef: np.ndarray + support: tuple[int, ...] + active_set: tuple[int, ...] + +def tangency_simplex( + coefs: np.ndarray, + *, + method: str = "fw+bisect", + tol: float = 1e-9, + max_iter: int = 2000, + weight_tol: float = 1e-10, + active_tol: float = 1e-9, + norm_tol: float = 1e-9, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = 8, + newton_tol: float = 1e-14, + newton_max_iter: int = 20, +) -> SimplexTangencyResult: ... +def tangency_simplex_grad( + coefs: np.ndarray, **solver_kwargs: Any +) -> SimplexTangencyGrad: ... diff --git a/stubtest-allowlist.txt b/stubtest-allowlist.txt index 9a3f320..a3a2b08 100644 --- a/stubtest-allowlist.txt +++ b/stubtest-allowlist.txt @@ -1,2 +1,2 @@ ellphi._solver_python.MethodName -ellphi.minimax.MethodName +ellphi._minimax_python.MethodName diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 45ec49b..6fe8087 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -15,9 +15,9 @@ import pytest import ellphi -import ellphi.minimax as minimax_mod +import ellphi._minimax_python as minimax_mod from ellphi.geometry import unpack_conic -from ellphi.minimax import solve_minimax, solve_minimax_from_coefs +from ellphi._minimax_python import solve_minimax, solve_minimax_from_coefs from .factories import random_coef_pair @@ -385,7 +385,7 @@ def test_pairwise_alpha_is_squared_tangency_time(solver_backend, rng, dim): @pytest.mark.parametrize("method", list(get_args(minimax_mod.MethodName))) -def test_right_triangle_support_differs_from_tight_set(method): +def test_right_triangle_support_differs_from_tight_constraint_set(method): """Support-vs-tight-set fixture: three unit balls on a right triangle. The centers ``(2, 0)``, ``(0, 2)`` and ``(0, 0)`` give ``alpha = 2`` at the diff --git a/tests/test_minimax_grad.py b/tests/test_minimax_grad.py index 62f5d91..27c6af0 100644 --- a/tests/test_minimax_grad.py +++ b/tests/test_minimax_grad.py @@ -15,8 +15,8 @@ import numpy as np import pytest -from ellphi.minimax import solve_minimax -from ellphi.minimax_grad import GradientResult, compute_gradient +from ellphi._minimax_grad_python import GradientResult, compute_gradient +from ellphi._minimax_python import solve_minimax # --------------------------------------------------------------------------- diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index 90380a1..d454993 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -16,7 +16,7 @@ import numpy as np import pytest -from ellphi.minimax import MethodName, MinimaxResult, solve_minimax +from ellphi._minimax_python import MethodName, MinimaxResult, solve_minimax from .factories import random_simplex diff --git a/tests/test_simplex.py b/tests/test_simplex.py new file mode 100644 index 0000000..e145f78 --- /dev/null +++ b/tests/test_simplex.py @@ -0,0 +1,277 @@ +"""Tests for the pairwise-aligned many-body tangency API.""" + +from __future__ import annotations + +from typing import get_args + +import numpy as np +import pytest + +import ellphi +from ellphi._minimax_python import MethodName +from ellphi.geometry import coef_from_cov + +from .factories import random_coef_pair, random_covariance + + +def _random_coefs(k: int, d: int, seed: int) -> np.ndarray: + rng = np.random.default_rng(seed) + centers = rng.uniform(-2.0, 2.0, size=(k, d)) + covariances = np.stack([random_covariance(rng, dim=d) for _ in range(k)]) + return coef_from_cov(centers, covariances) + + +def _relative_error(actual: np.ndarray | float, expected: np.ndarray | float) -> float: + numerator = float(np.linalg.norm(actual - expected)) + denominator = max( + float(np.linalg.norm(actual)), float(np.linalg.norm(expected)), 1e-15 + ) + return numerator / denominator + + +def test_pairwise_agrees_with_tangency(solver_backend, rng): + p, q = random_coef_pair(rng, dim=3) + result = ellphi.tangency_simplex(np.stack((p, q))) + pairwise = ellphi.tangency(p, q, backend=solver_backend) + + assert result.t == pytest.approx(pairwise.t, rel=1e-9) + np.testing.assert_allclose(result.point, pairwise.point, rtol=1e-9, atol=1e-10) + np.testing.assert_allclose( + result.mu, (1.0 - pairwise.mu, pairwise.mu), rtol=1e-8, atol=1e-10 + ) + + +def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backend): + centers = np.array([[1e8, 0.0], [1e8 + 2.0, 0.0]]) + coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], 2, axis=0)) + pairwise_coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + + result = ellphi.tangency_simplex(coefs) + pairwise = ellphi.tangency( + pairwise_coefs[0], pairwise_coefs[1], backend=solver_backend + ) + gradient = ellphi.tangency_simplex_grad(coefs) + tri_i, tri_j = np.triu_indices(2) + basis = np.concatenate( + ( + np.where( + tri_i == tri_j, + result.point[tri_i] ** 2, + 2.0 * result.point[tri_i] * result.point[tri_j], + ), + 2.0 * result.point, + np.array([1.0]), + ) + ) + pairwise_identity = 0.5 * basis / (2.0 * pairwise.t) + + assert result.t == pytest.approx(pairwise.t, rel=1e-9) + assert result.active_set == (0, 1) + assert np.all(np.isfinite(gradient.dt_dcoef)) + assert _relative_error(gradient.dt_dcoef[0], pairwise_identity) < 1e-6 + assert _relative_error(gradient.dt_dcoef[1], pairwise_identity) < 1e-6 + + +@pytest.mark.parametrize("dimension", [2, 3, 4]) +@pytest.mark.parametrize("condition_number", [1e2, 1e6, 1e10, 1e12]) +def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_number): + rng = np.random.default_rng(2700 + dimension) + rotation, _ = np.linalg.qr(rng.standard_normal((dimension, dimension))) + eigenvalues = np.geomspace(1.0, condition_number, dimension) + covariance = rotation @ np.diag(eigenvalues) @ rotation.T + center = rng.uniform(-2.0, 2.0, size=(1, dimension)) + coefs = coef_from_cov(center, covariance[None]) + + result = ellphi.tangency_simplex(coefs) + + assert result.t == 0.0 + assert np.all(np.isfinite(result.point)) + + +def test_scaled_centres_from_cov_are_accepted(): + centers = np.array([[1e6, -1e6], [1e6 + 2.0, -1e6 + 1.0]]) + covariances = np.array( + [ + [[2.0, 0.3], [0.3, 1.5]], + [[1.2, -0.2], [-0.2, 0.8]], + ] + ) + + result = ellphi.tangency_simplex(coef_from_cov(centers, covariances)) + + assert np.isfinite(result.t) + assert result.active_set == (0, 1) + + +def test_packed_one_dimensional_input_is_rejected_like_pairwise(): + coefs = np.array([[1.0, -2.0, 1.0], [1.0, -4.0, 4.0]]) + + with pytest.raises( + ValueError, match="packed input requires d >= 2, as for ellphi.tangency" + ): + ellphi.tangency_simplex(coefs) + + +@pytest.mark.parametrize("method", list(get_args(MethodName))) +def test_right_triangle_distinguishes_support_and_active_set(method): + centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) + coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], 3, axis=0)) + + result = ellphi.tangency_simplex(coefs, method=method, active_tol=1e-12) + + assert result.t == pytest.approx(np.sqrt(2.0), rel=1e-12) + np.testing.assert_allclose(result.point, [1.0, 1.0], atol=1e-12) + assert len(result.support) == 2 + assert len(result.active_set) == 3 + assert result.support == (0, 1) + assert set(result.support) <= set(result.active_set) + assert result.active_set == (0, 1, 2) + + +def test_singleton_and_empty_simplex(): + coefs = coef_from_cov(np.array([[1.0, -2.0]]), np.eye(2)[None]) + result = ellphi.tangency_simplex(coefs) + + assert result.t == 0.0 + np.testing.assert_allclose(result.point, [1.0, -2.0]) + np.testing.assert_array_equal(result.mu, [1.0]) + assert result.support == (0,) + assert result.active_set == (0,) + + with pytest.raises(ValueError, match="at least one vertex"): + ellphi.tangency_simplex(np.empty((0, coefs.shape[1]))) + + +def test_non_convergence_raises_with_diagnostics(): + coefs = _random_coefs(5, 3, seed=101) + with pytest.raises(RuntimeError) as exc_info: + ellphi.tangency_simplex(coefs, method="fw+bisect", max_iter=1, tol=1e-15) + + message = str(exc_info.value) + assert "method='fw+bisect'" in message + assert "n_iter=1" in message + assert "diagnostics=" in message + + +@pytest.mark.parametrize( + "k,d,seed", + [(3, 2, 201), (3, 3, 202), (4, 2, 203), (4, 3, 204)], +) +def test_gradient_matches_normalisation_preserving_central_difference(k, d, seed): + rng = np.random.default_rng(seed) + centers = rng.uniform(-2.0, 2.0, size=(k, d)) + covariances = np.stack([random_covariance(rng, dim=d) for _ in range(k)]) + matrices = np.linalg.inv(covariances) + center_direction = rng.standard_normal(centers.shape) + matrix_direction = rng.standard_normal(matrices.shape) + matrix_direction = 0.5 * (matrix_direction + np.swapaxes(matrix_direction, -1, -2)) + + def packed_at(step): + shifted_centers = centers + step * center_direction + shifted_matrices = matrices + step * matrix_direction + return coef_from_cov(shifted_centers, np.linalg.inv(shifted_matrices)) + + solver_kwargs = { + "method": "fw+brentq+newton", + "tol": 1e-12, + "newton_tol": 1e-14, + } + coefs = packed_at(0.0) + gradient = ellphi.tangency_simplex_grad(coefs, **solver_kwargs) + h = 1e-6 + plus = packed_at(h) + minus = packed_at(-h) + finite_difference = ( + ellphi.tangency_simplex(plus, **solver_kwargs).t + - ellphi.tangency_simplex(minus, **solver_kwargs).t + ) / (2.0 * h) + coefficient_direction = (plus - minus) / (2.0 * h) + analytical = float(np.sum(gradient.dt_dcoef * coefficient_direction)) + + error = _relative_error(analytical, finite_difference) + assert error < 1e-6, f"k={k}, d={d}, relative error={error:.3e}" + + +def test_pairwise_gradient_identity(solver_backend, rng): + p, q = random_coef_pair(rng, dim=3) + gradient = ellphi.tangency_simplex_grad(np.stack((p, q))) + pairwise = ellphi.tangency_grad(p, q, backend=solver_backend) + + error_p = _relative_error(gradient.dt_dcoef[0], pairwise.dt_dp) + error_q = _relative_error(gradient.dt_dcoef[1], pairwise.dt_dq) + assert error_p < 1e-6, f"dt_dp relative error={error_p:.3e}" + assert error_q < 1e-6, f"dt_dq relative error={error_q:.3e}" + + +def test_zero_time_gradient_raises(): + coefs = coef_from_cov(np.array([[1.0, -2.0]]), np.eye(2)[None]) + with pytest.raises(ZeroDivisionError, match="t == 0"): + ellphi.tangency_simplex_grad(coefs) + + +@pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) +def test_unnormalized_constant_is_rejected(api): + coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + coefs[0, -1] += 1.0 + + with pytest.raises(ValueError, match=r"row 0.*coef_from_cov"): + api(coefs) + + +@pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) +@pytest.mark.parametrize("name", ["active_tol", "weight_tol", "norm_tol"]) +@pytest.mark.parametrize("value", [np.nan, -1.0]) +def test_simplex_tolerances_must_be_finite_and_nonnegative(api, name, value): + coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + + with pytest.raises(ValueError, match=f"{name} must be finite and non-negative"): + api(coefs, **{name: value}) + + +def test_public_namedtuple_field_order(): + assert ellphi.SimplexTangencyResult._fields == ( + "t", + "point", + "mu", + "support", + "active_set", + ) + assert ellphi.SimplexTangencyGrad._fields == ( + "t", + "point", + "mu", + "dt_dcoef", + "support", + "active_set", + ) + + +def test_public_exports_hide_internal_engine(): + expected = { + "SimplexTangencyResult", + "SimplexTangencyGrad", + "tangency_simplex", + "tangency_simplex_grad", + } + assert expected <= set(ellphi.__all__) + assert not { + "MinimaxResult", + "GradientResult", + "solve_minimax", + "solve_minimax_from_coefs", + "compute_gradient", + } & set(ellphi.__all__) + for name in ( + "MinimaxResult", + "GradientResult", + "solve_minimax", + "solve_minimax_from_coefs", + "compute_gradient", + ): + assert not hasattr(ellphi, name) From 50120234a79ca8d6a8b750e9ac121d284886d38d Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 21:52:43 +0900 Subject: [PATCH 04/29] feat: harden the many-body engine (Newton guard, general constant offsets) and add the public surrogate fixture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Squash of local topic branch project26-engine-hardening (7 commits) after two local Codex review rounds (gpt-5.6-sol, read-only): - round 1: REQUEST CHANGES — major: snapping roundoff-sized constants falsified the packed-coordinate gradient; major: negative engine value clipped to t=0 with inconsistent sets; minor: offsets not checked finite before the k==1 fast path; minor: incomplete deviation list; nits: empty face misreported, fixture provenance not reproducible. Fixed in e8a2660 (gpt-5.6-luna): exact offsets passed through, ValueError for negative values beyond roundoff, finite check, deviation list, empty_face status, generation recipe + regeneration test. - round 2: REQUEST CHANGES — major: negative tolerance rejected legitimate cancellation-scale values (centre (1e6,-1e6)); minor: post-polish Cholesky failure deviation missing. Fixed in cc61adc: cancellation bound value_roundoff = sum_i 64*eps*cond2(A_i)*max(|c_i|, |xbar_i^T A_i xbar_i|) carried from _prepare_coefs; deviation list completed; the 1e8 translated test rewritten to a well-scaled claim (packed constants carry roundoff of order eps*|xbar|^2; a representation limit, not a solver property). Two-round cap reached; dispositions recorded here; checklist re-run independently (481 passed). Engine deviations from ellcech 82d13e3 are enumerated in the module docstring: Armijo-rejected steps never applied (best iterate kept, converged=False), face re-identification after accepted steps, undamped Newton stops on ill-conditioned reduced Hessian, newton-cold falls back to a fresh FW iterate (converged=False), failure statuses force converged=False, post-polish Cholesky failure forces converged=False, full-step Armijo roundoff allowance, additive offsets (delta_i) with d alpha/d delta_i = mu_i. Fidelity: 3,048 legacy converged=True results over 480 instances identical to 1e-12 (scripts/compare_minimax_engine.py, opt-in). Public surrogate fixture (k=6, d=2, deterministic recipe) encodes the #27 mechanism: SLSQP meets value/gap bounds, every other method raises. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/many_body_tangency.md | 41 ++-- scripts/compare_minimax_engine.py | 259 +++++++++++++++++++++ src/ellphi/_minimax_grad_python.py | 20 +- src/ellphi/_minimax_grad_python.pyi | 1 + src/ellphi/_minimax_python.py | 336 +++++++++++++++++++++++----- src/ellphi/_minimax_python.pyi | 1 + src/ellphi/simplex.py | 121 +++++----- src/ellphi/simplex.pyi | 5 +- tests/factories.py | 57 +++++ tests/test_minimax.py | 63 ++++++ tests/test_minimax_grad.py | 53 +++++ tests/test_minimax_methods.py | 97 +++++++- tests/test_simplex.py | 210 ++++++++++++++--- 13 files changed, 1089 insertions(+), 175 deletions(-) create mode 100644 scripts/compare_minimax_engine.py diff --git a/docs/guide/many_body_tangency.md b/docs/guide/many_body_tangency.md index d177c8b..55cb9f3 100644 --- a/docs/guide/many_body_tangency.md +++ b/docs/guide/many_body_tangency.md @@ -23,32 +23,29 @@ raises `RuntimeError` with its diagnostics. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. -Every coefficient row must be a normalized conic. If `unpack_conic` returns -`(A_i, b_i, c_i)`, the required convention is -`b_i = -A_i xbar_i` and `c_i = xbar_i^T A_i xbar_i`, equivalently -`c_i = b_i^T A_i^{-1} b_i` within the maximum of -`norm_tol * max(1, abs(c_i))` and -`64 * eps * cond2(A_i) * max(1, abs(c_i), abs(b_i^T A_i^{-1} b_i))`, -where `eps` is machine epsilon and `norm_tol` defaults to `1e-9`. -`tangency_simplex` and `tangency_simplex_grad` reject an offending row with -`ValueError`; `ellphi.coef_from_cov` constructs coefficients in this form. +If `unpack_conic` returns `(A_i, b_i, c_i)`, the center is +`xbar_i = -A_i^{-1} b_i` and the completed-square constant is +`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this exactly +computed `delta_i` to the many-body engine, including when it is small, so +general independent constants are supported. + +A packed row encodes its constant as +`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1` or +ill-conditioned `A_i`, the representable `delta_i` carries roundoff of order +`eps * |xbar_i|^2`, with a `cond2(A_i)` factor for ill-conditioned matrices. +Callers needing exact normalization at large translations should center their +data first. Packed input requires `d >= 2`, as for `ellphi.tangency`; d=1 packed conics are not supported and raise `ValueError`. -The private engine reconstructs each center from `(A_i, b_i)` and ignores -`c_i` during optimization. Thus `tangency_simplex_grad(coefs)` returns -`dt_dcoef`, a coefficient-space covector whose contraction with a packed -direction is the derivative of `t` only for normalization-preserving -perturbations. For the upper-triangular packed basis +The many-body engine uses the completed-square offsets above. Thus +`tangency_simplex_grad(coefs)` returns `dt_dcoef`, the gradient for arbitrary +independent packed-coordinate perturbations, including the constant +component. For the upper-triangular packed basis `[x_i**2, 2*x_i*x_j (i < j), 2*x_i, 1]`, the formula is -`mu_i * basis(point) / (2*t)`. The constant-term component must be read in -this chain-rule sense, not as a derivative under an arbitrary independent -change to a packed constant. It assumes a non-degenerate input, at least two -indices in `active_set`, multipliers supported on `active_set`, and an exact -weighted linear solve. Convergence or a small residual alone is not a +`mu_i * basis(point) / (2*t)`. It assumes a non-degenerate input, at least +two indices in `active_set`, multipliers supported on `active_set`, and an +exact weighted linear solve. Convergence or a small residual alone is not a derivative certificate, and the gradient is undefined at `t == 0`. For far-translated inputs, the uncentred packed basis used by this derivative can be poorly conditioned. - -Support for general independent constants inside the minimax solve is planned -engine work; it is not part of this wrapper contract. diff --git a/scripts/compare_minimax_engine.py b/scripts/compare_minimax_engine.py new file mode 100644 index 0000000..c506a64 --- /dev/null +++ b/scripts/compare_minimax_engine.py @@ -0,0 +1,259 @@ +"""Compare the private minimax engine with its ellcech source revision. + +This is an opt-in fidelity check, not part of the default pytest run. Generate +the shared inputs and the two engine records in separate processes, then +compare them:: + + uv run --no-sync python scripts/compare_minimax_engine.py \ + inputs --output /tmp/minimax-inputs.json + /path/to/ellcech/.venv/bin/python scripts/compare_minimax_engine.py \ + generate --engine legacy --revision 82d13e3 \ + --inputs /tmp/minimax-inputs.json --output /tmp/legacy.json + /path/to/ellcech/.venv/bin/python scripts/compare_minimax_engine.py \ + generate --engine candidate --revision HEAD \ + --source-root . --inputs /tmp/minimax-inputs.json \ + --output /tmp/candidate.json + uv run --no-sync python scripts/compare_minimax_engine.py \ + compare /tmp/legacy.json /tmp/candidate.json + +Only cases for which the legacy engine reports ``converged=True`` are fidelity +requirements. Alpha, circumcenter, and weights must then agree absolutely to +``1e-12``, and the candidate must also report convergence. +""" + +from __future__ import annotations + +import argparse +import hashlib +import json +import platform +import sys +from pathlib import Path +from typing import Any, Callable + +import numpy as np + + +METHODS = ( + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", +) +BASE_SEED = 260_027 +INSTANCES_PER_SHAPE = 20 +FIDELITY_ATOL = 1e-12 + + +def _solver(engine: str, source_root: Path | None) -> Callable[..., Any]: + if engine == "legacy": + from ellphi_alpha.minimax import solve_minimax + else: + if source_root is not None: + sys.path.insert(0, str(source_root.resolve() / "src")) + from ellphi._minimax_python import solve_minimax + + return solve_minimax + + +def _random_instance(k: int, d: int, instance: int) -> tuple[np.ndarray, np.ndarray]: + rng = np.random.default_rng(np.random.SeedSequence([BASE_SEED, k, d, instance])) + matrices = [] + for _ in range(k): + q, _ = np.linalg.qr(rng.standard_normal((d, d))) + eigenvalues = np.exp(rng.uniform(-1.0, 1.0, d)) + matrix = (q * eigenvalues) @ q.T + matrices.append(0.5 * (matrix + matrix.T)) + return np.stack(matrices), rng.standard_normal((k, d)) + + +def make_inputs(output: Path) -> None: + """Write the exact deterministic inputs shared by both implementations.""" + instances = [] + for k in range(1, 7): + for d in range(1, 5): + for instance in range(INSTANCES_PER_SHAPE): + matrices, centers = _random_instance(k, d, instance) + instances.append( + { + "k": k, + "d": d, + "instance": instance, + "matrices": matrices.tolist(), + "centers": centers.tolist(), + } + ) + payload = { + "base_seed": BASE_SEED, + "instances_per_shape": INSTANCES_PER_SHAPE, + "instances": instances, + } + output.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n") + print(f"wrote {len(instances)} inputs to {output}") + + +def _sha256(path: Path) -> str: + return hashlib.sha256(path.read_bytes()).hexdigest() + + +def generate( + engine: str, + revision: str, + inputs: Path, + output: Path, + source_root: Path | None, +) -> None: + """Generate deterministic solver records for one implementation.""" + solve_minimax = _solver(engine, source_root) + input_payload = json.loads(inputs.read_text()) + records = [] + for item in input_payload["instances"]: + matrices = np.asarray(item["matrices"], dtype=float) + centers = np.asarray(item["centers"], dtype=float) + for method in METHODS: + result = solve_minimax(matrices, centers, method=method) + records.append( + { + "k": item["k"], + "d": item["d"], + "instance": item["instance"], + "method": method, + "alpha": result.alpha, + "circumcenter": result.circumcenter.tolist(), + "weights": result.weights.tolist(), + "converged": result.converged, + } + ) + + payload = { + "manifest": { + "engine": engine, + "revision": revision, + "source_root": str(source_root.resolve()) if source_root else None, + "entry_point": "scripts/compare_minimax_engine.py generate", + "configuration": { + "methods": METHODS, + "k": [1, 6], + "d": [1, 4], + "instances_per_shape": INSTANCES_PER_SHAPE, + }, + "random_seed": BASE_SEED, + "input_identity": { + "path": str(inputs), + "sha256": _sha256(inputs), + "generator": "SeedSequence([base_seed, k, d, instance])", + }, + "output": str(output), + "execution_backend": "local Python/NumPy/SciPy", + "python": platform.python_version(), + "numpy": np.__version__, + "fallback_status": "not-applicable", + "status": "complete", + }, + "records": records, + } + output.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n") + print(f"wrote {len(records)} records to {output}") + + +def _record_key(record: dict[str, Any]) -> tuple[int, int, int, str]: + return ( + record["k"], + record["d"], + record["instance"], + record["method"], + ) + + +def compare(legacy_path: Path, candidate_path: Path) -> int: + """Compare candidate outputs where the legacy engine converged.""" + legacy_payload = json.loads(legacy_path.read_text()) + candidate_payload = json.loads(candidate_path.read_text()) + legacy = {_record_key(record): record for record in legacy_payload["records"]} + candidate = {_record_key(record): record for record in candidate_payload["records"]} + if legacy.keys() != candidate.keys(): + missing = sorted(legacy.keys() - candidate.keys()) + extra = sorted(candidate.keys() - legacy.keys()) + raise ValueError( + f"record-key mismatch: missing={missing[:3]}, extra={extra[:3]}" + ) + + converged = 0 + mismatches = [] + converged_by_method = {method: 0 for method in METHODS} + for key, old in legacy.items(): + if not old["converged"]: + continue + converged += 1 + converged_by_method[key[-1]] += 1 + new = candidate[key] + same = ( + new["converged"] + and abs(new["alpha"] - old["alpha"]) <= FIDELITY_ATOL + and np.allclose( + new["circumcenter"], + old["circumcenter"], + rtol=0.0, + atol=FIDELITY_ATOL, + ) + and np.allclose( + new["weights"], old["weights"], rtol=0.0, atol=FIDELITY_ATOL + ) + ) + if not same: + mismatches.append(key) + + summary = { + "records_compared": len(legacy), + "legacy_converged": converged, + "legacy_converged_by_method": converged_by_method, + "mismatches": len(mismatches), + "first_mismatches": mismatches[:10], + "atol": FIDELITY_ATOL, + "status": "complete" if not mismatches else "failed", + } + print(json.dumps(summary, indent=2, sort_keys=True)) + return 1 if mismatches else 0 + + +def main() -> int: + parser = argparse.ArgumentParser() + subparsers = parser.add_subparsers(dest="command", required=True) + + inputs_parser = subparsers.add_parser("inputs") + inputs_parser.add_argument("--output", type=Path, required=True) + + generate_parser = subparsers.add_parser("generate") + generate_parser.add_argument( + "--engine", choices=("legacy", "candidate"), required=True + ) + generate_parser.add_argument("--revision", required=True) + generate_parser.add_argument("--source-root", type=Path) + generate_parser.add_argument("--inputs", type=Path, required=True) + generate_parser.add_argument("--output", type=Path, required=True) + + compare_parser = subparsers.add_parser("compare") + compare_parser.add_argument("legacy", type=Path) + compare_parser.add_argument("candidate", type=Path) + + args = parser.parse_args() + if args.command == "inputs": + make_inputs(args.output) + return 0 + if args.command == "generate": + generate( + args.engine, + args.revision, + args.inputs, + args.output, + args.source_root, + ) + return 0 + return compare(args.legacy, args.candidate) + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/src/ellphi/_minimax_grad_python.py b/src/ellphi/_minimax_grad_python.py index fc4920b..727b915 100644 --- a/src/ellphi/_minimax_grad_python.py +++ b/src/ellphi/_minimax_grad_python.py @@ -8,7 +8,9 @@ ebe63a42060ac6420ad42d90b3ffe942969d54ec) is documentation-only. This docstring is written for EllPHi rather than copied from either revision: it adopts the ebe63a4 remark that zero weights give zero gradient blocks, but -not its characterization of differentiability. The code is unchanged. +not its characterization of differentiability. EllPHi adds the offset +gradient ``d alpha / d delta_i = mu_i``; the original center and matrix +gradient code is unchanged. Distributed as part of EllPHi under its MIT license; the ellcech source is MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. @@ -23,6 +25,7 @@ d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*) d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*) + d alpha / d delta_i = mu_i with centers ``xbar_i`` and matrices ``A_i`` treated as independent parameters. For ``k = 2`` these are the pairwise gradients of ``t ** 2``. @@ -74,6 +77,8 @@ class GradientResult: of shape ``(d,)`` per vertex. d_A: Gradients with respect to the matrices ``A_i``, one symmetric array of shape ``(d, d)`` per vertex. + d_offsets: Gradient with respect to additive offsets ``delta_i``, + shape ``(k,)``. alpha: The filtration value from the forward pass. circumcenter: The circumcenter ``x*`` from the forward pass. weights: The weights ``mu`` from the forward pass. @@ -81,6 +86,7 @@ class GradientResult: d_xbar: list[np.ndarray] d_A: list[np.ndarray] + d_offsets: np.ndarray alpha: float circumcenter: np.ndarray weights: np.ndarray @@ -93,10 +99,10 @@ def compute_gradient( ) -> GradientResult: """Evaluate the envelope-theorem gradient of ``alpha`` at a solver result. - Computes ``d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*)`` and - ``d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*)``. See the module - docstring for the hypotheses under which these approximate the true - gradient. + Computes ``d alpha / d xbar_i = 2 mu_i A_i (xbar_i - x*)``, + ``d alpha / d A_i = mu_i outer(xbar_i - x*, xbar_i - x*)``, and + ``d alpha / d delta_i = mu_i``. See the module docstring for the hypotheses + under which these approximate the true gradient. Args: result: A MinimaxResult from @@ -106,7 +112,8 @@ def compute_gradient( matrices: SPD matrices ``A_i``, shape ``(k, d, d)``. Returns: - GradientResult with ``d_xbar`` and ``d_A`` lists of length ``k``. + GradientResult with ``d_xbar`` and ``d_A`` lists of length ``k`` and + ``d_offsets`` of shape ``(k,)``. Raises: ValueError: If the shapes of ``centers``, ``matrices`` and @@ -152,6 +159,7 @@ def compute_gradient( return GradientResult( d_xbar=d_xbar, d_A=d_A, + d_offsets=mu.copy(), alpha=result.alpha, circumcenter=xstar.copy(), weights=mu.copy(), diff --git a/src/ellphi/_minimax_grad_python.pyi b/src/ellphi/_minimax_grad_python.pyi index b07e637..5249e81 100644 --- a/src/ellphi/_minimax_grad_python.pyi +++ b/src/ellphi/_minimax_grad_python.pyi @@ -14,6 +14,7 @@ __all__ = [ class GradientResult: d_xbar: list[np.ndarray] d_A: list[np.ndarray] + d_offsets: np.ndarray alpha: float circumcenter: np.ndarray weights: np.ndarray diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index cb4c2cd..dde0fae 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -5,14 +5,40 @@ Adapted from uda-lab/ellcech ``src/ellphi_alpha/minimax.py`` at commit 82d13e3e174f4903cdcd6adcee1f469348361c91, by Tomoki Uda (the author of EllPHi). That file is byte-identical at ellcech ``main`` -893056409db56865b7432274562db2d863e0abce. Numerical behaviour, method -strings, defaults and tolerances are kept unchanged; the changes are -packaging-level only (intra-package import of ``unpack_conic``, type -annotations, documentation). Distributed as part of EllPHi under its MIT -license; the ellcech source is MIT by owner decision -(uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. The docstring -corrections in items 1–3 deliberately deviate from the ellcech 82d13e3 -docstrings; code paths are unchanged. +893056409db56865b7432274562db2d863e0abce. This engine deliberately deviates +from ellcech 82d13e3 in the following ways: + +* Armijo-rejected Newton steps are never applied. The best iterate by dual + value is retained, the status is ``"armijo_rejected"``, and + ``converged=False``. +* After an accepted warm-start Newton step, the weight-thresholded face is + re-identified before the next step; the cold-start baseline keeps its full + initial face during Newton. +* Undamped Newton polishing stops when the reduced Hessian is ill-conditioned + beyond the configured limit, with status ``"ill_conditioned_hessian"``. + Damped Newton uses diagonal regularization at that threshold instead. +* ``newton-cold`` starts at the uniform weights. If Newton does not converge, + it falls back to a freshly run ``fw+bisect`` iterate from that same uniform + start and explicitly reports ``converged=False``. +* Newton failure statuses force ``converged=False``; these statuses are + ``"empty_face"``, ``"armijo_rejected"``, ``"factorization_failed"``, + ``"ill_conditioned_hessian"``, ``"linear_solve_failed"``, + ``"nonfinite_residual"``, ``"nonfinite_step"``, and + ``"projection_failed"``. A full Newton step may additionally be accepted + for roundoff when + ``g_trial + 8 * eps * max(1, abs(g_current), abs(g_trial), + abs(armijo_target)) >= armijo_target``; this allowance applies only to the + unbacktracked full step. +* The objective supports additive per-constraint offsets, including general + packed conic constants. +* A post-polish Cholesky factorization failure forces ``converged=False``; + ellcech 82d13e3 preserved the prior convergence flag in this case. + +The list above exhausts numerical and solver-behavior deviations from ellcech. +The remaining differences are packaging-only (the intra-package import of +``unpack_conic`` and type annotations) or documentation. Distributed as part +of EllPHi under its MIT license; the ellcech source is MIT by owner decision +(uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. This numerical engine is internal. The provisional public interface is :mod:`ellphi.simplex`. @@ -20,9 +46,10 @@ Mathematical background ----------------------- Given vertices ``i = 0, ..., k-1`` with centers ``x_i`` in R^d and SPD -matrices ``A_i``, the exact filtration value is +matrices ``A_i`` and offsets ``delta_i``, the exact filtration value is - alpha = min_x max_i f_i(x), f_i(x) = (x - x_i)^T A_i (x - x_i). + alpha = min_x max_i f_i(x), + f_i(x) = (x - x_i)^T A_i (x - x_i) + delta_i. ``alpha`` is a *squared* scale. In the pairwise case ``k = 2`` the exact value equals ``ellphi.tangency(p, q).t ** 2``; the tangency time is @@ -38,7 +65,8 @@ A(mu) = sum_i mu_i A_i b(mu) = sum_i mu_i A_i x_i - g(mu) = sum_i mu_i x_i^T A_i x_i - b(mu)^T A(mu)^{-1} b(mu) + g(mu) = sum_i mu_i (x_i^T A_i x_i + delta_i) + - b(mu)^T A(mu)^{-1} b(mu) = sum_i mu_i f_i(x*(mu)), where ``x*(mu) = A(mu)^{-1} b(mu)`` is the circumcenter. The dual gradient is @@ -75,7 +103,8 @@ with different result contracts. Packed coefficients store the linear term as ``b = -A x_bar``, so the center -is ``x_bar = -A^{-1} b``; :func:`solve_minimax_from_coefs` handles this. +is ``x_bar = -A^{-1} b`` and ``delta = c - x_bar^T A x_bar``; +:func:`solve_minimax_from_coefs` handles both conversions. """ from __future__ import annotations @@ -114,6 +143,7 @@ _NEWTON_TOL = 1e-14 _NEWTON_MAX_ITER = 20 +_NEWTON_HESSIAN_COND_LIMIT = 1e12 # Brentq line search constants (analogous to ellphi _DEFAULT_HYBRID_BRACKET_MAXITER) _DEFAULT_BRENTQ_MAXITER = 28 @@ -264,6 +294,7 @@ def _eval_f( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, *, regularization: float, condition_number_limit: float | None, @@ -284,6 +315,8 @@ def _eval_f( ) diff = xstar[np.newaxis, :] - centers f = np.einsum("ki,kij,kj->k", diff, matrices, diff) + if offsets is not None: + f = f + offsets return xstar, f @@ -294,6 +327,7 @@ def _exact_line_search( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, gamma_max: float, *, regularization: float, @@ -317,6 +351,7 @@ def h(gamma: float) -> float: matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -355,6 +390,7 @@ def _brentq_line_search( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, gamma_max: float, *, regularization: float, @@ -381,6 +417,7 @@ def h(gamma: float) -> float: matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -428,6 +465,7 @@ def _run_fw_bisect( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, mu: np.ndarray, *, tol: float, @@ -451,6 +489,7 @@ def _run_fw_bisect( matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -478,6 +517,7 @@ def _run_fw_bisect( matrices, Ax, centers, + offsets, gamma_max, regularization=regularization, condition_number_limit=condition_number_limit, @@ -497,6 +537,7 @@ def _run_fw_brentq( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, mu: np.ndarray, *, tol: float, @@ -522,6 +563,7 @@ def _run_fw_brentq( matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -550,6 +592,7 @@ def _run_fw_brentq( matrices, Ax, centers, + offsets, gamma_max, regularization=regularization, condition_number_limit=condition_number_limit, @@ -596,10 +639,12 @@ def _newton_polish( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, *, + weight_tol: float = _DEFAULT_WEIGHT_TOL, max_iter: int = _NEWTON_MAX_ITER, tol: float = _NEWTON_TOL, -) -> tuple[np.ndarray, int]: +) -> tuple[np.ndarray, int, dict]: """Newton polishing on the dual restricted to the current active face. Solves the KKT conditions r_l = f_{i_l}(x*) - f_{i_{m-1}}(x*) = 0 @@ -612,16 +657,44 @@ def _newton_polish( followed by simplex projection. Returns: - (mu, n_iter): Updated weights and number of Newton steps performed. + Updated weights, number of Newton steps, and diagnostics. """ m = len(active_set) + if m == 0: + return ( + mu, + 0, + { + "newton_iters": 0, + "hessian_cond": 0.0, + "newton_status": "empty_face", + }, + ) if m <= 1: - return mu, 0 + return ( + mu, + 0, + { + "newton_iters": 0, + "hessian_cond": 0.0, + "newton_status": "singleton_face", + }, + ) mu = mu.copy() n_iter = 0 + max_hessian_cond = 0.0 + newton_status = "max_iter" for n_iter in range(1, max_iter + 1): + m = len(active_set) + if m == 0: + newton_status = "empty_face" + break + if m <= 1: + newton_status = "singleton_face" + break + A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) @@ -631,14 +704,18 @@ def _newton_polish( d = A_mu.shape[0] Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) except linalg.LinAlgError: + newton_status = "factorization_failed" break diff = xstar[np.newaxis, :] - centers[active_set] # (m, d) f = np.einsum("ki,kij,kj->k", diff, matrices[active_set], diff) # (m,) + if offsets is not None: + f = f + offsets[active_set] # Residual: r_l = f_{i_l} - f_{i_{m-1}} r = f[:-1] - f[-1] # (m-1,) if float(np.max(np.abs(r))) < tol: + newton_status = "converged" break neg_H = _hessian_g_negative( @@ -650,9 +727,16 @@ def _newton_polish( neg_H[:-1, :-1] - neg_H[:-1, -1:] - neg_H[-1:, :-1] + neg_H[-1, -1] ) # (m-1, m-1) + hess_cond = float(np.linalg.cond(neg_H_r)) + max_hessian_cond = max(max_hessian_cond, hess_cond) + if not np.isfinite(hess_cond) or hess_cond > _NEWTON_HESSIAN_COND_LIMIT: + newton_status = "ill_conditioned_hessian" + break + try: delta = np.linalg.solve(neg_H_r, r) except np.linalg.LinAlgError: + newton_status = "linear_solve_failed" break mu_new = mu.copy() @@ -664,11 +748,18 @@ def _newton_polish( mu_new = np.clip(mu_new, 0.0, None) s = mu_new.sum() if s <= 0.0: + newton_status = "projection_failed" break mu_new /= s mu = mu_new + active_set = [i for i in range(len(mu)) if mu[i] > weight_tol] - return mu, n_iter + metadata = { + "newton_iters": n_iter, + "hessian_cond": max_hessian_cond, + "newton_status": newton_status, + } + return mu, n_iter, metadata def _damped_newton_polish( @@ -677,7 +768,10 @@ def _damped_newton_polish( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, *, + weight_tol: float = _DEFAULT_WEIGHT_TOL, + reidentify_face: bool = True, max_iter: int = _NEWTON_MAX_ITER, tol: float = _NEWTON_TOL, ) -> tuple[np.ndarray, int, dict]: @@ -692,14 +786,46 @@ def _damped_newton_polish( (mu, n_iter, metadata) """ m = len(active_set) + if m == 0: + return ( + mu, + 0, + { + "newton_iters": 0, + "hessian_cond": 0.0, + "newton_status": "empty_face", + }, + ) if m <= 1: - return mu, 0, {"newton_iters": 0, "hessian_cond": 0.0} + return ( + mu, + 0, + { + "newton_iters": 0, + "hessian_cond": 0.0, + "newton_status": "singleton_face", + }, + ) mu = mu.copy() + best_mu = mu.copy() + best_g = -np.inf n_iter = 0 max_hessian_cond = 0.0 + newton_status = "max_iter" + rejected_step_diagnostics: dict[str, float] = {} + roundoff_accepts = 0 + max_armijo_roundoff_shortfall = 0.0 for n_iter in range(1, max_iter + 1): + m = len(active_set) + if m == 0: + newton_status = "empty_face" + break + if m <= 1: + newton_status = "singleton_face" + break + A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) @@ -709,18 +835,23 @@ def _damped_newton_polish( d = A_mu.shape[0] Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) except linalg.LinAlgError: + newton_status = "factorization_failed" break diff = xstar[np.newaxis, :] - centers[active_set] f = np.einsum("ki,kij,kj->k", diff, matrices[active_set], diff) + if offsets is not None: + f = f + offsets[active_set] # Residual r = f[:-1] - f[-1] try: _ensure_finite(float(np.max(np.abs(r))), "Newton residual") except RuntimeError: + newton_status = "nonfinite_residual" break if float(np.max(np.abs(r))) < tol: + newton_status = "converged" break neg_H = _hessian_g_negative(active_set, xstar, matrices, Amu_inv, centers) @@ -730,7 +861,7 @@ def _damped_newton_polish( # Conditioning check hess_cond = float(np.linalg.cond(neg_H_r)) max_hessian_cond = max(max_hessian_cond, hess_cond) - if hess_cond > 1e12: + if hess_cond > _NEWTON_HESSIAN_COND_LIMIT: # Diagonal regularization reg = float(np.trace(neg_H_r)) / neg_H_r.shape[0] * 1e-10 reg = max(reg, 1e-14) @@ -739,9 +870,11 @@ def _damped_newton_polish( try: delta = np.linalg.solve(neg_H_r, r) except np.linalg.LinAlgError: + newton_status = "linear_solve_failed" break if not np.all(np.isfinite(delta)): + newton_status = "nonfinite_step" break # Current objective: g(mu) = dot(mu, f_full) @@ -750,16 +883,20 @@ def _damped_newton_polish( matrices, Ax, centers, + offsets, regularization=0.0, condition_number_limit=None, max_conditioning_steps=0, ) g_current = float(np.dot(mu, f_full)) + if g_current > best_g: + best_g = g_current + best_mu = mu.copy() # Armijo backtracking step = 1.0 accepted = False - for _ in range(_ARMIJO_MAX_BACKTRACK): + for backtrack in range(_ARMIJO_MAX_BACKTRACK): mu_trial = mu.copy() for pos, idx in enumerate(active_set[:-1]): mu_trial[idx] += step * delta[pos] @@ -778,36 +915,61 @@ def _damped_newton_polish( matrices, Ax, centers, + offsets, regularization=0.0, condition_number_limit=None, max_conditioning_steps=0, ) g_trial = float(np.dot(mu_trial, f_trial)) + armijo_target = g_current + _ARMIJO_SIGMA * step * float(r @ delta) + armijo_roundoff = ( + 8.0 + * np.finfo(float).eps + * max(1.0, abs(g_current), abs(g_trial), abs(armijo_target)) + ) + if backtrack == 0: + rejected_step_diagnostics = { + "armijo_g_current": g_current, + "armijo_full_step_g": g_trial, + "armijo_full_step_target": armijo_target, + "armijo_residual": float(np.max(np.abs(r))), + } # Armijo sufficient increase (maximizing g) - if g_trial >= g_current + _ARMIJO_SIGMA * step * float(r @ delta): + roundoff_accepted = ( + backtrack == 0 and g_trial + armijo_roundoff >= armijo_target + ) + if g_trial >= armijo_target or roundoff_accepted: + if roundoff_accepted and g_trial < armijo_target: + roundoff_accepts += 1 + max_armijo_roundoff_shortfall = max( + max_armijo_roundoff_shortfall, armijo_target - g_trial + ) mu = mu_trial + if g_trial > best_g: + best_g = g_trial + best_mu = mu.copy() accepted = True break step *= _ARMIJO_BETA if not accepted: - # Accept full step anyway (like undamped Newton) - mu_new = mu.copy() - for pos, idx in enumerate(active_set[:-1]): - mu_new[idx] += delta[pos] - mu_new[active_set[-1]] -= float(delta.sum()) - mu_new = np.clip(mu_new, 0.0, None) - s = mu_new.sum() - if s <= 0.0: - break - mu_new /= s - mu = mu_new + newton_status = "armijo_rejected" + mu = best_mu + break + + if reidentify_face: + active_set = [i for i in range(len(mu)) if mu[i] > weight_tol] metadata = { "newton_iters": n_iter, "hessian_cond": max_hessian_cond, + "newton_status": newton_status, + "armijo_roundoff_accepts": roundoff_accepts, + "armijo_roundoff_shortfall": max_armijo_roundoff_shortfall, } + if newton_status == "armijo_rejected": + metadata.update(rejected_step_diagnostics) return mu, n_iter, metadata @@ -820,6 +982,7 @@ def _run_scipy_slsqp( matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, k: int, *, regularization: float, @@ -842,6 +1005,7 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -877,33 +1041,51 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: def _check_newton_convergence( mu: np.ndarray, - active_set_fw: list[int], + active_set: list[int], matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, + offsets: np.ndarray | None, converged: bool, newton_tol: float, + newton_status: str, ) -> bool: """Recheck convergence after Newton polishing.""" - if len(active_set_fw) <= 1: - return converged + failure_statuses = { + "empty_face", + "armijo_rejected", + "factorization_failed", + "ill_conditioned_hessian", + "linear_solve_failed", + "nonfinite_residual", + "nonfinite_step", + "projection_failed", + } + if not converged or newton_status in failure_statuses: + return False try: A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) chol = linalg.cho_factor(A_mu, check_finite=False) xstar_check = linalg.cho_solve(chol, b_mu, check_finite=False) - d_check = xstar_check[np.newaxis, :] - centers[active_set_fw] - f_check = np.einsum("ki,kij,kj->k", d_check, matrices[active_set_fw], d_check) - r_check = f_check[:-1] - f_check[-1] - return converged and float(np.max(np.abs(r_check))) < newton_tol * 1e4 + d_check = xstar_check[np.newaxis, :] - centers + f_check = np.einsum("ki,kij,kj->k", d_check, matrices, d_check) + if offsets is not None: + f_check = f_check + offsets + if len(active_set) <= 1: + return True + f_active = f_check[active_set] + r_check = f_active[:-1] - f_active[-1] + return float(np.max(np.abs(r_check))) < newton_tol * 1e4 except linalg.LinAlgError: - return converged + return False def solve_minimax( matrices: np.ndarray, centers: np.ndarray, *, + offsets: np.ndarray | None = None, method: MethodName | str = "fw+bisect", tol: float = _DEFAULT_TOL, max_iter: int = _DEFAULT_MAX_ITER, @@ -943,6 +1125,8 @@ def solve_minimax( a single vertex. centers: Centers ``x_i``, shape ``(k, d)``, or ``(d,)`` for a single vertex. + offsets: Optional additive constants ``delta_i``, shape ``(k,)``. + ``None`` is the original zero-offset problem. method: One of the seven canonical method names above. tol: Frank-Wolfe gap tolerance for the FW-based methods. max_iter: Maximum number of Frank-Wolfe iterations. @@ -969,7 +1153,7 @@ def solve_minimax( ``condition_number_limit is None``), and the stabilised problem otherwise; in the pairwise case the exact value is ``ellphi.tangency(p, q).t ** 2``. For ``k = 1`` the result is the - trivial ``alpha = 0`` at the center. + trivial ``alpha = delta_0`` at the center. Raises: ValueError: For an unknown method, an empty simplex or invalid @@ -1006,11 +1190,17 @@ def solve_minimax( if k == 0: raise ValueError("simplex must contain at least one vertex (k=0 given)") + if offsets is not None: + offsets = np.asarray(offsets, dtype=float) + if offsets.shape != (k,): + raise ValueError(f"offsets shape {offsets.shape} inconsistent with k={k}") + if not np.all(np.isfinite(offsets)): + raise ValueError("offsets must be finite") # --- Trivial case: single point --- if k == 1: return MinimaxResult( - alpha=0.0, + alpha=0.0 if offsets is None else float(offsets[0]), circumcenter=centers[0].copy(), weights=np.array([1.0]), active_set=[0], @@ -1039,46 +1229,51 @@ def solve_minimax( # --- Dispatch --- if method == "fw+bisect": mu, converged, n_iter = _run_fw_bisect( - matrices, Ax, centers, mu_init, **_fw_kwargs + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata["fw_iters"] = n_iter elif method == "fw+brentq": mu, converged, n_iter, meta_fw = _run_fw_brentq( - matrices, Ax, centers, mu_init, **_fw_kwargs + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata.update(meta_fw) elif method == "fw+bisect+newton": mu, converged, n_iter_fw = _run_fw_bisect( - matrices, Ax, centers, mu_init, **_fw_kwargs + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) active_set_fw = [i for i in range(k) if mu[i] > weight_tol] - mu, n_iter_newton = _newton_polish( + mu, n_iter_newton, meta_newton = _newton_polish( mu, active_set_fw, matrices, Ax, centers, + offsets, + weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, ) n_iter = n_iter_fw + n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_fw, + active_set_newton, matrices, Ax, centers, + offsets, converged, newton_tol, + meta_newton["newton_status"], ) metadata["fw_iters"] = n_iter_fw - metadata["newton_iters"] = n_iter_newton + metadata.update(meta_newton) elif method == "fw+brentq+newton": mu, converged, n_iter_fw, meta_fw = _run_fw_brentq( - matrices, Ax, centers, mu_init, **_fw_kwargs + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( @@ -1087,25 +1282,30 @@ def solve_minimax( matrices, Ax, centers, + offsets, + weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, ) n_iter = n_iter_fw + n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_fw, + active_set_newton, matrices, Ax, centers, + offsets, converged, newton_tol, + meta_newton["newton_status"], ) metadata.update(meta_fw) metadata.update(meta_newton) elif method == "fw+bisect+damped-newton": mu, converged, n_iter_fw = _run_fw_bisect( - matrices, Ax, centers, mu_init, **_fw_kwargs + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( @@ -1114,18 +1314,23 @@ def solve_minimax( matrices, Ax, centers, + offsets, + weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, ) n_iter = n_iter_fw + n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_fw, + active_set_newton, matrices, Ax, centers, + offsets, converged, newton_tol, + meta_newton["newton_status"], ) metadata["fw_iters"] = n_iter_fw metadata.update(meta_newton) @@ -1139,19 +1344,32 @@ def solve_minimax( matrices, Ax, centers, + offsets, + weight_tol=weight_tol, + reidentify_face=False, max_iter=newton_max_iter, tol=newton_tol, ) n_iter = n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_cold, + active_set_newton, matrices, Ax, centers, + offsets, True, newton_tol, + meta_newton["newton_status"], ) + if not converged: + mu, _, n_iter_fw = _run_fw_bisect( + matrices, Ax, centers, offsets, mu_init, **_fw_kwargs + ) + n_iter += n_iter_fw + meta_newton["fallback_method"] = "fw+bisect" + meta_newton["fallback_fw_iters"] = n_iter_fw metadata.update(meta_newton) elif method == "scipy-slsqp": @@ -1159,6 +1377,7 @@ def solve_minimax( matrices, Ax, centers, + offsets, k, regularization=regularization, condition_number_limit=condition_number_limit, @@ -1172,6 +1391,7 @@ def solve_minimax( matrices, Ax, centers, + offsets, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1199,12 +1419,14 @@ def solve_minimax_from_coefs( ) -> MinimaxResult: """Convenience wrapper: accept ellphi packed conic coefficient vectors. - Converts ellphi's packed representation (A, b_ellphi, c) to (A_i, x_bar_i) - and calls solve_minimax. + Converts ellphi's packed representation (A, b_ellphi, c) to + (A_i, x_bar_i, delta_i) and calls solve_minimax. Sign convention: ellphi stores ``b_ellphi = -A x_bar`` (linear term of ``x^T A x + 2 b^T x + c``), so ``x_bar = -A^{-1} b_ellphi``. + Completing the square gives + ``delta = c - x_bar^T A x_bar``. Value correspondence: In the pairwise case ``result.alpha`` approximates @@ -1226,7 +1448,7 @@ def solve_minimax_from_coefs( if coefs.ndim == 1: coefs = coefs[np.newaxis] - A_arr, b_arr, _ = unpack_conic(coefs) # (k,d,d), (k,d), (k,) + A_arr, b_arr, c_arr = unpack_conic(coefs) # (k,d,d), (k,d), (k,) # x_bar_i = -A_i^{-1} b_i (ellphi sign convention: b = -A x_bar) k = A_arr.shape[0] @@ -1234,4 +1456,6 @@ def solve_minimax_from_coefs( for i in range(k): centers[i] = _exact_linear_solve(A_arr[i], -b_arr[i]) - return solve_minimax(A_arr, centers, **kwargs) + centered_constants = np.einsum("ki,kij,kj->k", centers, A_arr, centers) + offsets = c_arr - centered_constants + return solve_minimax(A_arr, centers, offsets=offsets, **kwargs) diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index 3668751..39c3641 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -33,6 +33,7 @@ def solve_minimax( matrices: np.ndarray, centers: np.ndarray, *, + offsets: np.ndarray | None = None, method: MethodName | str = "fw+bisect", tol: float = 1e-09, max_iter: int = 2000, diff --git a/src/ellphi/simplex.py b/src/ellphi/simplex.py index 74d081c..7a76429 100644 --- a/src/ellphi/simplex.py +++ b/src/ellphi/simplex.py @@ -11,7 +11,7 @@ import numpy as np -from ._minimax_python import MethodName, solve_minimax_from_coefs +from ._minimax_python import MethodName, solve_minimax from .geometry import unpack_conic __all__ = [ @@ -22,7 +22,7 @@ ] -_NORMALIZATION_ROUNDING_FACTOR = 64.0 +_NEGATIVE_ALPHA_ROUNDING_FACTOR = 64.0 _MACHINE_EPSILON = np.finfo(float).eps @@ -66,8 +66,8 @@ class SimplexTangencyGrad(NamedTuple): t: Tangency time. point: Tangency point, shape ``(d,)``. mu: Simplex multipliers, shape ``(k,)``. - dt_dcoef: Gradient of ``t`` for normalization-preserving packed - coefficient perturbations, shape ``(k, m)``. + dt_dcoef: Gradient of ``t`` for independent packed coefficient + perturbations, shape ``(k, m)``. support: Indices with multiplier greater than ``weight_tol``. active_set: Tight constraints at ``point`` under ``active_tol``. """ @@ -97,49 +97,59 @@ def _validate_tolerance(name: str, value: float) -> None: raise ValueError(f"{name} must be finite and non-negative") -def _validate_normalized_coefs( - coefs: np.ndarray, norm_tol: float -) -> tuple[np.ndarray, np.ndarray]: - """Validate the normalized conic identity used by the private engine.""" +def _prepare_coefs( + coefs: np.ndarray, +) -> tuple[np.ndarray, np.ndarray, np.ndarray, float]: + """Reconstruct centers and preserve exact completed-square offsets. + + A packed row encodes the constant as + ``c = xbar.T @ A @ xbar + delta``. Computing ``delta`` from a + far-translated or ill-conditioned row can therefore lose precision of + order ``eps * cond2(A) * max(abs(c), abs(xbar.T @ A @ xbar))``. The + returned ``value_roundoff`` is the sum of these per-row bounds; callers + needing exact normalization at large translations should center their data + first. + """ matrices, linear, constants = unpack_conic(coefs) centers = np.empty_like(linear) + offsets = np.empty_like(constants) + value_roundoff = 0.0 for row, (matrix, vector, constant) in enumerate(zip(matrices, linear, constants)): try: inverse_times_linear = np.linalg.solve(matrix, vector) except np.linalg.LinAlgError as exc: raise ValueError( - f"coefficient row {row} is not a normalised conic; use " - "ellphi.coef_from_cov for normalised conics" + f"coefficient row {row} has a singular quadratic matrix" ) from exc centered_constant = float(vector @ inverse_times_linear) - residual = abs(float(constant) - centered_constant) - condition_number = float(np.linalg.cond(matrix, 2)) - scale = max(1.0, abs(float(constant)), abs(centered_constant)) - bound = max( - norm_tol * max(1.0, abs(float(constant))), - _NORMALIZATION_ROUNDING_FACTOR + delta = float(constant) - centered_constant + row_roundoff = ( + _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON - * condition_number - * scale, + * float(np.linalg.cond(matrix, 2)) + * max(abs(float(constant)), abs(centered_constant)) ) - if not np.isfinite(residual) or residual > bound: + if not np.isfinite(delta) or not np.isfinite(row_roundoff): raise ValueError( - f"coefficient row {row} is not a normalised conic: " - f"|c_i - b_i^T A_i^-1 b_i|={residual} exceeds " - f"the normalization tolerance bound={bound}; use " - "ellphi.coef_from_cov for normalised conics" + f"coefficient row {row} has a non-finite normalization residual" ) centers[row] = -inverse_times_linear - return matrices, centers + offsets[row] = delta + value_roundoff += row_roundoff + return matrices, centers, offsets, float(value_roundoff) def _centered_constraint_values( - point: np.ndarray, matrices: np.ndarray, centers: np.ndarray + point: np.ndarray, + matrices: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray, ) -> np.ndarray: - """Evaluate all constraints using the engine's reconstructed centers.""" + """Evaluate all centered constraints with the engine's offsets.""" differences = point[np.newaxis, :] - centers - return np.einsum("ki,kij,kj->k", differences, matrices, differences) + values = np.einsum("ki,kij,kj->k", differences, matrices, differences) + return values + offsets def tangency_simplex( @@ -150,7 +160,6 @@ def tangency_simplex( max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, - norm_tol: float = 1e-9, regularization: float = 0.0, condition_number_limit: float | None = None, max_conditioning_steps: int = 8, @@ -167,12 +176,6 @@ def tangency_simplex( weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set`` as the tight-constraint set at the returned point. - norm_tol: Relative tolerance for the required normalized-conic - identity. The accepted residual bound is the maximum of - ``norm_tol * max(1, |c_i|)`` and - ``64 * eps * cond2(A_i) * max(1, |c_i|, - |b_i^T A_i^{-1} b_i|)``. Each row must use the convention - ``b_i = -A_i xbar_i`` and ``c_i = xbar_i^T A_i xbar_i``. regularization: Optional diagonal regularization of weighted matrices. condition_number_limit: Optional weighted-matrix condition target. max_conditioning_steps: Maximum conditioning-shift escalations. @@ -185,9 +188,9 @@ def tangency_simplex( Raises: ValueError: If the coefficient array is not two-dimensional, is empty, a tolerance is not finite and non-negative, or a coefficient row - is not a normalized conic. Packed input requires ``d >= 2``, as - for :func:`ellphi.tangency`. Use :func:`ellphi.coef_from_cov` to - construct normalized rows. + has a singular quadratic matrix, or the packed quadrics have no + common non-negative tangency scale. Packed input requires + ``d >= 2``, as for :func:`ellphi.tangency`. RuntimeError: If the internal solver does not converge or produces a non-finite output. Solver diagnostics are included in the error. """ @@ -203,11 +206,12 @@ def tangency_simplex( ) _validate_tolerance("active_tol", active_tol) _validate_tolerance("weight_tol", weight_tol) - _validate_tolerance("norm_tol", norm_tol) - matrices, centers = _validate_normalized_coefs(coefs, norm_tol) + matrices, centers, offsets, value_roundoff = _prepare_coefs(coefs) - result = solve_minimax_from_coefs( - coefs, + result = solve_minimax( + matrices, + centers, + offsets=offsets, method=method, tol=tol, max_iter=max_iter, @@ -231,14 +235,25 @@ def tangency_simplex( f"diagnostics={result.metadata!r}" ) - values = _centered_constraint_values(result.circumcenter, matrices, centers) + values = _centered_constraint_values( + result.circumcenter, matrices, centers, offsets + ) if not np.all(np.isfinite(values)): raise RuntimeError( "tangency_simplex was non-finite: " f"method={result.method!r}, n_iter={result.n_iter}, " f"diagnostics={result.metadata!r}" ) - t_squared = float(max(result.alpha, 0.0)) + alpha = float(result.alpha) + constraint_scale = float(np.max(np.abs(values))) + scale = max(abs(alpha), constraint_scale) + negative_tolerance = max( + _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * max(1.0, scale), + value_roundoff, + ) + if alpha < -negative_tolerance: + raise ValueError("packed quadrics have no common non-negative tangency scale") + t_squared = float(max(alpha, 0.0)) t = float(np.sqrt(max(0.0, t_squared))) support = tuple(int(i) for i in np.flatnonzero(result.weights > weight_tol)) active_threshold = active_tol * max(1.0, t_squared) @@ -258,7 +273,7 @@ def tangency_simplex( def tangency_simplex_grad( coefs: np.ndarray, **solver_kwargs: Any ) -> SimplexTangencyGrad: - """Return many-body tangency and its normalized-coefficient gradient. + """Return many-body tangency and its packed-coefficient gradient. For EllPHi's packed conic ``f_i(x) = coef_i @ basis(x)``, the basis is ``[x_j**2 if j == l else 2*x_j*x_l for j <= l, 2*x_0, ..., 2*x_(d-1), 1]`` @@ -266,13 +281,17 @@ def tangency_simplex_grad( ``d(t**2)/d coef_i = mu_i * basis(point)`` and therefore ``dt/d coef_i = mu_i * basis(point) / (2*t)``. - The private engine reconstructs each center from ``A_i`` and ``b_i`` and - ignores ``c_i`` during optimization. Therefore ``dt_dcoef`` is the - coefficient-space covector for packed perturbations that preserve - ``b_i = -A_i xbar_i`` and ``c_i = xbar_i^T A_i xbar_i``. It is not a - derivative with respect to arbitrary independent packed-coordinate - perturbations; the constant component has this normalization-preserving - chain-rule meaning. + The engine passes the completed-square offset + ``delta_i = c_i - b_i^T A_i^-1 b_i`` through the minimax problem. Thus + ``dt_dcoef`` is the true gradient for independent packed-coordinate + perturbations, including the constant component ``mu_i / (2*t)``. + + A packed row encodes ``c_i = xbar_i^T A_i xbar_i + delta_i``. For + ``|xbar_i|**2 >> 1`` or ill-conditioned ``A_i``, the representable + ``delta_i`` carries roundoff of order + ``eps * cond2(A_i) * max(|c_i|, |xbar_i^T A_i xbar_i|)``. Callers + needing exact normalization at large translations should center their data + first. This is a gradient of ``t``, not ``t**2``. Its hypotheses are a non-degenerate input, at least two indices in ``active_set``, multipliers diff --git a/src/ellphi/simplex.pyi b/src/ellphi/simplex.pyi index 7ff4a63..66a8e09 100644 --- a/src/ellphi/simplex.pyi +++ b/src/ellphi/simplex.pyi @@ -2,6 +2,8 @@ from typing import Any, NamedTuple import numpy as np +from ._minimax_python import MethodName + __all__ = [ "SimplexTangencyResult", "SimplexTangencyGrad", @@ -27,12 +29,11 @@ class SimplexTangencyGrad(NamedTuple): def tangency_simplex( coefs: np.ndarray, *, - method: str = "fw+bisect", + method: MethodName | str = "fw+bisect", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, - norm_tol: float = 1e-9, regularization: float = 0.0, condition_number_limit: float | None = None, max_conditioning_steps: int = 8, diff --git a/tests/factories.py b/tests/factories.py index e8d860d..379eada 100644 --- a/tests/factories.py +++ b/tests/factories.py @@ -67,3 +67,60 @@ def random_simplex( eigvals = rng.uniform(1.0, cond_bound, size=d) matrices[i] = U @ np.diag(eigvals) @ U.T return matrices, centers + + +def minimax_public_surrogate() -> tuple[np.ndarray, np.ndarray]: + """Return the public-safe deterministic minimax regression instance. + + The literals are reproduced from this complete recipe. Create + ``rng = np.random.default_rng(10602)`` and traverse zero-based instances + ``0`` through ``12`` in order. For each instance, first traverse matrix + rows ``i = 0`` through ``5`` and, for each row, draw + ``q = np.linalg.qr(rng.standard_normal((2, 2)))[0]`` followed by + ``eigenvalues = np.exp(rng.uniform(-1.0, 1.0, size=2))`` and construct + ``(q * eigenvalues) @ q.T``. After all six matrices, draw + ``centers = rng.standard_normal((6, 2))``. The returned literals are the + matrices and centers from instance 12; this explicit matrix-first, + row-major traversal is part of the fixture definition. + """ + matrices = np.array( + [ + [ + [0.6508813596346038, 0.2489660729149641], + [0.2489660729149641, 0.7881614960406568], + ], + [ + [0.7004122505872777, 0.14197229432398561], + [0.14197229432398561, 1.1445419752575752], + ], + [ + [0.6661363125679673, -0.7228217513541597], + [-0.7228217513541597, 2.3994411001217943], + ], + [ + [0.555802471026214, 0.26197345221646695], + [0.26197345221646695, 0.9029253520499695], + ], + [ + [2.304214987069779, 0.6449129856946328], + [0.6449129856946328, 0.737837149118542], + ], + [ + [0.7373374529979612, 0.10773179234057872], + [0.10773179234057872, 0.8413822561278285], + ], + ], + dtype=float, + ) + centers = np.array( + [ + [0.3708705067926382, 0.48366396611109785], + [1.16738707134914, -0.9051617225542165], + [-0.6339208703399198, -0.47057481821754643], + [0.1207125164253454, -1.267286300475832], + [0.877114694674914, -0.46523959355638184], + [-0.4268970087617493, 0.6371793650807637], + ], + dtype=float, + ) + return matrices, centers diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 6fe8087..a6598c3 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -67,6 +67,22 @@ def test_single_point_3d(self): res = solve_minimax(A[np.newaxis], x[np.newaxis]) assert res.alpha == pytest.approx(0.0, abs=1e-12) + def test_single_point_offset(self): + res = solve_minimax( + np.eye(2)[np.newaxis], + np.array([[1.0, 2.0]]), + offsets=np.array([0.75]), + ) + assert res.alpha == 0.75 + + def test_single_point_nan_offset_raises(self): + with pytest.raises(ValueError, match="offsets must be finite"): + solve_minimax( + np.eye(2)[np.newaxis], + np.zeros((1, 2)), + offsets=np.array([np.nan]), + ) + # --------------------------------------------------------------------------- # Isotropic (A_i = I) special cases @@ -111,6 +127,16 @@ def test_three_points_circumcenter_equidistant(self): assert np.max(f) - np.min(f) == pytest.approx(0.0, abs=1e-6) assert res.converged + def test_two_points_with_offset(self): + matrices = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0]]) + + res = solve_minimax(matrices, centers, offsets=np.array([1.0, 0.0])) + + assert res.converged + assert res.alpha == pytest.approx(1.5625, abs=1e-12) + np.testing.assert_allclose(res.circumcenter, [0.75, 0.0], atol=1e-12) + # --------------------------------------------------------------------------- # Cross-validation with ellphi (pairwise case |σ| = 2) @@ -235,6 +261,23 @@ def test_random_simplex_convergence(self, k, d): class TestNumericalStabilityControls: + @pytest.mark.parametrize("method", list(get_args(minimax_mod.MethodName))) + def test_zero_offsets_are_bitwise_identical(self, method): + matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0], [0.5, 1.0]]) + + baseline = solve_minimax(matrices, centers, method=method) + explicit_zeros = solve_minimax( + matrices, centers, offsets=np.zeros(3), method=method + ) + + assert explicit_zeros.alpha == baseline.alpha + np.testing.assert_array_equal( + explicit_zeros.circumcenter, baseline.circumcenter + ) + np.testing.assert_array_equal(explicit_zeros.weights, baseline.weights) + assert explicit_zeros.converged == baseline.converged + def test_explicit_default_controls_match_previous_behaviour(self): rng = np.random.default_rng(321) centers = rng.standard_normal((4, 3)) @@ -305,6 +348,8 @@ def test_stability_control_parameter_validation(self): solve_minimax(A, centers, condition_number_limit=1.0) with pytest.raises(ValueError): solve_minimax(A, centers, max_conditioning_steps=-1) + with pytest.raises(ValueError, match="offsets shape"): + solve_minimax(A, centers, offsets=np.zeros(3)) def test_conditioning_steps_cap_is_strict(self): A = np.diag([1e-12, 1.0]) @@ -379,6 +424,24 @@ def test_pairwise_alpha_is_squared_tangency_time(solver_backend, rng, dim): assert res.weights.sum() == pytest.approx(1.0, abs=1e-12) +@pytest.mark.parametrize("dim", [2, 3]) +def test_unnormalized_pairwise_coefs_match_tangency(solver_backend, rng, dim): + """General packed constants agree with pairwise tangency.""" + for _ in range(5): + pcoef, qcoef = random_coef_pair(rng, dim=dim) + coefs = np.stack([pcoef, qcoef]) + coefs[:, -1] += rng.uniform(0.1, 1.0, size=2) + + pairwise = ellphi.tangency(coefs[0], coefs[1], backend=solver_backend) + res = solve_minimax_from_coefs(coefs, tol=1e-11) + + assert res.converged + assert res.alpha == pytest.approx(pairwise.t**2, rel=1e-9) + np.testing.assert_allclose( + res.circumcenter, pairwise.point, rtol=1e-9, atol=1e-10 + ) + + # --------------------------------------------------------------------------- # Regression fixture: weight support versus tight constraint set # --------------------------------------------------------------------------- diff --git a/tests/test_minimax_grad.py b/tests/test_minimax_grad.py index 27c6af0..06c10ec 100644 --- a/tests/test_minimax_grad.py +++ b/tests/test_minimax_grad.py @@ -101,6 +101,7 @@ def test_output_shapes(self): grad = compute_gradient(result, centers, matrices) assert len(grad.d_xbar) == k assert len(grad.d_A) == k + assert grad.d_offsets.shape == (k,) for i in range(k): assert grad.d_xbar[i].shape == (d,) assert grad.d_A[i].shape == (d, d) @@ -119,6 +120,7 @@ def test_passive_vertices_zero(self): if result.weights[i] < 1e-10: np.testing.assert_allclose(grad.d_xbar[i], 0.0, atol=1e-14) np.testing.assert_allclose(grad.d_A[i], 0.0, atol=1e-14) + assert grad.d_offsets[i] == pytest.approx(0.0, abs=1e-14) def test_d_A_symmetric(self): """d alpha / d A_k = mu_k outer(diff, diff) is symmetric.""" @@ -148,6 +150,29 @@ def test_weights_match_result(self): result = solve_minimax(matrices, centers, method="fw+brentq+newton") grad = compute_gradient(result, centers, matrices) np.testing.assert_allclose(grad.weights, result.weights, atol=1e-15) + np.testing.assert_array_equal(grad.d_offsets, result.weights) + + def test_zero_offsets_leave_existing_gradients_unchanged(self): + rng = np.random.default_rng(6) + d, k = 2, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + + baseline = solve_minimax(matrices, centers, method="scipy-slsqp") + with_zeros = solve_minimax( + matrices, + centers, + offsets=np.zeros(k), + method="scipy-slsqp", + ) + baseline_grad = compute_gradient(baseline, centers, matrices) + zero_grad = compute_gradient(with_zeros, centers, matrices) + + for actual, expected in zip(zero_grad.d_xbar, baseline_grad.d_xbar): + np.testing.assert_array_equal(actual, expected) + for actual, expected in zip(zero_grad.d_A, baseline_grad.d_A): + np.testing.assert_array_equal(actual, expected) + np.testing.assert_array_equal(zero_grad.d_offsets, baseline_grad.d_offsets) # --------------------------------------------------------------------------- @@ -230,6 +255,34 @@ def test_pairwise_matches_ellphi_direction(self): err = _rel_err(grad.d_xbar[i], fd) assert err < 1e-5, f"pairwise xbar[{i}] rel_err={err:.2e}" + def test_offset_gradient_matches_finite_differences(self): + rng = np.random.default_rng(31) + d, k = 2, 3 + matrices = np.stack([_make_spd(rng, d) for _ in range(k)]) + centers = rng.standard_normal((k, d)) + offsets = np.array([0.2, 0.5, 0.1]) + result = solve_minimax(matrices, centers, offsets=offsets, method="scipy-slsqp") + grad = compute_gradient(result, centers, matrices) + h = 1e-6 + + finite_difference = np.empty(k) + for i in range(k): + plus = offsets.copy() + minus = offsets.copy() + plus[i] += h + minus[i] -= h + alpha_plus = solve_minimax( + matrices, centers, offsets=plus, method="scipy-slsqp" + ).alpha + alpha_minus = solve_minimax( + matrices, centers, offsets=minus, method="scipy-slsqp" + ).alpha + finite_difference[i] = (alpha_plus - alpha_minus) / (2.0 * h) + + np.testing.assert_allclose( + grad.d_offsets, finite_difference, rtol=1e-5, atol=1e-7 + ) + # --------------------------------------------------------------------------- # Input validation tests diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index d454993..e9b5472 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -18,7 +18,7 @@ from ellphi._minimax_python import MethodName, MinimaxResult, solve_minimax -from .factories import random_simplex +from .factories import minimax_public_surrogate, random_simplex # --------------------------------------------------------------------------- @@ -42,6 +42,88 @@ def _random_simplex(k: int, d: int, seed: int = 0): "newton-cold", ) +SURROGATE_ALPHA = 0.9024444260258915 + + +def _surrogate_diagnostics(result, matrices, centers): + diff = result.circumcenter[np.newaxis, :] - centers + values = np.einsum("ki,kij,kj->k", diff, matrices, diff) + gap = float(np.max(values) - result.weights @ values) + stationarity = np.einsum("k,kij,kj->i", result.weights, matrices, diff) + residual = float(np.linalg.norm(stationarity, ord=np.inf)) + return gap, residual + + +@pytest.fixture(scope="module") +def public_surrogate_results(): + matrices, centers = minimax_public_surrogate() + results = { + method: solve_minimax(matrices, centers, method=method) + for method in CANONICAL_METHODS + } + return matrices, centers, results + + +def test_public_surrogate_recipe_matches_literals(): + rng = np.random.default_rng(10602) + expected_matrices = np.empty((6, 2, 2)) + expected_centers = np.empty((6, 2)) + for instance in range(13): + matrices = np.empty((6, 2, 2)) + for row in range(6): + q = np.linalg.qr(rng.standard_normal((2, 2)))[0] + eigenvalues = np.exp(rng.uniform(-1.0, 1.0, size=2)) + matrices[row] = (q * eigenvalues) @ q.T + centers = rng.standard_normal((6, 2)) + + if instance == 12: + expected_matrices = matrices + expected_centers = centers + + matrices, centers = minimax_public_surrogate() + np.testing.assert_allclose(matrices, expected_matrices, rtol=1e-15, atol=1e-15) + np.testing.assert_array_equal(centers, expected_centers) + + +class TestPublicSurrogate: + def test_slsqp_reference_value_and_gap(self, public_surrogate_results): + matrices, centers, results = public_surrogate_results + result = results["scipy-slsqp"] + gap, residual = _surrogate_diagnostics(result, matrices, centers) + + assert result.converged + assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 + assert gap <= 1e-8 + assert residual <= 1e-8 + + @pytest.mark.parametrize( + "method", [method for method in CANONICAL_METHODS if method != "scipy-slsqp"] + ) + def test_other_methods_are_accurate_or_report_failure( + self, method, public_surrogate_results + ): + matrices, centers, results = public_surrogate_results + result = results[method] + gap, residual = _surrogate_diagnostics(result, matrices, centers) + + if result.converged: + assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 + assert gap <= 1e-8 + assert residual <= 1e-8 + else: + assert result.converged is False + + def test_newton_failures_do_not_collapse_to_a_vertex( + self, public_surrogate_results + ): + _, _, results = public_surrogate_results + bisect_error = abs(results["fw+bisect"].alpha - SURROGATE_ALPHA) + brentq_error = abs(results["fw+brentq"].alpha - SURROGATE_ALPHA) + + for method in ("fw+bisect+newton", "fw+bisect+damped-newton", "newton-cold"): + assert abs(results[method].alpha - SURROGATE_ALPHA) <= bisect_error + assert abs(results["fw+brentq+newton"].alpha - SURROGATE_ALPHA) <= brentq_error + # --------------------------------------------------------------------------- # Basic dispatch / API @@ -226,6 +308,19 @@ def test_metadata_has_hessian_cond(self): assert res.metadata is not None assert "hessian_cond" in res.metadata + def test_empty_thresholded_face_is_nonconverged(self): + matrices, centers = _random_simplex(3, 2, seed=42) + res = solve_minimax( + matrices, + centers, + method="fw+bisect+damped-newton", + weight_tol=1.0, + ) + + assert res.converged is False + assert res.metadata is not None + assert res.metadata["newton_status"] == "empty_face" + # --------------------------------------------------------------------------- # fw+bisect+newton specific diff --git a/tests/test_simplex.py b/tests/test_simplex.py index e145f78..4de8c74 100644 --- a/tests/test_simplex.py +++ b/tests/test_simplex.py @@ -8,10 +8,10 @@ import pytest import ellphi -from ellphi._minimax_python import MethodName -from ellphi.geometry import coef_from_cov +from ellphi._minimax_python import MethodName, solve_minimax +from ellphi.geometry import coef_from_cov, pack_conic, unpack_conic -from .factories import random_coef_pair, random_covariance +from .factories import minimax_public_surrogate, random_coef_pair, random_covariance def _random_coefs(k: int, d: int, seed: int) -> np.ndarray: @@ -29,6 +29,20 @@ def _relative_error(actual: np.ndarray | float, expected: np.ndarray | float) -> return numerator / denominator +def _value_roundoff_bound(coefs: np.ndarray) -> float: + matrices, linear, constants = unpack_conic(coefs) + return sum( + 64.0 + * np.finfo(float).eps + * np.linalg.cond(matrix, 2) + * max( + abs(float(constant)), + abs(float(vector @ np.linalg.solve(matrix, vector))), + ) + for matrix, vector, constant in zip(matrices, linear, constants) + ) + + def test_pairwise_agrees_with_tangency(solver_backend, rng): p, q = random_coef_pair(rng, dim=3) result = ellphi.tangency_simplex(np.stack((p, q))) @@ -41,13 +55,42 @@ def test_pairwise_agrees_with_tangency(solver_backend, rng): ) +@pytest.mark.parametrize("dimension", [2, 3]) +def test_unnormalized_pairwise_agrees_with_tangency(solver_backend, rng, dimension): + for _ in range(5): + centers = rng.uniform(-2.0, 2.0, size=(2, dimension)) + while np.linalg.norm(centers[0] - centers[1]) < 1.5: + centers = rng.uniform(-2.0, 2.0, size=(2, dimension)) + covariances = np.stack( + [random_covariance(rng, dim=dimension) for _ in range(2)] + ) + coefs = coef_from_cov(centers, covariances) + coefs[:, -1] += rng.uniform(0.1, 1.0) + rng.uniform(-1e-4, 1e-4, size=2) + + result = ellphi.tangency_simplex(coefs) + pairwise = ellphi.tangency(coefs[0], coefs[1], backend=solver_backend) + + assert result.t == pytest.approx(pairwise.t, rel=1e-9) + np.testing.assert_allclose(result.point, pairwise.point, rtol=1e-9, atol=1e-10) + + def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backend): - centers = np.array([[1e8, 0.0], [1e8 + 2.0, 0.0]]) + centers = np.array([[1e6, 0.0], [1e6 + 2.0, 0.0]]) coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], 2, axis=0)) pairwise_coefs = coef_from_cov( np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) ) + # Packed inputs carry roundoff of order eps*|xbar|**2; this is a + # representation limit, not a solver property. + matrices, _, constants = unpack_conic(coefs) + translation_bound = max( + 64.0 + * np.finfo(float).eps + * np.linalg.cond(matrix, 2) + * max(1.0, abs(float(constant))) + for matrix, constant in zip(matrices, constants) + ) result = ellphi.tangency_simplex(coefs) pairwise = ellphi.tangency( pairwise_coefs[0], pairwise_coefs[1], backend=solver_backend @@ -67,13 +110,35 @@ def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backen ) pairwise_identity = 0.5 * basis / (2.0 * pairwise.t) - assert result.t == pytest.approx(pairwise.t, rel=1e-9) + assert abs(result.t**2 - pairwise.t**2) <= translation_bound assert result.active_set == (0, 1) assert np.all(np.isfinite(gradient.dt_dcoef)) assert _relative_error(gradient.dt_dcoef[0], pairwise_identity) < 1e-6 assert _relative_error(gradient.dt_dcoef[1], pairwise_identity) < 1e-6 +def test_translated_singleton_roundoff_negative_scale_is_clipped(): + center = np.array([[1e6, -1e6]]) + covariance = np.array([[1.0, 0.2], [0.2, 1.7]]) + coefs = coef_from_cov(center, covariance[None]) + value_roundoff = _value_roundoff_bound(coefs) + + result = ellphi.tangency_simplex(coefs) + + assert abs(result.t) <= np.sqrt(value_roundoff) + + +def test_translated_coincident_roundoff_negative_scale_is_clipped(): + center = np.array([[1e6, -1e6]]) + covariance = np.array([[1.0, 0.2], [0.2, 1.7]]) + coefs = np.repeat(coef_from_cov(center, covariance[None]), 2, axis=0) + value_roundoff = _value_roundoff_bound(coefs) + + result = ellphi.tangency_simplex(coefs) + + assert abs(result.t) <= np.sqrt(value_roundoff) + + @pytest.mark.parametrize("dimension", [2, 3, 4]) @pytest.mark.parametrize("condition_number", [1e2, 1e6, 1e10, 1e12]) def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_number): @@ -84,10 +149,28 @@ def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_num center = rng.uniform(-2.0, 2.0, size=(1, dimension)) coefs = coef_from_cov(center, covariance[None]) - result = ellphi.tangency_simplex(coefs) + matrices, linear, constants = unpack_conic(coefs) + precision_bound = ( + 64.0 + * np.finfo(float).eps + * np.linalg.cond(matrices[0], 2) + * max(1.0, abs(float(constants[0]))) + ) - assert result.t == 0.0 - assert np.all(np.isfinite(result.point)) + if condition_number <= 1e6: + result = ellphi.tangency_simplex(coefs) + assert result.t**2 <= precision_bound + point = result.point + else: + inverse_times_linear = np.linalg.solve(matrices[0], linear[0]) + centers = np.stack([-inverse_times_linear]) + centered_constant = float(linear[0] @ inverse_times_linear) + result = solve_minimax( + matrices, centers, offsets=np.array([constants[0] - centered_constant]) + ) + assert abs(result.alpha) <= precision_bound + point = result.circumcenter + assert np.all(np.isfinite(point)) def test_scaled_centres_from_cov_are_accepted(): @@ -105,6 +188,50 @@ def test_scaled_centres_from_cov_are_accepted(): assert result.active_set == (0, 1) +def test_subthreshold_packed_constant_is_honoured_by_gradient(): + matrices = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0]]) + linear = -np.einsum("kij,kj->ki", matrices, centers) + baseline_coefs = pack_conic(matrices, linear, np.array([0.0, 4.0])) + perturbed_coefs = baseline_coefs.copy() + perturbed_coefs[0, -1] += 5e-10 + solver_kwargs = {"method": "fw+brentq+newton", "tol": 1e-12} + + baseline = ellphi.tangency_simplex(baseline_coefs, **solver_kwargs) + perturbed = ellphi.tangency_simplex(perturbed_coefs, **solver_kwargs) + gradient = ellphi.tangency_simplex_grad(perturbed_coefs, **solver_kwargs) + + expected_change = baseline.mu[0] * 5e-10 + assert perturbed.t**2 - baseline.t**2 == pytest.approx( + expected_change, rel=1e-6, abs=1e-15 + ) + + h = 1e-7 + plus = perturbed_coefs.copy() + minus = perturbed_coefs.copy() + plus[0, -1] += h + minus[0, -1] -= h + finite_difference = ( + ellphi.tangency_simplex(plus, **solver_kwargs).t + - ellphi.tangency_simplex(minus, **solver_kwargs).t + ) / (2.0 * h) + assert gradient.dt_dcoef[0, -1] == pytest.approx( + finite_difference, rel=1e-6, abs=1e-12 + ) + + +def test_negative_packed_scale_raises(): + coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + coefs[:, -1] -= 2.0 + + with pytest.raises( + ValueError, match="packed quadrics have no common non-negative tangency scale" + ): + ellphi.tangency_simplex(coefs) + + def test_packed_one_dimensional_input_is_rejected_like_pairwise(): coefs = np.array([[1.0, -2.0, 1.0], [1.0, -4.0, 4.0]]) @@ -155,42 +282,33 @@ def test_non_convergence_raises_with_diagnostics(): assert "diagnostics=" in message -@pytest.mark.parametrize( - "k,d,seed", - [(3, 2, 201), (3, 3, 202), (4, 2, 203), (4, 3, 204)], -) -def test_gradient_matches_normalisation_preserving_central_difference(k, d, seed): +@pytest.mark.parametrize("k,d,seed", [(3, 2, 201), (4, 2, 203)]) +def test_gradient_matches_independent_packed_central_difference(k, d, seed): rng = np.random.default_rng(seed) centers = rng.uniform(-2.0, 2.0, size=(k, d)) covariances = np.stack([random_covariance(rng, dim=d) for _ in range(k)]) - matrices = np.linalg.inv(covariances) - center_direction = rng.standard_normal(centers.shape) - matrix_direction = rng.standard_normal(matrices.shape) - matrix_direction = 0.5 * (matrix_direction + np.swapaxes(matrix_direction, -1, -2)) - - def packed_at(step): - shifted_centers = centers + step * center_direction - shifted_matrices = matrices + step * matrix_direction - return coef_from_cov(shifted_centers, np.linalg.inv(shifted_matrices)) + coefs = coef_from_cov(centers, covariances) + coefs[:, -1] += rng.uniform(0.1, 1.0, size=k) solver_kwargs = { "method": "fw+brentq+newton", "tol": 1e-12, "newton_tol": 1e-14, } - coefs = packed_at(0.0) gradient = ellphi.tangency_simplex_grad(coefs, **solver_kwargs) h = 1e-6 - plus = packed_at(h) - minus = packed_at(-h) - finite_difference = ( - ellphi.tangency_simplex(plus, **solver_kwargs).t - - ellphi.tangency_simplex(minus, **solver_kwargs).t - ) / (2.0 * h) - coefficient_direction = (plus - minus) / (2.0 * h) - analytical = float(np.sum(gradient.dt_dcoef * coefficient_direction)) - - error = _relative_error(analytical, finite_difference) + finite_difference = np.empty_like(coefs) + for index in np.ndindex(coefs.shape): + plus = coefs.copy() + minus = coefs.copy() + plus[index] += h + minus[index] -= h + finite_difference[index] = ( + ellphi.tangency_simplex(plus, **solver_kwargs).t + - ellphi.tangency_simplex(minus, **solver_kwargs).t + ) / (2.0 * h) + + error = _relative_error(gradient.dt_dcoef, finite_difference) assert error < 1e-6, f"k={k}, d={d}, relative error={error:.3e}" @@ -212,18 +330,36 @@ def test_zero_time_gradient_raises(): @pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) -def test_unnormalized_constant_is_rejected(api): +def test_unnormalized_constant_agrees_with_expected(api): coefs = coef_from_cov( np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) ) coefs[0, -1] += 1.0 - with pytest.raises(ValueError, match=r"row 0.*coef_from_cov"): - api(coefs) + result = api(coefs) + + assert result.t == pytest.approx(1.25) + np.testing.assert_allclose(result.point, [0.75, 0.0], atol=1e-12) + assert result.active_set == (0, 1) + + +@pytest.mark.parametrize("method", list(get_args(MethodName))) +def test_public_surrogate_methods(method): + matrices, centers = minimax_public_surrogate() + linear = -np.einsum("kij,kj->ki", matrices, centers) + constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) + coefs = pack_conic(matrices, linear, constants) + + if method == "scipy-slsqp": + result = ellphi.tangency_simplex(coefs, method=method) + assert result.t == pytest.approx(np.sqrt(0.9024444260258915), abs=1e-8) + else: + with pytest.raises(RuntimeError): + ellphi.tangency_simplex(coefs, method=method) @pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) -@pytest.mark.parametrize("name", ["active_tol", "weight_tol", "norm_tol"]) +@pytest.mark.parametrize("name", ["active_tol", "weight_tol"]) @pytest.mark.parametrize("value", [np.nan, -1.0]) def test_simplex_tolerances_must_be_finite_and_nonnegative(api, name, value): coefs = coef_from_cov( From dc39c2eb9ea4e350b872bc83de64776e28aa383d Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 22:18:15 +0900 Subject: [PATCH 05/29] fix many-body solver review findings Validate solver controls and preserve a non-empty Frank-Wolfe face. Use the regularized dual for positive-regularization SLSQP and cover all three review regressions. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 87 ++++++++++++++++++--- src/ellphi/simplex.py | 61 +++++++++++++-- tests/test_minimax.py | 142 ++++++++++++++++++++++++++++++++++ tests/test_minimax_methods.py | 17 ++-- tests/test_simplex.py | 10 +++ 5 files changed, 292 insertions(+), 25 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index dde0fae..facbe81 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -31,6 +31,9 @@ unbacktracked full step. * The objective supports additive per-constraint offsets, including general packed conic constants. +* For positive regularization, the SLSQP objective is the regularized dual + rather than ``dot(mu, f)``; this fixes the inherited ellcech objective and + Jacobian mismatch. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. @@ -255,6 +258,25 @@ def _condition_matrix( return A_reg +def _validate_tolerance( + name: str, value: float, *, strictly_positive: bool = False +) -> None: + """Validate a finite numerical tolerance or regularization value.""" + if not np.isfinite(value) or (value <= 0.0 if strictly_positive else value < 0.0): + qualifier = "finite and > 0" if strictly_positive else "finite and non-negative" + raise ValueError(f"{name} must be {qualifier}") + + +def _validate_positive_int(name: str, value: int) -> None: + """Validate a positive integer solver parameter.""" + if ( + isinstance(value, (bool, np.bool_)) + or not isinstance(value, (int, np.integer)) + or value <= 0 + ): + raise ValueError(f"{name} must be a positive integer") + + def _cholesky_solve( A: np.ndarray, b: np.ndarray, @@ -497,6 +519,8 @@ def _run_fw_bisect( s = int(np.argmax(f)) active_mask = mu > weight_tol + if not np.any(active_mask): + active_mask = np.ones_like(mu, dtype=bool) f_active = np.where(active_mask, f, np.inf) v = int(np.argmin(f_active)) @@ -572,6 +596,8 @@ def _run_fw_brentq( s = int(np.argmax(f)) active_mask = mu > weight_tol + if not np.any(active_mask): + active_mask = np.ones_like(mu, dtype=bool) f_active = np.where(active_mask, f, np.inf) v = int(np.argmin(f_active)) @@ -978,6 +1004,42 @@ def _simplex_residual(mu: npt.NDArray[np.float64]) -> float: return float(mu.sum() - 1.0) +def _slsqp_objective_and_gradient( + mu: npt.NDArray[np.float64], + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray | None, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[float, np.ndarray]: + """Return SLSQP's negative dual objective and its negative gradient.""" + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + if regularization == 0.0: + # Keep the unregularized objective path bitwise identical. + return -float(np.dot(mu, f)), -f + + c = np.einsum("ki,kij,kj->k", centers, matrices, centers) + if offsets is not None: + c = c + offsets + b_mu = np.einsum("k,ki->i", mu, Ax) + # The regularized dual is g_r(mu) = sum_i mu_i c_i - + # b(mu)^T (A(mu) + r I)^(-1) b(mu), whose gradient is f. + g_regularized = float(np.dot(mu, c) - np.dot(b_mu, xstar)) + return -g_regularized, -f + + def _run_scipy_slsqp( matrices: np.ndarray, Ax: np.ndarray, @@ -1000,7 +1062,7 @@ def _run_scipy_slsqp( def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: n_eval[0] += 1 - _, f = _eval_f( + return _slsqp_objective_and_gradient( mu, matrices, Ax, @@ -1010,8 +1072,6 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - # g(mu) = dot(mu, f); gradient dg/dmu_i = f_i(x*(mu)) - return -float(np.dot(mu, f)), -f x0 = np.full(k, 1.0 / k) bounds = [(0.0, None)] * k @@ -1174,13 +1234,6 @@ def solve_minimax( matrices = np.asarray(matrices, dtype=float) centers = np.asarray(centers, dtype=float) - if regularization < 0.0: - raise ValueError("regularization must be non-negative") - if condition_number_limit is not None and condition_number_limit <= 1.0: - raise ValueError("condition_number_limit must be > 1 when provided") - if max_conditioning_steps < 0: - raise ValueError("max_conditioning_steps must be non-negative") - # Accept single-simplex input (2D matrix, 1D center) if matrices.ndim == 2: matrices = matrices[np.newaxis] @@ -1188,8 +1241,22 @@ def solve_minimax( k, d = centers.shape + _validate_tolerance("tol", tol, strictly_positive=True) + _validate_tolerance("newton_tol", newton_tol) + _validate_tolerance("regularization", regularization) + _validate_tolerance("weight_tol", weight_tol) + _validate_positive_int("max_iter", max_iter) + _validate_positive_int("newton_max_iter", newton_max_iter) + _validate_positive_int("max_conditioning_steps", max_conditioning_steps) + if condition_number_limit is not None and ( + not np.isfinite(condition_number_limit) or condition_number_limit <= 1.0 + ): + raise ValueError("condition_number_limit must be finite and > 1 when provided") + if k == 0: raise ValueError("simplex must contain at least one vertex (k=0 given)") + if weight_tol >= 1.0 / k: + raise ValueError("weight_tol must satisfy 0 <= weight_tol < 1/k") if offsets is not None: offsets = np.asarray(offsets, dtype=float) if offsets.shape != (k,): diff --git a/src/ellphi/simplex.py b/src/ellphi/simplex.py index 7a76429..b19562a 100644 --- a/src/ellphi/simplex.py +++ b/src/ellphi/simplex.py @@ -91,10 +91,51 @@ def _coefficient_basis(point: np.ndarray) -> np.ndarray: return np.concatenate((quadratic, 2.0 * point, np.array([1.0]))) -def _validate_tolerance(name: str, value: float) -> None: - """Validate a finite, non-negative numerical tolerance.""" - if not np.isfinite(value) or value < 0.0: - raise ValueError(f"{name} must be finite and non-negative") +def _validate_tolerance( + name: str, value: float, *, strictly_positive: bool = False +) -> None: + """Validate a finite numerical tolerance.""" + if not np.isfinite(value) or (value <= 0.0 if strictly_positive else value < 0.0): + qualifier = "finite and > 0" if strictly_positive else "finite and non-negative" + raise ValueError(f"{name} must be {qualifier}") + + +def _validate_positive_int(name: str, value: int) -> None: + """Validate a positive integer solver parameter.""" + if ( + isinstance(value, (bool, np.bool_)) + or not isinstance(value, (int, np.integer)) + or value <= 0 + ): + raise ValueError(f"{name} must be a positive integer") + + +def _validate_solver_parameters( + k: int, + *, + tol: float, + max_iter: int, + weight_tol: float, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, + newton_tol: float, + newton_max_iter: int, +) -> None: + """Validate public solver controls before dispatching to the engine.""" + _validate_tolerance("tol", tol, strictly_positive=True) + _validate_tolerance("newton_tol", newton_tol) + _validate_tolerance("regularization", regularization) + _validate_tolerance("weight_tol", weight_tol) + _validate_positive_int("max_iter", max_iter) + _validate_positive_int("newton_max_iter", newton_max_iter) + _validate_positive_int("max_conditioning_steps", max_conditioning_steps) + if condition_number_limit is not None and ( + not np.isfinite(condition_number_limit) or condition_number_limit <= 1.0 + ): + raise ValueError("condition_number_limit must be finite and > 1 when provided") + if weight_tol >= 1.0 / k: + raise ValueError("weight_tol must satisfy 0 <= weight_tol < 1/k") def _prepare_coefs( @@ -205,7 +246,17 @@ def tangency_simplex( "one-dimensional packed conics are not supported" ) _validate_tolerance("active_tol", active_tol) - _validate_tolerance("weight_tol", weight_tol) + _validate_solver_parameters( + coefs.shape[0], + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, + ) matrices, centers, offsets, value_roundoff = _prepare_coefs(coefs) result = solve_minimax( diff --git a/tests/test_minimax.py b/tests/test_minimax.py index a6598c3..c0a854c 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -351,6 +351,148 @@ def test_stability_control_parameter_validation(self): with pytest.raises(ValueError, match="offsets shape"): solve_minimax(A, centers, offsets=np.zeros(3)) + @pytest.mark.parametrize("value", [np.inf, np.nan, 0.0]) + def test_fw_tolerance_must_be_finite_and_positive(self, value): + A = np.eye(2)[np.newaxis].repeat(2, axis=0) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + with pytest.raises(ValueError, match="tol must be finite and > 0"): + solve_minimax(A, centers, tol=value) + + @pytest.mark.parametrize("k", [2, 3, 4]) + @pytest.mark.parametrize("weight_tol", [None, 0.5]) + def test_weight_tol_cannot_empty_the_fw_face(self, k, weight_tol): + A = np.repeat(np.eye(2)[np.newaxis], k, axis=0) + centers = np.arange(2 * k, dtype=float).reshape(k, 2) + threshold = 1.0 / k if weight_tol is None else weight_tol + with pytest.raises(ValueError, match="weight_tol must satisfy"): + solve_minimax(A, centers, weight_tol=threshold) + + def test_fw_empty_face_fallback_does_not_false_converge(self): + A = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0]]) + offsets = np.array([1.0, 0.0]) + Ax = np.einsum("kij,kj->ki", A, centers) + mu, converged, n_iter = minimax_mod._run_fw_bisect( + A, + Ax, + centers, + offsets, + np.full(2, 0.5), + tol=1e-12, + max_iter=1, + weight_tol=1.0, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert n_iter == 1 + assert not converged + assert np.all(np.isfinite(mu)) + + def test_regularized_slsqp_objective_gradient_matches(self): + matrices = np.array( + [ + [[2.0, 0.2], [0.2, 1.0]], + [[1.0, -0.1], [-0.1, 3.0]], + [[1.5, 0.3], [0.3, 2.0]], + ] + ) + centers = np.array([[0.0, 0.0], [1.0, -0.5], [-0.5, 1.0]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + mu = np.array([0.2, 0.3, 0.5]) + objective, gradient = minimax_mod._slsqp_objective_and_gradient( + mu, + matrices, + Ax, + centers, + None, + regularization=0.25, + condition_number_limit=None, + max_conditioning_steps=8, + ) + step = 1e-6 + finite_difference = np.empty_like(mu) + for i in range(mu.size): + plus = mu.copy() + minus = mu.copy() + plus[i] += step + minus[i] -= step + plus_value, _ = minimax_mod._slsqp_objective_and_gradient( + plus, + matrices, + Ax, + centers, + None, + regularization=0.25, + condition_number_limit=None, + max_conditioning_steps=8, + ) + minus_value, _ = minimax_mod._slsqp_objective_and_gradient( + minus, + matrices, + Ax, + centers, + None, + regularization=0.25, + condition_number_limit=None, + max_conditioning_steps=8, + ) + finite_difference[i] = (plus_value - minus_value) / (2.0 * step) + + np.testing.assert_allclose(finite_difference, gradient, rtol=1e-6, atol=1e-8) + assert np.isfinite(objective) + + def test_slsqp_converges_with_regularization(self): + matrices = np.array( + [ + [[2.0, 0.2], [0.2, 1.0]], + [[1.0, -0.1], [-0.1, 3.0]], + [[1.5, 0.3], [0.3, 2.0]], + ] + ) + centers = np.array([[0.0, 0.0], [1.0, -0.5], [-0.5, 1.0]]) + result = solve_minimax( + matrices, + centers, + method="scipy-slsqp", + regularization=0.25, + ) + + assert result.converged + assert np.isfinite(result.alpha) + assert np.all(np.isfinite(result.weights)) + assert result.weights.sum() == pytest.approx(1.0) + + def test_slsqp_zero_regularization_objective_path_is_unchanged(self): + matrices = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + mu = np.array([0.25, 0.75]) + objective, gradient = minimax_mod._slsqp_objective_and_gradient( + mu, + matrices, + Ax, + centers, + None, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + _, f = minimax_mod._eval_f( + mu, + matrices, + Ax, + centers, + None, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert objective == -float(np.dot(mu, f)) + np.testing.assert_array_equal(gradient, -f) + def test_conditioning_steps_cap_is_strict(self): A = np.diag([1e-12, 1.0]) eye = np.eye(2) diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index e9b5472..f179503 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -310,16 +310,13 @@ def test_metadata_has_hessian_cond(self): def test_empty_thresholded_face_is_nonconverged(self): matrices, centers = _random_simplex(3, 2, seed=42) - res = solve_minimax( - matrices, - centers, - method="fw+bisect+damped-newton", - weight_tol=1.0, - ) - - assert res.converged is False - assert res.metadata is not None - assert res.metadata["newton_status"] == "empty_face" + with pytest.raises(ValueError, match="weight_tol must satisfy"): + solve_minimax( + matrices, + centers, + method="fw+bisect+damped-newton", + weight_tol=1.0, + ) # --------------------------------------------------------------------------- diff --git a/tests/test_simplex.py b/tests/test_simplex.py index 4de8c74..d4c9399 100644 --- a/tests/test_simplex.py +++ b/tests/test_simplex.py @@ -370,6 +370,16 @@ def test_simplex_tolerances_must_be_finite_and_nonnegative(api, name, value): api(coefs, **{name: value}) +@pytest.mark.parametrize("value", [np.inf, np.nan, 0.0]) +def test_public_tol_must_be_finite_and_positive(value): + coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + + with pytest.raises(ValueError, match="tol must be finite and > 0"): + ellphi.tangency_simplex(coefs, tol=value) + + def test_public_namedtuple_field_order(): assert ellphi.SimplexTangencyResult._fields == ( "t", From 565547a1128486c133107b10ea0a64270a4d3731 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 22:29:13 +0900 Subject: [PATCH 06/29] =?UTF-8?q?refactor:=20name=20the=20many-body=20API?= =?UTF-8?q?=20after=20the=20=C4=8Cech=20filtration=20(cech,=20CechResult,?= =?UTF-8?q?=20cech=5Fgrad)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename the public many-body API after the anisotropic Čech filtration. For k bodies, t^2 = alpha(sigma) is the least scale at which the growing ellipsoids share the critical point x*, where the active normals are positively dependent; the boundaries are not mutually tangent except in the pairwise k = 2 case. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 65 +++++++++++++++++ docs/guide/many_body_tangency.md | 51 -------------- mkdocs.yml | 2 +- src/ellphi/__init__.py | 25 ++++--- src/ellphi/__init__.pyi | 18 ++--- src/ellphi/_minimax_grad_python.py | 3 +- src/ellphi/_minimax_python.py | 3 +- src/ellphi/{simplex.py => cech.py} | 93 +++++++++++++++---------- src/ellphi/{simplex.pyi => cech.pyi} | 20 +++--- tests/{test_simplex.py => test_cech.py} | 82 +++++++++++----------- 10 files changed, 194 insertions(+), 168 deletions(-) create mode 100644 docs/guide/cech_filtration.md delete mode 100644 docs/guide/many_body_tangency.md rename src/ellphi/{simplex.py => cech.py} (81%) rename src/ellphi/{simplex.pyi => cech.pyi} (68%) rename tests/{test_simplex.py => test_cech.py} (84%) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md new file mode 100644 index 0000000..5766248 --- /dev/null +++ b/docs/guide/cech_filtration.md @@ -0,0 +1,65 @@ +# Čech filtration + +The public `ellphi.cech` API computes the anisotropic Čech filtration value for +a simplex of packed ellipsoid coefficient vectors. For +`f_i(x)` describing the growing ellipsoids +`E_i(t) = {f_i <= t^2}`, `cech(coefs)` returns the Čech filtration time +`t`, where + +`t^2 = alpha(sigma) = min_x max_i f_i(x)` + +is the least squared scale at which all bodies share a common point. + +The result fields are ordered as +`(t, point, mu, support, active_set)`. The gradient result fields are +ordered as `(t, point, mu, dt_dcoef, support, active_set)`. + +- `t`: the Čech filtration time, with `t^2 = alpha(sigma)`. +- `point`: the common intersection point `x*` at the critical scale. +- `mu`: the Lagrange multipliers, or dual weights on the simplex. +- `support`: the thresholded weight support + `{i : mu_i > weight_tol}`. +- `active_set`: the tight-constraint set at the returned point, + `I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`. + +At the critical scale the intersection is the single point `x*`. The active +ellipsoid boundaries pass through `x*` and satisfy +`sum_i mu_i grad f_i(x*) = 0`, so their normals are positively dependent; +the boundaries are not tangent to each other. Pairwise tangency is only the +`k = 2` special case: for `k = 2` the Čech time equals the tangency time +computed by `tangency()`, and `cech()` agrees with it. + +Up to numerical tolerance, `support` is a subset of `active_set`; under +strict complementarity (ND1), they coincide. For three unit balls centred at +`(0, 0)`, `(2, 0)`, and `(0, 2)`, the point is `(1, 1)`, support has +two indices, and `active_set` has three. A solver that does not converge or +produces non-finite output raises `RuntimeError` with its diagnostics. + +The private engine's internal field named `active_set` is the weight support +(historical ellcech naming) and is not part of the public API. + +If `unpack_conic` returns `(A_i, b_i, c_i)`, the center is +`xbar_i = -A_i^{-1} b_i` and the completed-square constant is +`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this exactly +computed `delta_i` to the many-body engine, including when it is small, so +general independent constants are supported. + +A packed row encodes its constant as +`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1` or +ill-conditioned `A_i`, the representable `delta_i` carries roundoff of order +`eps * |xbar_i|^2`, with a `cond2(A_i)` factor for ill-conditioned matrices. +Callers needing exact normalization at large translations should center their +data first. Packed input requires `d >= 2`; d=1 packed conics are not +supported and raise `ValueError`. + +The many-body engine uses the completed-square offsets above. Thus +`cech_grad(coefs)` returns `dt_dcoef`, the gradient for arbitrary +independent packed-coordinate perturbations, including the constant component. +For the upper-triangular packed basis +`[x_i**2, 2*x_i*x_j (i < j), 2*x_i, 1]`, the formula is +`mu_i * basis(point) / (2*t)`. It assumes a non-degenerate input, at least +two indices in `active_set`, multipliers supported on `active_set`, and an +exact weighted linear solve. Convergence or a small residual alone is not a +derivative certificate, and the gradient is undefined at `t == 0`. +For far-translated inputs, the uncentred packed basis used by this derivative +can be poorly conditioned. diff --git a/docs/guide/many_body_tangency.md b/docs/guide/many_body_tangency.md deleted file mode 100644 index 55cb9f3..0000000 --- a/docs/guide/many_body_tangency.md +++ /dev/null @@ -1,51 +0,0 @@ -# Many-body tangency - -The provisional `ellphi.simplex` API extends pairwise tangency to a simplex of -packed ellipsoid coefficient vectors. `tangency_simplex(coefs)` returns the -tangency time `t`, point, simplex multipliers `mu`, multiplier `support`, and -numerically determined `active_set`. Unlike the internal minimax engine, the -public API reports `t`, not the squared value `t**2`. - -The public result fields are ordered as `(t, point, mu, support, active_set)`. -The gradient result fields are ordered as -`(t, point, mu, dt_dcoef, support, active_set)`. - -`support` is the thresholded weight support -`{i : mu_i > weight_tol}`. `active_set` is the tight-constraint set at the -returned point, -`I = {i : t**2 - f_i(point) <= active_tol * max(1, t**2)}`. Up to numerical -tolerance, `support` is a subset of `active_set`; under strict complementarity -(ND1), they coincide. For three unit balls centred at `(0, 0)`, `(2, 0)`, and -`(0, 2)`, the point is `(1, 1)`, support has two indices, and `active_set` -has three. A solver that does not converge or produces non-finite output -raises `RuntimeError` with its diagnostics. - -The private engine's internal field named `active_set` is the weight support -(historical ellcech naming) and is not part of the public API. - -If `unpack_conic` returns `(A_i, b_i, c_i)`, the center is -`xbar_i = -A_i^{-1} b_i` and the completed-square constant is -`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this exactly -computed `delta_i` to the many-body engine, including when it is small, so -general independent constants are supported. - -A packed row encodes its constant as -`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1` or -ill-conditioned `A_i`, the representable `delta_i` carries roundoff of order -`eps * |xbar_i|^2`, with a `cond2(A_i)` factor for ill-conditioned matrices. -Callers needing exact normalization at large translations should center their -data first. -Packed input requires `d >= 2`, as for `ellphi.tangency`; d=1 packed conics -are not supported and raise `ValueError`. - -The many-body engine uses the completed-square offsets above. Thus -`tangency_simplex_grad(coefs)` returns `dt_dcoef`, the gradient for arbitrary -independent packed-coordinate perturbations, including the constant -component. For the upper-triangular packed basis -`[x_i**2, 2*x_i*x_j (i < j), 2*x_i, 1]`, the formula is -`mu_i * basis(point) / (2*t)`. It assumes a non-degenerate input, at least -two indices in `active_set`, multipliers supported on `active_set`, and an -exact weighted linear solve. Convergence or a small residual alone is not a -derivative certificate, and the gradient is undefined at `t == 0`. -For far-translated inputs, the uncentred packed basis used by this derivative -can be poorly conditioned. diff --git a/mkdocs.yml b/mkdocs.yml index 7b6dc48..94b460e 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,7 @@ nav: - User Guide: - TDA Workflow: guide/tda_workflow.md - Differentiable Tangency: guide/differentiable.md - - Many-body Tangency: guide/many_body_tangency.md + - Čech Filtration: guide/cech_filtration.md - Notebook Examples: guide/notebooks.md - API Reference: - Overview: reference/index.md diff --git a/src/ellphi/__init__.py b/src/ellphi/__init__.py index 4bbde31..76b6b97 100644 --- a/src/ellphi/__init__.py +++ b/src/ellphi/__init__.py @@ -14,8 +14,7 @@ two ellipses. - `ellphi.visualization`: Helper functions for visualizing ellipses and ellipse clouds. -- `ellphi.simplex`: Pairwise-aligned many-body tangency values and gradients - (provisional names). +- `ellphi.cech`: Anisotropic Čech filtration values and gradients. """ import numpy as np @@ -48,12 +47,12 @@ from .grad import TangencyGrad, tangency_grad, pdist_tangency_grad, coef_from_cov_grad -# many-body tangency (provisional names) -from .simplex import ( - SimplexTangencyResult, - SimplexTangencyGrad, - tangency_simplex, - tangency_simplex_grad, +# anisotropic Čech filtration +from .cech import ( + CechResult, + CechGrad, + cech, + cech_grad, ) FloatArray = NDArray[np.float64] @@ -86,11 +85,11 @@ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", - # many-body tangency (provisional) - "SimplexTangencyResult", - "SimplexTangencyGrad", - "tangency_simplex", - "tangency_simplex_grad", + # anisotropic Čech filtration + "CechResult", + "CechGrad", + "cech", + "cech_grad", "__version__", "version_info", ] diff --git a/src/ellphi/__init__.pyi b/src/ellphi/__init__.pyi index 23178b6..f3d0e65 100644 --- a/src/ellphi/__init__.pyi +++ b/src/ellphi/__init__.pyi @@ -32,11 +32,11 @@ from .grad import ( pdist_tangency_grad as pdist_tangency_grad, coef_from_cov_grad as coef_from_cov_grad, ) -from .simplex import ( - SimplexTangencyGrad as SimplexTangencyGrad, - SimplexTangencyResult as SimplexTangencyResult, - tangency_simplex as tangency_simplex, - tangency_simplex_grad as tangency_simplex_grad, +from .cech import ( + CechGrad as CechGrad, + CechResult as CechResult, + cech as cech, + cech_grad as cech_grad, ) from ._version import __version__ as __version__ @@ -65,10 +65,10 @@ __all__ = [ "tangency_grad", "pdist_tangency_grad", "coef_from_cov_grad", - "SimplexTangencyResult", - "SimplexTangencyGrad", - "tangency_simplex", - "tangency_simplex_grad", + "CechResult", + "CechGrad", + "cech", + "cech_grad", "FloatArray", "__version__", "version_info", diff --git a/src/ellphi/_minimax_grad_python.py b/src/ellphi/_minimax_grad_python.py index 727b915..bf5ef20 100644 --- a/src/ellphi/_minimax_grad_python.py +++ b/src/ellphi/_minimax_grad_python.py @@ -15,8 +15,7 @@ MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. -This numerical engine is internal. The provisional public interface is -:mod:`ellphi.simplex`. +This numerical engine is internal. The public interface is :mod:`ellphi.cech`. Formula ------- diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index facbe81..b8c2c9b 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -43,8 +43,7 @@ of EllPHi under its MIT license; the ellcech source is MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. -This numerical engine is internal. The provisional public interface is -:mod:`ellphi.simplex`. +This numerical engine is internal. The public interface is :mod:`ellphi.cech`. Mathematical background ----------------------- diff --git a/src/ellphi/simplex.py b/src/ellphi/cech.py similarity index 81% rename from src/ellphi/simplex.py rename to src/ellphi/cech.py index b19562a..40456bf 100644 --- a/src/ellphi/simplex.py +++ b/src/ellphi/cech.py @@ -1,8 +1,9 @@ -"""Pairwise-aligned many-body tangency API (provisional names). +"""Anisotropic Čech filtration API. -The names in this module are provisional. ``tangency_simplex`` extends the -pairwise :func:`ellphi.tangency` contract to one or more packed ellipsoid -coefficient vectors while keeping the many-body numerical engine internal. +The :func:`cech` function computes the anisotropic Čech filtration time for +one or more packed ellipsoid coefficient vectors while keeping the many-body +numerical engine internal. For ``k = 2`` the Čech time equals the tangency +time computed by :func:`ellphi.tangency`, and ``cech`` agrees with it. """ from __future__ import annotations @@ -15,10 +16,10 @@ from .geometry import unpack_conic __all__ = [ - "SimplexTangencyResult", - "SimplexTangencyGrad", - "tangency_simplex", - "tangency_simplex_grad", + "CechResult", + "CechGrad", + "cech", + "cech_grad", ] @@ -26,8 +27,17 @@ _MACHINE_EPSILON = np.finfo(float).eps -class SimplexTangencyResult(NamedTuple): - """Result of a many-body tangency calculation. +class CechResult(NamedTuple): + """Result of an anisotropic Čech filtration calculation. + + For a simplex ``sigma`` of ellipsoids with quadratic functions ``f_i``, + ``t**2 = alpha(sigma) = min_x max_i f_i(x)`` is the least squared scale at + which all growing ellipsoids ``E_i(t) = {f_i <= t**2}`` share a point. + At the critical scale their intersection is the single point ``x*``; + active boundaries pass through ``x*`` and satisfy + ``sum_i mu_i grad f_i(x*) = 0`` with positive weights, but the boundaries + are not tangent to each other. Pairwise tangency is only the ``k = 2`` + special case. ``support`` is the thresholded weight support ``{i: mu[i] > weight_tol}``. ``active_set`` is the tight-constraint set at the returned point, @@ -41,9 +51,10 @@ class SimplexTangencyResult(NamedTuple): support (historical ellcech naming) and is not part of the public API. Attributes: - t: Tangency time ``sqrt(max_i f_i(point))``. - point: Tangency point, shape ``(d,)``. - mu: Simplex multipliers, shape ``(k,)``. + t: Čech filtration time; ``t**2 = alpha(sigma)``. + point: Common intersection point ``x*`` at the critical scale, shape + ``(d,)``. + mu: Lagrange multipliers (dual weights on the simplex), shape ``(k,)``. support: Indices with multiplier greater than ``weight_tol``. active_set: Tight constraints satisfying the numerical active-set test with ``active_tol``. @@ -56,16 +67,17 @@ class SimplexTangencyResult(NamedTuple): active_set: tuple[int, ...] -class SimplexTangencyGrad(NamedTuple): - """Many-body tangency result and coefficient-space gradient. +class CechGrad(NamedTuple): + """Čech filtration result and coefficient-space gradient. ``support`` and ``active_set`` have the definitions documented for - :class:`SimplexTangencyResult`. + :class:`CechResult`. Attributes: - t: Tangency time. - point: Tangency point, shape ``(d,)``. - mu: Simplex multipliers, shape ``(k,)``. + t: Čech filtration time; ``t**2 = alpha(sigma)``. + point: Common intersection point ``x*`` at the critical scale, shape + ``(d,)``. + mu: Lagrange multipliers (dual weights on the simplex), shape ``(k,)``. dt_dcoef: Gradient of ``t`` for independent packed coefficient perturbations, shape ``(k, m)``. support: Indices with multiplier greater than ``weight_tol``. @@ -193,7 +205,7 @@ def _centered_constraint_values( return values + offsets -def tangency_simplex( +def cech( coefs: np.ndarray, *, method: MethodName | str = "fw+bisect", @@ -206,8 +218,14 @@ def tangency_simplex( max_conditioning_steps: int = 8, newton_tol: float = 1e-14, newton_max_iter: int = 20, -) -> SimplexTangencyResult: - """Compute the common tangency time for a simplex of ellipsoids. +) -> CechResult: + """Compute the Čech filtration time for a simplex of ellipsoids. + + The returned ``t`` satisfies ``t**2 = alpha(sigma)``, where + ``alpha(sigma) = min_x max_i f_i(x)`` is the least squared scale at which + all growing ellipsoids share a common point. For ``k = 2`` the Čech time + equals the tangency time computed by :func:`ellphi.tangency`, and ``cech`` + agrees with it. Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. @@ -224,13 +242,14 @@ def tangency_simplex( newton_max_iter: Maximum Newton-polishing iterations. Returns: - A result using tangency time rather than squared filtration value. + A result containing the Čech filtration time rather than the squared + filtration value. Raises: ValueError: If the coefficient array is not two-dimensional, is empty, a tolerance is not finite and non-negative, or a coefficient row has a singular quadratic matrix, or the packed quadrics have no - common non-negative tangency scale. Packed input requires + common non-negative filtration scale. Packed input requires ``d >= 2``, as for :func:`ellphi.tangency`. RuntimeError: If the internal solver does not converge or produces a non-finite output. Solver diagnostics are included in the error. @@ -281,7 +300,7 @@ def tangency_simplex( if not result.converged or not finite: reason = "did not converge" if not result.converged else "was non-finite" raise RuntimeError( - "tangency_simplex " + "cech " f"{reason}: method={result.method!r}, n_iter={result.n_iter}, " f"diagnostics={result.metadata!r}" ) @@ -291,7 +310,7 @@ def tangency_simplex( ) if not np.all(np.isfinite(values)): raise RuntimeError( - "tangency_simplex was non-finite: " + "cech was non-finite: " f"method={result.method!r}, n_iter={result.n_iter}, " f"diagnostics={result.metadata!r}" ) @@ -303,7 +322,7 @@ def tangency_simplex( value_roundoff, ) if alpha < -negative_tolerance: - raise ValueError("packed quadrics have no common non-negative tangency scale") + raise ValueError("packed quadrics have no common non-negative filtration scale") t_squared = float(max(alpha, 0.0)) t = float(np.sqrt(max(0.0, t_squared))) support = tuple(int(i) for i in np.flatnonzero(result.weights > weight_tol)) @@ -312,7 +331,7 @@ def tangency_simplex( int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) ) - return SimplexTangencyResult( + return CechResult( t=t, point=result.circumcenter, mu=result.weights, @@ -321,10 +340,8 @@ def tangency_simplex( ) -def tangency_simplex_grad( - coefs: np.ndarray, **solver_kwargs: Any -) -> SimplexTangencyGrad: - """Return many-body tangency and its packed-coefficient gradient. +def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: + """Return the Čech filtration time and its coefficient-space gradient. For EllPHi's packed conic ``f_i(x) = coef_i @ basis(x)``, the basis is ``[x_j**2 if j == l else 2*x_j*x_l for j <= l, 2*x_0, ..., 2*x_(d-1), 1]`` @@ -353,23 +370,23 @@ def tangency_simplex_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - **solver_kwargs: Forwarded to :func:`tangency_simplex`. + **solver_kwargs: Forwarded to :func:`cech`. Returns: - Tangency data and ``dt_dcoef`` with shape ``(k, m)``. + Čech filtration data and ``dt_dcoef`` with shape ``(k, m)``. Raises: - ZeroDivisionError: If the tangency time is zero. + ZeroDivisionError: If the Čech filtration time is zero. RuntimeError: If the forward solve fails. """ coefs = np.asarray(coefs, dtype=float) - result = tangency_simplex(coefs, **solver_kwargs) + result = cech(coefs, **solver_kwargs) if result.t == 0.0: - raise ZeroDivisionError("tangency gradient is undefined when t == 0") + raise ZeroDivisionError("Čech gradient is undefined when t == 0") basis = _coefficient_basis(result.point) dt_dcoef = result.mu[:, np.newaxis] * basis[np.newaxis, :] / (2.0 * result.t) - return SimplexTangencyGrad( + return CechGrad( t=result.t, point=result.point, mu=result.mu, diff --git a/src/ellphi/simplex.pyi b/src/ellphi/cech.pyi similarity index 68% rename from src/ellphi/simplex.pyi rename to src/ellphi/cech.pyi index 66a8e09..7c0d5c7 100644 --- a/src/ellphi/simplex.pyi +++ b/src/ellphi/cech.pyi @@ -5,20 +5,20 @@ import numpy as np from ._minimax_python import MethodName __all__ = [ - "SimplexTangencyResult", - "SimplexTangencyGrad", - "tangency_simplex", - "tangency_simplex_grad", + "CechResult", + "CechGrad", + "cech", + "cech_grad", ] -class SimplexTangencyResult(NamedTuple): +class CechResult(NamedTuple): t: float point: np.ndarray mu: np.ndarray support: tuple[int, ...] active_set: tuple[int, ...] -class SimplexTangencyGrad(NamedTuple): +class CechGrad(NamedTuple): t: float point: np.ndarray mu: np.ndarray @@ -26,7 +26,7 @@ class SimplexTangencyGrad(NamedTuple): support: tuple[int, ...] active_set: tuple[int, ...] -def tangency_simplex( +def cech( coefs: np.ndarray, *, method: MethodName | str = "fw+bisect", @@ -39,7 +39,5 @@ def tangency_simplex( max_conditioning_steps: int = 8, newton_tol: float = 1e-14, newton_max_iter: int = 20, -) -> SimplexTangencyResult: ... -def tangency_simplex_grad( - coefs: np.ndarray, **solver_kwargs: Any -) -> SimplexTangencyGrad: ... +) -> CechResult: ... +def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: ... diff --git a/tests/test_simplex.py b/tests/test_cech.py similarity index 84% rename from tests/test_simplex.py rename to tests/test_cech.py index d4c9399..3a08eb1 100644 --- a/tests/test_simplex.py +++ b/tests/test_cech.py @@ -1,4 +1,4 @@ -"""Tests for the pairwise-aligned many-body tangency API.""" +"""Tests for the anisotropic Čech filtration API.""" from __future__ import annotations @@ -43,9 +43,9 @@ def _value_roundoff_bound(coefs: np.ndarray) -> float: ) -def test_pairwise_agrees_with_tangency(solver_backend, rng): +def test_pairwise_cech_agrees_with_tangency(solver_backend, rng): p, q = random_coef_pair(rng, dim=3) - result = ellphi.tangency_simplex(np.stack((p, q))) + result = ellphi.cech(np.stack((p, q))) pairwise = ellphi.tangency(p, q, backend=solver_backend) assert result.t == pytest.approx(pairwise.t, rel=1e-9) @@ -56,7 +56,9 @@ def test_pairwise_agrees_with_tangency(solver_backend, rng): @pytest.mark.parametrize("dimension", [2, 3]) -def test_unnormalized_pairwise_agrees_with_tangency(solver_backend, rng, dimension): +def test_unnormalized_pairwise_cech_agrees_with_tangency( + solver_backend, rng, dimension +): for _ in range(5): centers = rng.uniform(-2.0, 2.0, size=(2, dimension)) while np.linalg.norm(centers[0] - centers[1]) < 1.5: @@ -67,7 +69,7 @@ def test_unnormalized_pairwise_agrees_with_tangency(solver_backend, rng, dimensi coefs = coef_from_cov(centers, covariances) coefs[:, -1] += rng.uniform(0.1, 1.0) + rng.uniform(-1e-4, 1e-4, size=2) - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) pairwise = ellphi.tangency(coefs[0], coefs[1], backend=solver_backend) assert result.t == pytest.approx(pairwise.t, rel=1e-9) @@ -91,11 +93,11 @@ def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backen * max(1.0, abs(float(constant))) for matrix, constant in zip(matrices, constants) ) - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) pairwise = ellphi.tangency( pairwise_coefs[0], pairwise_coefs[1], backend=solver_backend ) - gradient = ellphi.tangency_simplex_grad(coefs) + gradient = ellphi.cech_grad(coefs) tri_i, tri_j = np.triu_indices(2) basis = np.concatenate( ( @@ -123,7 +125,7 @@ def test_translated_singleton_roundoff_negative_scale_is_clipped(): coefs = coef_from_cov(center, covariance[None]) value_roundoff = _value_roundoff_bound(coefs) - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) assert abs(result.t) <= np.sqrt(value_roundoff) @@ -134,7 +136,7 @@ def test_translated_coincident_roundoff_negative_scale_is_clipped(): coefs = np.repeat(coef_from_cov(center, covariance[None]), 2, axis=0) value_roundoff = _value_roundoff_bound(coefs) - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) assert abs(result.t) <= np.sqrt(value_roundoff) @@ -158,7 +160,7 @@ def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_num ) if condition_number <= 1e6: - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) assert result.t**2 <= precision_bound point = result.point else: @@ -182,7 +184,7 @@ def test_scaled_centres_from_cov_are_accepted(): ] ) - result = ellphi.tangency_simplex(coef_from_cov(centers, covariances)) + result = ellphi.cech(coef_from_cov(centers, covariances)) assert np.isfinite(result.t) assert result.active_set == (0, 1) @@ -197,9 +199,9 @@ def test_subthreshold_packed_constant_is_honoured_by_gradient(): perturbed_coefs[0, -1] += 5e-10 solver_kwargs = {"method": "fw+brentq+newton", "tol": 1e-12} - baseline = ellphi.tangency_simplex(baseline_coefs, **solver_kwargs) - perturbed = ellphi.tangency_simplex(perturbed_coefs, **solver_kwargs) - gradient = ellphi.tangency_simplex_grad(perturbed_coefs, **solver_kwargs) + baseline = ellphi.cech(baseline_coefs, **solver_kwargs) + perturbed = ellphi.cech(perturbed_coefs, **solver_kwargs) + gradient = ellphi.cech_grad(perturbed_coefs, **solver_kwargs) expected_change = baseline.mu[0] * 5e-10 assert perturbed.t**2 - baseline.t**2 == pytest.approx( @@ -212,8 +214,7 @@ def test_subthreshold_packed_constant_is_honoured_by_gradient(): plus[0, -1] += h minus[0, -1] -= h finite_difference = ( - ellphi.tangency_simplex(plus, **solver_kwargs).t - - ellphi.tangency_simplex(minus, **solver_kwargs).t + ellphi.cech(plus, **solver_kwargs).t - ellphi.cech(minus, **solver_kwargs).t ) / (2.0 * h) assert gradient.dt_dcoef[0, -1] == pytest.approx( finite_difference, rel=1e-6, abs=1e-12 @@ -227,9 +228,9 @@ def test_negative_packed_scale_raises(): coefs[:, -1] -= 2.0 with pytest.raises( - ValueError, match="packed quadrics have no common non-negative tangency scale" + ValueError, match="packed quadrics have no common non-negative filtration scale" ): - ellphi.tangency_simplex(coefs) + ellphi.cech(coefs) def test_packed_one_dimensional_input_is_rejected_like_pairwise(): @@ -238,7 +239,7 @@ def test_packed_one_dimensional_input_is_rejected_like_pairwise(): with pytest.raises( ValueError, match="packed input requires d >= 2, as for ellphi.tangency" ): - ellphi.tangency_simplex(coefs) + ellphi.cech(coefs) @pytest.mark.parametrize("method", list(get_args(MethodName))) @@ -246,7 +247,7 @@ def test_right_triangle_distinguishes_support_and_active_set(method): centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], 3, axis=0)) - result = ellphi.tangency_simplex(coefs, method=method, active_tol=1e-12) + result = ellphi.cech(coefs, method=method, active_tol=1e-12) assert result.t == pytest.approx(np.sqrt(2.0), rel=1e-12) np.testing.assert_allclose(result.point, [1.0, 1.0], atol=1e-12) @@ -257,9 +258,9 @@ def test_right_triangle_distinguishes_support_and_active_set(method): assert result.active_set == (0, 1, 2) -def test_singleton_and_empty_simplex(): +def test_singleton_and_empty_cech_input(): coefs = coef_from_cov(np.array([[1.0, -2.0]]), np.eye(2)[None]) - result = ellphi.tangency_simplex(coefs) + result = ellphi.cech(coefs) assert result.t == 0.0 np.testing.assert_allclose(result.point, [1.0, -2.0]) @@ -268,13 +269,13 @@ def test_singleton_and_empty_simplex(): assert result.active_set == (0,) with pytest.raises(ValueError, match="at least one vertex"): - ellphi.tangency_simplex(np.empty((0, coefs.shape[1]))) + ellphi.cech(np.empty((0, coefs.shape[1]))) def test_non_convergence_raises_with_diagnostics(): coefs = _random_coefs(5, 3, seed=101) with pytest.raises(RuntimeError) as exc_info: - ellphi.tangency_simplex(coefs, method="fw+bisect", max_iter=1, tol=1e-15) + ellphi.cech(coefs, method="fw+bisect", max_iter=1, tol=1e-15) message = str(exc_info.value) assert "method='fw+bisect'" in message @@ -295,7 +296,7 @@ def test_gradient_matches_independent_packed_central_difference(k, d, seed): "tol": 1e-12, "newton_tol": 1e-14, } - gradient = ellphi.tangency_simplex_grad(coefs, **solver_kwargs) + gradient = ellphi.cech_grad(coefs, **solver_kwargs) h = 1e-6 finite_difference = np.empty_like(coefs) for index in np.ndindex(coefs.shape): @@ -304,8 +305,7 @@ def test_gradient_matches_independent_packed_central_difference(k, d, seed): plus[index] += h minus[index] -= h finite_difference[index] = ( - ellphi.tangency_simplex(plus, **solver_kwargs).t - - ellphi.tangency_simplex(minus, **solver_kwargs).t + ellphi.cech(plus, **solver_kwargs).t - ellphi.cech(minus, **solver_kwargs).t ) / (2.0 * h) error = _relative_error(gradient.dt_dcoef, finite_difference) @@ -314,7 +314,7 @@ def test_gradient_matches_independent_packed_central_difference(k, d, seed): def test_pairwise_gradient_identity(solver_backend, rng): p, q = random_coef_pair(rng, dim=3) - gradient = ellphi.tangency_simplex_grad(np.stack((p, q))) + gradient = ellphi.cech_grad(np.stack((p, q))) pairwise = ellphi.tangency_grad(p, q, backend=solver_backend) error_p = _relative_error(gradient.dt_dcoef[0], pairwise.dt_dp) @@ -326,10 +326,10 @@ def test_pairwise_gradient_identity(solver_backend, rng): def test_zero_time_gradient_raises(): coefs = coef_from_cov(np.array([[1.0, -2.0]]), np.eye(2)[None]) with pytest.raises(ZeroDivisionError, match="t == 0"): - ellphi.tangency_simplex_grad(coefs) + ellphi.cech_grad(coefs) -@pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) def test_unnormalized_constant_agrees_with_expected(api): coefs = coef_from_cov( np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) @@ -351,17 +351,17 @@ def test_public_surrogate_methods(method): coefs = pack_conic(matrices, linear, constants) if method == "scipy-slsqp": - result = ellphi.tangency_simplex(coefs, method=method) + result = ellphi.cech(coefs, method=method) assert result.t == pytest.approx(np.sqrt(0.9024444260258915), abs=1e-8) else: with pytest.raises(RuntimeError): - ellphi.tangency_simplex(coefs, method=method) + ellphi.cech(coefs, method=method) -@pytest.mark.parametrize("api", [ellphi.tangency_simplex, ellphi.tangency_simplex_grad]) +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @pytest.mark.parametrize("name", ["active_tol", "weight_tol"]) @pytest.mark.parametrize("value", [np.nan, -1.0]) -def test_simplex_tolerances_must_be_finite_and_nonnegative(api, name, value): +def test_cech_tolerances_must_be_finite_and_nonnegative(api, name, value): coefs = coef_from_cov( np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) ) @@ -377,18 +377,18 @@ def test_public_tol_must_be_finite_and_positive(value): ) with pytest.raises(ValueError, match="tol must be finite and > 0"): - ellphi.tangency_simplex(coefs, tol=value) + ellphi.cech(coefs, tol=value) def test_public_namedtuple_field_order(): - assert ellphi.SimplexTangencyResult._fields == ( + assert ellphi.CechResult._fields == ( "t", "point", "mu", "support", "active_set", ) - assert ellphi.SimplexTangencyGrad._fields == ( + assert ellphi.CechGrad._fields == ( "t", "point", "mu", @@ -400,10 +400,10 @@ def test_public_namedtuple_field_order(): def test_public_exports_hide_internal_engine(): expected = { - "SimplexTangencyResult", - "SimplexTangencyGrad", - "tangency_simplex", - "tangency_simplex_grad", + "CechResult", + "CechGrad", + "cech", + "cech_grad", } assert expected <= set(ellphi.__all__) assert not { From 5a799d556ae98b40b35f55c37cf581ae7c286dcf Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 22:47:16 +0900 Subject: [PATCH 07/29] fix: stabilize many-body Newton and FW convergence Thread matrix stabilization through Newton polishing and convergence checks, keep stabilized SLSQP objectives consistent, report successful FW fallbacks, and prevent thresholded-face false convergence. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 214 +++++++++++++++++++++++++++------- tests/test_minimax.py | 108 +++++++++++++++++ tests/test_minimax_methods.py | 15 +++ 3 files changed, 296 insertions(+), 41 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index b8c2c9b..dd47e33 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -19,7 +19,7 @@ Damped Newton uses diagonal regularization at that threshold instead. * ``newton-cold`` starts at the uniform weights. If Newton does not converge, it falls back to a freshly run ``fw+bisect`` iterate from that same uniform - start and explicitly reports ``converged=False``. + start and reports the fallback's convergence status. * Newton failure statuses force ``converged=False``; these statuses are ``"empty_face"``, ``"armijo_rejected"``, ``"factorization_failed"``, ``"ill_conditioned_hessian"``, ``"linear_solve_failed"``, @@ -31,9 +31,9 @@ unbacktracked full step. * The objective supports additive per-constraint offsets, including general packed conic constants. -* For positive regularization, the SLSQP objective is the regularized dual - rather than ``dot(mu, f)``; this fixes the inherited ellcech objective and - Jacobian mismatch. +* For stabilization, the SLSQP and damped-Newton objectives are the + regularized dual rather than ``dot(mu, f)``; this keeps their objective and + Jacobian consistent with the conditioned matrix. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. @@ -257,6 +257,50 @@ def _condition_matrix( return A_reg +def _conditioning_shift_gradient( + mu: np.ndarray, + matrices: np.ndarray, + A_mu: np.ndarray, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> np.ndarray: + """Differentiate the active scalar conditioning shift with respect to mu.""" + if condition_number_limit is None: + return np.zeros(mu.shape, dtype=float) + + spectral_scale = float(np.linalg.norm(A_mu, ord=2)) + if spectral_scale < 1.0: + return np.zeros(mu.shape, dtype=float) + eps_floor = np.finfo(A_mu.dtype).eps * spectral_scale + base_shift_from_floor = regularization < eps_floor + if not base_shift_from_floor: + base_shift = regularization + base_gradient = np.zeros(mu.shape, dtype=float) + else: + base_shift = eps_floor + base_gradient = np.empty(mu.shape, dtype=float) + A_used = _condition_matrix( + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + effective_shift = float(np.trace(A_used - A_mu) / A_mu.shape[0]) + escalation = effective_shift / base_shift + _, eigenvectors = np.linalg.eigh(A_mu) + leading_vector = eigenvectors[:, -1] + if base_shift_from_floor: + spectral_gradient = np.einsum( + "i,kij,j->k", leading_vector, matrices, leading_vector + ) + base_gradient = np.finfo(A_mu.dtype).eps * spectral_gradient + if spectral_scale == 1.0: + base_gradient *= 0.5 + return escalation * base_gradient + + def _validate_tolerance( name: str, value: float, *, strictly_positive: bool = False ) -> None: @@ -341,6 +385,22 @@ def _eval_f( return xstar, f +def _regularized_dual_value( + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray | None, + xstar: np.ndarray, +) -> float: + """Evaluate the dual value for the matrix used to obtain ``xstar``.""" + c = np.einsum("ki,kij,kj->k", centers, matrices, centers) + if offsets is not None: + c = c + offsets + b_mu = np.einsum("k,ki->i", mu, Ax) + return float(np.dot(mu, c) - np.dot(b_mu, xstar)) + + def _exact_line_search( s: int, v: int, @@ -522,16 +582,17 @@ def _run_fw_bisect( active_mask = np.ones_like(mu, dtype=bool) f_active = np.where(active_mask, f, np.inf) v = int(np.argmin(f_active)) + if s == v: + positive_mask = mu > 0.0 + positive_mask[s] = False + if np.any(positive_mask): + v = int(np.argmin(np.where(positive_mask, f, np.inf))) - fw_gap = float(f[s] - np.dot(mu, f)) + fw_gap = float(np.max(f) - np.dot(mu, f)) if fw_gap < tol: converged = True break - if s == v: - converged = True - break - gamma_max = float(mu[v]) gamma = _exact_line_search( s, @@ -599,16 +660,17 @@ def _run_fw_brentq( active_mask = np.ones_like(mu, dtype=bool) f_active = np.where(active_mask, f, np.inf) v = int(np.argmin(f_active)) + if s == v: + positive_mask = mu > 0.0 + positive_mask[s] = False + if np.any(positive_mask): + v = int(np.argmin(np.where(positive_mask, f, np.inf))) - fw_gap = float(f[s] - np.dot(mu, f)) + fw_gap = float(np.max(f) - np.dot(mu, f)) if fw_gap < tol: converged = True break - if s == v: - converged = True - break - gamma_max = float(mu[v]) gamma, ls_evals = _brentq_line_search( s, @@ -669,6 +731,9 @@ def _newton_polish( weight_tol: float = _DEFAULT_WEIGHT_TOL, max_iter: int = _NEWTON_MAX_ITER, tol: float = _NEWTON_TOL, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, ) -> tuple[np.ndarray, int, dict]: """Newton polishing on the dual restricted to the current active face. @@ -722,11 +787,17 @@ def _newton_polish( A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) + A_used = _condition_matrix( + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) try: - chol = linalg.cho_factor(A_mu, check_finite=False) + chol = linalg.cho_factor(A_used, check_finite=False) xstar = linalg.cho_solve(chol, b_mu, check_finite=False) - d = A_mu.shape[0] + d = A_used.shape[0] Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) except linalg.LinAlgError: newton_status = "factorization_failed" @@ -799,6 +870,9 @@ def _damped_newton_polish( reidentify_face: bool = True, max_iter: int = _NEWTON_MAX_ITER, tol: float = _NEWTON_TOL, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, ) -> tuple[np.ndarray, int, dict]: """Newton polishing with Armijo backtracking and conditioning safeguards. @@ -853,11 +927,17 @@ def _damped_newton_polish( A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) + A_used = _condition_matrix( + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) try: - chol = linalg.cho_factor(A_mu, check_finite=False) + chol = linalg.cho_factor(A_used, check_finite=False) xstar = linalg.cho_solve(chol, b_mu, check_finite=False) - d = A_mu.shape[0] + d = A_used.shape[0] Amu_inv = linalg.cho_solve(chol, np.eye(d), check_finite=False) except linalg.LinAlgError: newton_status = "factorization_failed" @@ -909,11 +989,16 @@ def _damped_newton_polish( Ax, centers, offsets, - regularization=0.0, - condition_number_limit=None, - max_conditioning_steps=0, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) - g_current = float(np.dot(mu, f_full)) + if regularization == 0.0 and condition_number_limit is None: + g_current = float(np.dot(mu, f_full)) + else: + g_current = _regularized_dual_value( + mu, matrices, Ax, centers, offsets, xstar + ) if g_current > best_g: best_g = g_current best_mu = mu.copy() @@ -935,17 +1020,22 @@ def _damped_newton_polish( continue mu_trial /= s - _, f_trial = _eval_f( + xstar_trial, f_trial = _eval_f( mu_trial, matrices, Ax, centers, offsets, - regularization=0.0, - condition_number_limit=None, - max_conditioning_steps=0, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) - g_trial = float(np.dot(mu_trial, f_trial)) + if regularization == 0.0 and condition_number_limit is None: + g_trial = float(np.dot(mu_trial, f_trial)) + else: + g_trial = _regularized_dual_value( + mu_trial, matrices, Ax, centers, offsets, xstar_trial + ) armijo_target = g_current + _ARMIJO_SIGMA * step * float(r @ delta) armijo_roundoff = ( 8.0 @@ -1025,18 +1115,24 @@ def _slsqp_objective_and_gradient( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - if regularization == 0.0: + if regularization == 0.0 and condition_number_limit is None: # Keep the unregularized objective path bitwise identical. return -float(np.dot(mu, f)), -f - c = np.einsum("ki,kij,kj->k", centers, matrices, centers) - if offsets is not None: - c = c + offsets - b_mu = np.einsum("k,ki->i", mu, Ax) - # The regularized dual is g_r(mu) = sum_i mu_i c_i - - # b(mu)^T (A(mu) + r I)^(-1) b(mu), whose gradient is f. - g_regularized = float(np.dot(mu, c) - np.dot(b_mu, xstar)) - return -g_regularized, -f + # The stabilized dual is g_r(mu) = sum_i mu_i c_i - + # b(mu)^T A_used(mu)^(-1) b(mu), whose gradient is f for the + # effective matrix used in this evaluation. + g_regularized = _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + A_mu = np.einsum("k,kij->ij", mu, matrices) + shift_gradient = _conditioning_shift_gradient( + mu, + matrices, + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + return -g_regularized, -f - shift_gradient * float(np.dot(xstar, xstar)) def _run_scipy_slsqp( @@ -1108,6 +1204,10 @@ def _check_newton_convergence( converged: bool, newton_tol: float, newton_status: str, + *, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, ) -> bool: """Recheck convergence after Newton polishing.""" failure_statuses = { @@ -1125,7 +1225,13 @@ def _check_newton_convergence( try: A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) - chol = linalg.cho_factor(A_mu, check_finite=False) + A_used = _condition_matrix( + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + chol = linalg.cho_factor(A_used, check_finite=False) xstar_check = linalg.cho_solve(chol, b_mu, check_finite=False) d_check = xstar_check[np.newaxis, :] - centers f_check = np.einsum("ki,kij,kj->k", d_check, matrices, d_check) @@ -1192,9 +1298,8 @@ def solve_minimax( weight_tol: Threshold defining the weight support ``active_set``. It also selects the face used by Newton polishing. regularization: Non-negative diagonal shift applied to ``A(mu)`` in - Frank-Wolfe evaluations and line searches, SLSQP evaluations, and - the final evaluation. Newton-polishing solves use the unshifted - ``A(mu)``. + Frank-Wolfe evaluations and line searches, SLSQP evaluations, + Newton polishing, and the final evaluation. condition_number_limit: Optional target for ``cond(A(mu))``. If the target is exceeded, the diagonal shift is escalated by factors of 10 for at most ``max_conditioning_steps`` attempts; the target is @@ -1320,6 +1425,9 @@ def solve_minimax( weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] @@ -1333,6 +1441,9 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw metadata.update(meta_newton) @@ -1352,6 +1463,9 @@ def solve_minimax( weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] @@ -1365,6 +1479,9 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) metadata.update(meta_fw) metadata.update(meta_newton) @@ -1384,6 +1501,9 @@ def solve_minimax( weight_tol=weight_tol, max_iter=newton_max_iter, tol=newton_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] @@ -1397,6 +1517,9 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw metadata.update(meta_newton) @@ -1415,6 +1538,9 @@ def solve_minimax( reidentify_face=False, max_iter=newton_max_iter, tol=newton_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] @@ -1428,14 +1554,20 @@ def solve_minimax( True, newton_tol, meta_newton["newton_status"], + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, ) if not converged: - mu, _, n_iter_fw = _run_fw_bisect( + mu, fallback_converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) + converged = fallback_converged n_iter += n_iter_fw meta_newton["fallback_method"] = "fw+bisect" meta_newton["fallback_fw_iters"] = n_iter_fw + meta_newton["fallback_converged"] = fallback_converged + meta_newton["newton_status"] = "fw_fallback" metadata.update(meta_newton) elif method == "scipy-slsqp": diff --git a/tests/test_minimax.py b/tests/test_minimax.py index c0a854c..d240138 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -278,6 +278,23 @@ def test_zero_offsets_are_bitwise_identical(self, method): np.testing.assert_array_equal(explicit_zeros.weights, baseline.weights) assert explicit_zeros.converged == baseline.converged + explicit_stability_zeros = solve_minimax( + matrices, + centers, + method=method, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + assert explicit_stability_zeros.alpha == baseline.alpha + np.testing.assert_array_equal( + explicit_stability_zeros.circumcenter, baseline.circumcenter + ) + np.testing.assert_array_equal( + explicit_stability_zeros.weights, baseline.weights + ) + assert explicit_stability_zeros.converged == baseline.converged + def test_explicit_default_controls_match_previous_behaviour(self): rng = np.random.default_rng(321) centers = rng.standard_normal((4, 3)) @@ -443,6 +460,97 @@ def test_regularized_slsqp_objective_gradient_matches(self): np.testing.assert_allclose(finite_difference, gradient, rtol=1e-6, atol=1e-8) assert np.isfinite(objective) + def test_conditioning_slsqp_objective_gradient_matches(self): + matrices = np.array( + [ + [[1e-8, 0.0], [0.0, 1.0]], + [[2e-8, 0.0], [0.0, 1.0]], + [[3e-8, 0.0], [0.0, 1.0]], + ] + ) + centers = np.array([[0.0, 0.0], [1.0, -0.5], [-0.5, 1.0]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + mu = np.array([0.2, 0.3, 0.5]) + kwargs = { + "regularization": 0.0, + "condition_number_limit": 1e4, + "max_conditioning_steps": 12, + } + objective, gradient = minimax_mod._slsqp_objective_and_gradient( + mu, matrices, Ax, centers, None, **kwargs + ) + step = 1e-6 + finite_difference = np.empty_like(mu) + for i in range(mu.size): + plus = mu.copy() + minus = mu.copy() + plus[i] += step + minus[i] -= step + plus_value, _ = minimax_mod._slsqp_objective_and_gradient( + plus, matrices, Ax, centers, None, **kwargs + ) + minus_value, _ = minimax_mod._slsqp_objective_and_gradient( + minus, matrices, Ax, centers, None, **kwargs + ) + finite_difference[i] = (plus_value - minus_value) / (2.0 * step) + + np.testing.assert_allclose(finite_difference, gradient, rtol=1e-6, atol=1e-8) + assert np.isfinite(objective) + + def test_newton_polishing_uses_stabilized_stationarity(self): + matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + stabilized = solve_minimax( + matrices, + centers, + method="fw+bisect+newton", + regularization=1.0, + tol=1e-12, + ) + unadjusted = solve_minimax( + matrices, centers, method="fw+bisect+newton", tol=1e-12 + ) + Ax = np.einsum("kij,kj->ki", matrices, centers) + _, values = minimax_mod._eval_f( + stabilized.weights, + matrices, + Ax, + centers, + None, + regularization=1.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert stabilized.converged + assert np.max(values) - stabilized.weights @ values < 1e-12 + assert stabilized.alpha == pytest.approx(4.0 / 9.0, abs=1e-12) + assert unadjusted.alpha == pytest.approx(stabilized.alpha, abs=1e-12) + assert not np.array_equal(stabilized.weights, unadjusted.weights) + + def test_fw_gap_ignores_subthreshold_positive_weights(self): + matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) + centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + mu = np.array([0.405, 0.405, 0.19]) + + _, converged, n_iter = minimax_mod._run_fw_bisect( + matrices, + Ax, + centers, + None, + mu, + tol=1e-12, + max_iter=1, + weight_tol=0.2, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert n_iter == 1 + assert not converged + def test_slsqp_converges_with_regularization(self): matrices = np.array( [ diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index f179503..a853ef0 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -288,6 +288,21 @@ def test_result_finite(self, seed): assert np.isfinite(res.alpha) assert np.all(np.isfinite(res.circumcenter)) + def test_converged_fw_fallback_is_reported(self): + matrices, centers = _random_simplex(5, 3, seed=0) + result = solve_minimax( + matrices, + centers, + method="newton-cold", + newton_max_iter=1, + tol=1e-10, + ) + + assert result.converged + assert result.metadata is not None + assert result.metadata["newton_status"] == "fw_fallback" + assert result.metadata["fallback_converged"] is True + # --------------------------------------------------------------------------- # fw+bisect+damped-newton specific From c878998467e291a8f5bbf244dd94dff8e56581ef Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 22:47:23 +0900 Subject: [PATCH 08/29] refactor: keep Cech stabilization controls private Remove stabilization keywords from the public value and gradient APIs, update their stubs and guide, and cover rejected controls plus the public fallback path. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 7 +++++ src/ellphi/cech.py | 57 ++++++++++++++++++++--------------- src/ellphi/cech.pyi | 17 ++++++++--- tests/test_cech.py | 30 ++++++++++++++++++ 4 files changed, 81 insertions(+), 30 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index 5766248..1fe6f7a 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -22,6 +22,13 @@ ordered as `(t, point, mu, dt_dcoef, support, active_set)`. - `active_set`: the tight-constraint set at the returned point, `I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`. +The public `cech` and `cech_grad` signatures intentionally do not expose +matrix stabilization controls such as `regularization`, +`condition_number_limit`, or `max_conditioning_steps`. Stabilized solves are +available only through the private `ellphi._minimax_python` engine for +research use, and the public coefficient-space gradient carries no guarantee +for those stabilized solves. + At the critical scale the intersection is the single point `x*`. The active ellipsoid boundaries pass through `x*` and satisfy `sum_i mu_i grad f_i(x*) = 0`, so their normals are positively dependent; diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 40456bf..5165757 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -8,7 +8,7 @@ from __future__ import annotations -from typing import Any, NamedTuple +from typing import NamedTuple import numpy as np @@ -128,24 +128,15 @@ def _validate_solver_parameters( tol: float, max_iter: int, weight_tol: float, - regularization: float, - condition_number_limit: float | None, - max_conditioning_steps: int, newton_tol: float, newton_max_iter: int, ) -> None: """Validate public solver controls before dispatching to the engine.""" _validate_tolerance("tol", tol, strictly_positive=True) _validate_tolerance("newton_tol", newton_tol) - _validate_tolerance("regularization", regularization) _validate_tolerance("weight_tol", weight_tol) _validate_positive_int("max_iter", max_iter) _validate_positive_int("newton_max_iter", newton_max_iter) - _validate_positive_int("max_conditioning_steps", max_conditioning_steps) - if condition_number_limit is not None and ( - not np.isfinite(condition_number_limit) or condition_number_limit <= 1.0 - ): - raise ValueError("condition_number_limit must be finite and > 1 when provided") if weight_tol >= 1.0 / k: raise ValueError("weight_tol must satisfy 0 <= weight_tol < 1/k") @@ -213,9 +204,6 @@ def cech( max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, - regularization: float = 0.0, - condition_number_limit: float | None = None, - max_conditioning_steps: int = 8, newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: @@ -235,12 +223,12 @@ def cech( weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set`` as the tight-constraint set at the returned point. - regularization: Optional diagonal regularization of weighted matrices. - condition_number_limit: Optional weighted-matrix condition target. - max_conditioning_steps: Maximum conditioning-shift escalations. newton_tol: Newton-polishing residual tolerance. newton_max_iter: Maximum Newton-polishing iterations. + Stabilized solves are available only through the private minimax engine; + they are research controls and carry no public gradient guarantee. + Returns: A result containing the Čech filtration time rather than the squared filtration value. @@ -270,9 +258,6 @@ def cech( tol=tol, max_iter=max_iter, weight_tol=weight_tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, newton_tol=newton_tol, newton_max_iter=newton_max_iter, ) @@ -286,9 +271,6 @@ def cech( tol=tol, max_iter=max_iter, weight_tol=weight_tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, newton_tol=newton_tol, newton_max_iter=newton_max_iter, ) @@ -340,7 +322,17 @@ def cech( ) -def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: +def cech_grad( + coefs: np.ndarray, + *, + method: MethodName | str = "fw+bisect", + tol: float = 1e-9, + max_iter: int = 2000, + weight_tol: float = 1e-10, + active_tol: float = 1e-9, + newton_tol: float = 1e-14, + newton_max_iter: int = 20, +) -> CechGrad: """Return the Čech filtration time and its coefficient-space gradient. For EllPHi's packed conic ``f_i(x) = coef_i @ basis(x)``, the basis is @@ -370,7 +362,13 @@ def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - **solver_kwargs: Forwarded to :func:`cech`. + method: Internal many-body solver method. + tol: Frank-Wolfe gap tolerance. + max_iter: Maximum Frank-Wolfe iterations. + weight_tol: Threshold defining ``support``. + active_tol: Relative tolerance defining ``active_set``. + newton_tol: Newton-polishing residual tolerance. + newton_max_iter: Maximum Newton-polishing iterations. Returns: Čech filtration data and ``dt_dcoef`` with shape ``(k, m)``. @@ -380,7 +378,16 @@ def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: RuntimeError: If the forward solve fails. """ coefs = np.asarray(coefs, dtype=float) - result = cech(coefs, **solver_kwargs) + result = cech( + coefs, + method=method, + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + active_tol=active_tol, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, + ) if result.t == 0.0: raise ZeroDivisionError("Čech gradient is undefined when t == 0") diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 7c0d5c7..9696f08 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -1,4 +1,4 @@ -from typing import Any, NamedTuple +from typing import NamedTuple import numpy as np @@ -34,10 +34,17 @@ def cech( max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, - regularization: float = 0.0, - condition_number_limit: float | None = None, - max_conditioning_steps: int = 8, newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: ... -def cech_grad(coefs: np.ndarray, **solver_kwargs: Any) -> CechGrad: ... +def cech_grad( + coefs: np.ndarray, + *, + method: MethodName | str = "fw+bisect", + tol: float = 1e-9, + max_iter: int = 2000, + weight_tol: float = 1e-10, + active_tol: float = 1e-9, + newton_tol: float = 1e-14, + newton_max_iter: int = 20, +) -> CechGrad: ... diff --git a/tests/test_cech.py b/tests/test_cech.py index 3a08eb1..e8708ac 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -283,6 +283,36 @@ def test_non_convergence_raises_with_diagnostics(): assert "diagnostics=" in message +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) +@pytest.mark.parametrize( + "name, value", + [ + ("regularization", 1e-6), + ("condition_number_limit", 1e6), + ("max_conditioning_steps", 4), + ], +) +def test_public_api_rejects_private_stabilization_controls(api, name, value): + coefs = _random_coefs(2, 2, seed=107) + + with pytest.raises(TypeError): + api(coefs, **{name: value}) + + +def test_public_newton_cold_returns_a_successful_fw_fallback(): + coefs = _random_coefs(5, 3, seed=0) + + result = ellphi.cech( + coefs, + method="newton-cold", + newton_max_iter=1, + tol=1e-10, + ) + + assert np.isfinite(result.t) + assert result.active_set + + @pytest.mark.parametrize("k,d,seed", [(3, 2, 201), (4, 2, 203)]) def test_gradient_matches_independent_packed_central_difference(k, d, seed): rng = np.random.default_rng(seed) From 6d0e6fe3611d593183a4f6e86ce53ef52f04f6b6 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 22:57:28 +0900 Subject: [PATCH 09/29] =?UTF-8?q?fix:=20reject=20non-SPD=20quadratic=20blo?= =?UTF-8?q?cks=20in=20the=20public=20=C4=8Cech=20API?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/cech.py | 36 +++++++++++++++++++++++++++++-- tests/test_cech.py | 53 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 87 insertions(+), 2 deletions(-) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 5165757..ab07608 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -141,6 +141,35 @@ def _validate_solver_parameters( raise ValueError("weight_tol must satisfy 0 <= weight_tol < 1/k") +def _validate_quadratic_matrices(matrices: np.ndarray) -> None: + """Validate symmetry and positive definiteness before solving centers.""" + for row, matrix in enumerate(matrices): + if not np.all(np.isfinite(matrix)): + raise ValueError(f"coefficient row {row} has a non-finite quadratic matrix") + + condition_number = float(np.linalg.cond(matrix, 2)) + if not np.isfinite(condition_number): + condition_number = 1.0 + symmetry_rtol = ( + _NEGATIVE_ALPHA_ROUNDING_FACTOR + * _MACHINE_EPSILON + * max(1.0, condition_number) + ) + matrix_scale = float(np.linalg.norm(matrix, ord=np.inf)) + symmetry_error = float(np.linalg.norm(matrix - matrix.T, ord=np.inf)) + if symmetry_error > symmetry_rtol * matrix_scale: + raise ValueError( + f"coefficient row {row} has a non-symmetric quadratic matrix" + ) + + try: + np.linalg.cholesky(matrix) + except np.linalg.LinAlgError as exc: + raise ValueError( + f"coefficient row {row} has a non-positive definite quadratic matrix" + ) from exc + + def _prepare_coefs( coefs: np.ndarray, ) -> tuple[np.ndarray, np.ndarray, np.ndarray, float]: @@ -155,6 +184,7 @@ def _prepare_coefs( first. """ matrices, linear, constants = unpack_conic(coefs) + _validate_quadratic_matrices(matrices) centers = np.empty_like(linear) offsets = np.empty_like(constants) value_roundoff = 0.0 @@ -236,8 +266,9 @@ def cech( Raises: ValueError: If the coefficient array is not two-dimensional, is empty, a tolerance is not finite and non-negative, or a coefficient row - has a singular quadratic matrix, or the packed quadrics have no - common non-negative filtration scale. Packed input requires + has a non-symmetric or non-positive-definite quadratic matrix, or + the packed quadrics have no common non-negative filtration scale. + Packed input requires ``d >= 2``, as for :func:`ellphi.tangency`. RuntimeError: If the internal solver does not converge or produces a non-finite output. Solver diagnostics are included in the error. @@ -374,6 +405,7 @@ def cech_grad( Čech filtration data and ``dt_dcoef`` with shape ``(k, m)``. Raises: + ValueError: If a quadratic block is not symmetric positive definite. ZeroDivisionError: If the Čech filtration time is zero. RuntimeError: If the forward solve fails. """ diff --git a/tests/test_cech.py b/tests/test_cech.py index e8708ac..f988c0c 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -2,6 +2,7 @@ from __future__ import annotations +import importlib from typing import get_args import numpy as np @@ -14,6 +15,9 @@ from .factories import minimax_public_surrogate, random_coef_pair, random_covariance +cech_module = importlib.import_module("ellphi.cech") + + def _random_coefs(k: int, d: int, seed: int) -> np.ndarray: rng = np.random.default_rng(seed) centers = rng.uniform(-2.0, 2.0, size=(k, d)) @@ -233,6 +237,55 @@ def test_negative_packed_scale_raises(): ellphi.cech(coefs) +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) +@pytest.mark.parametrize( + "matrix", + [ + np.diag([1.0, -1.0]), + -np.eye(2), + ], +) +def test_public_api_rejects_non_spd_quadratic_blocks(api, matrix): + coefs = pack_conic(matrix[None], np.zeros((1, 2)), np.zeros(1)) + + with pytest.raises( + ValueError, + match=r"coefficient row 0 has a non-positive definite quadratic matrix", + ): + api(coefs) + + +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) +def test_public_api_rejects_non_symmetric_quadratic_blocks(api, monkeypatch): + matrices = np.array([[[2.0, 0.25], [0.0, 2.0]]]) + linear = np.zeros((1, 2)) + constants = np.zeros(1) + monkeypatch.setattr( + cech_module, + "unpack_conic", + lambda _: (matrices, linear, constants), + ) + + with pytest.raises( + ValueError, + match=r"coefficient row 0 has a non-symmetric quadratic matrix", + ): + api(np.zeros((1, 6))) + + +@pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) +def test_public_api_accepts_ill_conditioned_spd_quadratic_block(api): + matrix = np.diag([1.0, 1e12]) + matrices = np.repeat(matrix[None], 2, axis=0) + centers = np.array([[0.0, 0.0], [2.0, 0.0]]) + linear = -np.einsum("kij,kj->ki", matrices, centers) + constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) + coefs = pack_conic(matrices, linear, constants) + + result = api(coefs) + assert result.t == pytest.approx(1.0) + + def test_packed_one_dimensional_input_is_rejected_like_pairwise(): coefs = np.array([[1.0, -2.0, 1.0], [1.0, -4.0, 4.0]]) From 9c173233843b377bf4c90425db037e25ad823a39 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 23:05:49 +0900 Subject: [PATCH 10/29] fix: consistent stabilisation in singleton and FW-gap paths; allow zero conditioning escalations Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 175 +++++++++++++++++++++++++++------- tests/test_minimax.py | 54 +++++++++++ 2 files changed, 193 insertions(+), 36 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index dd47e33..1725349 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -320,6 +320,16 @@ def _validate_positive_int(name: str, value: int) -> None: raise ValueError(f"{name} must be a positive integer") +def _validate_non_negative_int(name: str, value: int) -> None: + """Validate a non-negative integer solver parameter.""" + if ( + isinstance(value, (bool, np.bool_)) + or not isinstance(value, (int, np.integer)) + or value < 0 + ): + raise ValueError(f"{name} must be a non-negative integer") + + def _cholesky_solve( A: np.ndarray, b: np.ndarray, @@ -385,6 +395,35 @@ def _eval_f( return xstar, f +def _dual_gradient( + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray | None, + xstar: np.ndarray, + f: np.ndarray, + *, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> np.ndarray: + """Return the gradient of the dual represented by ``xstar`` and ``f``.""" + if regularization == 0.0 and condition_number_limit is None: + return f + + A_mu = np.einsum("k,kij->ij", mu, matrices) + shift_gradient = _conditioning_shift_gradient( + mu, + matrices, + A_mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + return f + shift_gradient * float(np.dot(xstar, xstar)) + + def _regularized_dual_value( mu: np.ndarray, matrices: np.ndarray, @@ -417,8 +456,8 @@ def _exact_line_search( ) -> float: """Find gamma* in [0, gamma_max] that maximises g along the pairwise direction. - Bisects on h(gamma) = f_s(x*(mu + gamma*(e_s - e_v))) - f_v(...) = 0. - dg/dgamma = f_s(x*(gamma)) - f_v(x*(gamma)) (positive at 0, negative at gamma_max). + Bisects on the stabilized dual directional derivative + ``h(gamma) = grad_s - grad_v``. """ if gamma_max <= 0.0: return 0.0 @@ -427,17 +466,29 @@ def h(gamma: float) -> float: mu_g = mu.copy() mu_g[s] += gamma mu_g[v] -= gamma - _, f_g = _eval_f( + x_g, f_g = _eval_f( + mu_g, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient_g = _dual_gradient( mu_g, matrices, Ax, centers, offsets, + x_g, + f_g, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(f_g[s] - f_g[v]) + return float(gradient_g[s] - gradient_g[v]) h0 = h(0.0) if h0 <= 0.0: @@ -493,17 +544,29 @@ def h(gamma: float) -> float: mu_g = mu.copy() mu_g[s] += gamma mu_g[v] -= gamma - _, f_g = _eval_f( + x_g, f_g = _eval_f( + mu_g, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient_g = _dual_gradient( mu_g, matrices, Ax, centers, offsets, + x_g, + f_g, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(f_g[s] - f_g[v]) + return float(gradient_g[s] - gradient_g[v]) h0 = h(0.0) if h0 <= 0.0: @@ -576,19 +639,32 @@ def _run_fw_bisect( max_conditioning_steps=max_conditioning_steps, ) - s = int(np.argmax(f)) + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + + s = int(np.argmax(gradient)) active_mask = mu > weight_tol if not np.any(active_mask): active_mask = np.ones_like(mu, dtype=bool) - f_active = np.where(active_mask, f, np.inf) - v = int(np.argmin(f_active)) + gradient_active = np.where(active_mask, gradient, np.inf) + v = int(np.argmin(gradient_active)) if s == v: positive_mask = mu > 0.0 positive_mask[s] = False if np.any(positive_mask): - v = int(np.argmin(np.where(positive_mask, f, np.inf))) + v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(f) - np.dot(mu, f)) + fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break @@ -654,19 +730,32 @@ def _run_fw_brentq( ) total_fevals += 1 - s = int(np.argmax(f)) + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + + s = int(np.argmax(gradient)) active_mask = mu > weight_tol if not np.any(active_mask): active_mask = np.ones_like(mu, dtype=bool) - f_active = np.where(active_mask, f, np.inf) - v = int(np.argmin(f_active)) + gradient_active = np.where(active_mask, gradient, np.inf) + v = int(np.argmin(gradient_active)) if s == v: positive_mask = mu > 0.0 positive_mask[s] = False if np.any(positive_mask): - v = int(np.argmin(np.where(positive_mask, f, np.inf))) + v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(f) - np.dot(mu, f)) + fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break @@ -1115,24 +1204,27 @@ def _slsqp_objective_and_gradient( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - if regularization == 0.0 and condition_number_limit is None: - # Keep the unregularized objective path bitwise identical. - return -float(np.dot(mu, f)), -f - - # The stabilized dual is g_r(mu) = sum_i mu_i c_i - - # b(mu)^T A_used(mu)^(-1) b(mu), whose gradient is f for the - # effective matrix used in this evaluation. - g_regularized = _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) - A_mu = np.einsum("k,kij->ij", mu, matrices) - shift_gradient = _conditioning_shift_gradient( + gradient = _dual_gradient( mu, matrices, - A_mu, + Ax, + centers, + offsets, + xstar, + f, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return -g_regularized, -f - shift_gradient * float(np.dot(xstar, xstar)) + if regularization == 0.0 and condition_number_limit is None: + # Keep the unregularized objective path bitwise identical. + return -float(np.dot(mu, f)), -gradient + + # The stabilized dual is g_r(mu) = sum_i mu_i c_i - + # b(mu)^T A_used(mu)^(-1) b(mu). Its gradient includes the derivative + # of any conditioning shift that depends on A(mu). + g_regularized = _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + return -g_regularized, -gradient def _run_scipy_slsqp( @@ -1316,8 +1408,9 @@ def solve_minimax( circumcenter for an unadjusted solve (``regularization == 0`` and ``condition_number_limit is None``), and the stabilised problem otherwise; in the pairwise case the exact value is - ``ellphi.tangency(p, q).t ** 2``. For ``k = 1`` the result is the - trivial ``alpha = delta_0`` at the center. + ``ellphi.tangency(p, q).t ** 2``. For ``k = 1`` the result uses the + same conditioned evaluation as the non-singleton paths and keeps + the trivial converged, zero-iteration semantics. Raises: ValueError: For an unknown method, an empty simplex or invalid @@ -1351,7 +1444,7 @@ def solve_minimax( _validate_tolerance("weight_tol", weight_tol) _validate_positive_int("max_iter", max_iter) _validate_positive_int("newton_max_iter", newton_max_iter) - _validate_positive_int("max_conditioning_steps", max_conditioning_steps) + _validate_non_negative_int("max_conditioning_steps", max_conditioning_steps) if condition_number_limit is not None and ( not np.isfinite(condition_number_limit) or condition_number_limit <= 1.0 ): @@ -1368,11 +1461,24 @@ def solve_minimax( if not np.all(np.isfinite(offsets)): raise ValueError("offsets must be finite") + # Precompute A_i x_bar_i (shape: k x d) + Ax = np.einsum("kij,kj->ki", matrices, centers) + # --- Trivial case: single point --- if k == 1: + xstar, f = _eval_f( + np.array([1.0]), + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) return MinimaxResult( - alpha=0.0 if offsets is None else float(offsets[0]), - circumcenter=centers[0].copy(), + alpha=float(f[0]), + circumcenter=xstar, weights=np.array([1.0]), active_set=[0], converged=True, @@ -1380,9 +1486,6 @@ def solve_minimax( method=method, ) - # Precompute A_i x_bar_i (shape: k x d) - Ax = np.einsum("kij,kj->ki", matrices, centers) - # Uniform initialisation for FW-based methods mu_init = np.full(k, 1.0 / k) diff --git a/tests/test_minimax.py b/tests/test_minimax.py index d240138..52791ce 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -75,6 +75,18 @@ def test_single_point_offset(self): ) assert res.alpha == 0.75 + def test_single_point_uses_stabilized_matrix(self): + res = solve_minimax( + np.eye(2)[np.newaxis], + np.array([[1.0, 0.0]]), + regularization=1.0, + ) + + assert res.alpha == pytest.approx(0.25) + np.testing.assert_allclose(res.circumcenter, [0.5, 0.0]) + assert res.converged + assert res.n_iter == 0 + def test_single_point_nan_offset_raises(self): with pytest.raises(ValueError, match="offsets must be finite"): solve_minimax( @@ -365,6 +377,13 @@ def test_stability_control_parameter_validation(self): solve_minimax(A, centers, condition_number_limit=1.0) with pytest.raises(ValueError): solve_minimax(A, centers, max_conditioning_steps=-1) + result = solve_minimax( + A, + centers, + condition_number_limit=2.0, + max_conditioning_steps=0, + ) + assert np.isfinite(result.alpha) with pytest.raises(ValueError, match="offsets shape"): solve_minimax(A, centers, offsets=np.zeros(3)) @@ -497,6 +516,41 @@ def test_conditioning_slsqp_objective_gradient_matches(self): np.testing.assert_allclose(finite_difference, gradient, rtol=1e-6, atol=1e-8) assert np.isfinite(objective) + def test_fw_gap_uses_conditioning_shift_gradient(self): + matrices = np.array([[[1.0]], [[2.0]]]) + centers = np.array([[1e8], [2e8]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + mu = np.array([0.5, 0.5]) + kwargs = { + "regularization": 0.0, + "condition_number_limit": 1e6, + "max_conditioning_steps": 0, + } + + _, unadjusted_f = minimax_mod._eval_f(mu, matrices, Ax, centers, None, **kwargs) + offsets = np.array([0.0, unadjusted_f[0] - unadjusted_f[1]]) + xstar, f = minimax_mod._eval_f(mu, matrices, Ax, centers, offsets, **kwargs) + gradient = minimax_mod._dual_gradient( + mu, matrices, Ax, centers, offsets, xstar, f, **kwargs + ) + raw_gap = float(np.max(f) - np.dot(mu, f)) + stabilized_gap = float(np.max(gradient) - np.dot(mu, gradient)) + + assert raw_gap < 1.0 + assert stabilized_gap > 1.0 + for method in ("fw+bisect", "fw+brentq"): + result = solve_minimax( + matrices, + centers, + offsets=offsets, + method=method, + tol=stabilized_gap / 2.0, + max_iter=1, + **kwargs, + ) + assert result.n_iter == 1 + assert not result.converged + def test_newton_polishing_uses_stabilized_stationarity(self): matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) centers = np.array([[0.0, 0.0], [1.0, 0.0]]) From ce78b372dc87dde62ba47c1b280c7fdc8e9d10f9 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Sun, 4 Oct 2026 23:28:24 +0900 Subject: [PATCH 11/29] fix: global gap recheck after Newton, re-evaluate exhausted FW, stabilised Newton residuals Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 121 ++++++++++++++++++++++++++++++++-- tests/test_minimax.py | 93 +++++++++++++++++++++++++- 2 files changed, 204 insertions(+), 10 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 1725349..2e5ebc9 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -690,6 +690,31 @@ def _run_fw_bisect( mu = np.clip(mu, 0.0, None) mu /= mu.sum() + if not converged: + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + converged = float(np.max(gradient) - np.dot(mu, gradient)) < tol + return mu, converged, n_iter @@ -782,6 +807,31 @@ def _run_fw_brentq( mu = np.clip(mu, 0.0, None) mu /= mu.sum() + if not converged: + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + converged = float(np.max(gradient) - np.dot(mu, gradient)) < tol + metadata = { "fw_iters": n_iter, "n_fevals": total_fevals + total_line_search_evals, @@ -897,8 +947,27 @@ def _newton_polish( if offsets is not None: f = f + offsets[active_set] - # Residual: r_l = f_{i_l} - f_{i_{m-1}} - r = f[:-1] - f[-1] # (m-1,) + if regularization == 0.0 and condition_number_limit is None: + # Keep the unregularized residual path bitwise identical. + r = f[:-1] - f[-1] + else: + diff_all = xstar[np.newaxis, :] - centers + f_all = np.einsum("ki,kij,kj->k", diff_all, matrices, diff_all) + if offsets is not None: + f_all = f_all + offsets + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f_all, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + r = gradient[active_set[:-1]] - gradient[active_set[-1]] if float(np.max(np.abs(r))) < tol: newton_status = "converged" break @@ -1037,8 +1106,27 @@ def _damped_newton_polish( if offsets is not None: f = f + offsets[active_set] - # Residual - r = f[:-1] - f[-1] + if regularization == 0.0 and condition_number_limit is None: + # Keep the unregularized residual path bitwise identical. + r = f[:-1] - f[-1] + else: + diff_all = xstar[np.newaxis, :] - centers + f_all = np.einsum("ki,kij,kj->k", diff_all, matrices, diff_all) + if offsets is not None: + f_all = f_all + offsets + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f_all, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + r = gradient[active_set[:-1]] - gradient[active_set[-1]] try: _ensure_finite(float(np.max(np.abs(r))), "Newton residual") except RuntimeError: @@ -1297,6 +1385,7 @@ def _check_newton_convergence( newton_tol: float, newton_status: str, *, + tol: float, regularization: float = 0.0, condition_number_limit: float | None = None, max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, @@ -1312,7 +1401,7 @@ def _check_newton_convergence( "nonfinite_step", "projection_failed", } - if not converged or newton_status in failure_statuses: + if newton_status in failure_statuses: return False try: A_mu = np.einsum("k,kij->ij", mu, matrices) @@ -1329,10 +1418,24 @@ def _check_newton_convergence( f_check = np.einsum("ki,kij,kj->k", d_check, matrices, d_check) if offsets is not None: f_check = f_check + offsets + gradient_check = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar_check, + f_check, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fw_gap = float(np.max(gradient_check) - np.dot(mu, gradient_check)) + if not np.isfinite(fw_gap) or fw_gap >= tol: + return False if len(active_set) <= 1: return True - f_active = f_check[active_set] - r_check = f_active[:-1] - f_active[-1] + r_check = gradient_check[active_set[:-1]] - gradient_check[active_set[-1]] return float(np.max(np.abs(r_check))) < newton_tol * 1e4 except linalg.LinAlgError: return False @@ -1544,6 +1647,7 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1582,6 +1686,7 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1620,6 +1725,7 @@ def solve_minimax( converged, newton_tol, meta_newton["newton_status"], + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1657,6 +1763,7 @@ def solve_minimax( True, newton_tol, meta_newton["newton_status"], + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 52791ce..145e47b 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -403,7 +403,7 @@ def test_weight_tol_cannot_empty_the_fw_face(self, k, weight_tol): with pytest.raises(ValueError, match="weight_tol must satisfy"): solve_minimax(A, centers, weight_tol=threshold) - def test_fw_empty_face_fallback_does_not_false_converge(self): + def test_fw_empty_face_rechecks_gap_after_last_update(self): A = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) centers = np.array([[0.0, 0.0], [2.0, 0.0]]) offsets = np.array([1.0, 0.0]) @@ -423,7 +423,7 @@ def test_fw_empty_face_fallback_does_not_false_converge(self): ) assert n_iter == 1 - assert not converged + assert converged assert np.all(np.isfinite(mu)) def test_regularized_slsqp_objective_gradient_matches(self): @@ -544,7 +544,7 @@ def test_fw_gap_uses_conditioning_shift_gradient(self): centers, offsets=offsets, method=method, - tol=stabilized_gap / 2.0, + tol=stabilized_gap / 100.0, max_iter=1, **kwargs, ) @@ -582,6 +582,45 @@ def test_newton_polishing_uses_stabilized_stationarity(self): assert unadjusted.alpha == pytest.approx(stabilized.alpha, abs=1e-12) assert not np.array_equal(stabilized.weights, unadjusted.weights) + def test_newton_polishing_uses_conditioning_shift_gradient(self): + matrices = np.array([[[1.0]], [[2.0]]]) + centers = np.array([[1e8], [2e8]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + stability = { + "regularization": 0.0, + "condition_number_limit": 1e6, + "max_conditioning_steps": 0, + } + _, unadjusted_values = minimax_mod._eval_f( + np.array([0.5, 0.5]), + matrices, + Ax, + centers, + None, + **stability, + ) + offsets = np.array([0.0, unadjusted_values[0] - unadjusted_values[1]]) + mu, _, metadata = minimax_mod._damped_newton_polish( + np.array([0.5, 0.5]), + [0, 1], + matrices, + Ax, + centers, + offsets, + max_iter=2, + tol=1.0, + **stability, + ) + xstar, values = minimax_mod._eval_f( + mu, matrices, Ax, centers, offsets, **stability + ) + gradient = minimax_mod._dual_gradient( + mu, matrices, Ax, centers, offsets, xstar, values, **stability + ) + + assert metadata["newton_status"] == "converged" + assert abs(float(gradient[0] - gradient[1])) <= 1.0 + def test_fw_gap_ignores_subthreshold_positive_weights(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) @@ -605,6 +644,54 @@ def test_fw_gap_ignores_subthreshold_positive_weights(self): assert n_iter == 1 assert not converged + def test_newton_rechecks_global_gap_beyond_weight_face(self): + matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) + centers = np.array( + [ + [3.7476304, -3.7246354], + [0.8495570, -1.0704745], + [0.1480270, -3.5617054], + ] + ) + + result = solve_minimax( + matrices, + centers, + method="fw+bisect+newton", + weight_tol=0.2, + tol=1e-3, + ) + + assert result.weights[2] > 0.0 + assert result.weights[2] < 0.2 + assert result.active_set == [0, 1] + assert result.converged is False + + def test_hybrid_rechecks_fw_optimum_hit_on_last_iteration(self): + matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + reference = solve_minimax( + matrices, + centers, + method="fw+bisect", + tol=1e-12, + max_iter=2, + ) + assert reference.converged + last_update = reference.n_iter - 1 + + result = solve_minimax( + matrices, + centers, + method="fw+bisect+newton", + tol=1e-12, + max_iter=last_update, + ) + + assert result.converged + assert result.alpha == reference.alpha + np.testing.assert_array_equal(result.weights, reference.weights) + def test_slsqp_converges_with_regularization(self): matrices = np.array( [ From c1bb4f64dd179cccfeb994503e2bb589bcae67e2 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 00:08:39 +0900 Subject: [PATCH 12/29] fix: require a positive Newton tolerance Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 2 +- src/ellphi/cech.py | 2 +- tests/test_cech.py | 10 ++++++++++ tests/test_minimax_methods.py | 6 ++++++ 4 files changed, 18 insertions(+), 2 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 2e5ebc9..0e212ff 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -1542,7 +1542,7 @@ def solve_minimax( k, d = centers.shape _validate_tolerance("tol", tol, strictly_positive=True) - _validate_tolerance("newton_tol", newton_tol) + _validate_tolerance("newton_tol", newton_tol, strictly_positive=True) _validate_tolerance("regularization", regularization) _validate_tolerance("weight_tol", weight_tol) _validate_positive_int("max_iter", max_iter) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index ab07608..d2519eb 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -133,7 +133,7 @@ def _validate_solver_parameters( ) -> None: """Validate public solver controls before dispatching to the engine.""" _validate_tolerance("tol", tol, strictly_positive=True) - _validate_tolerance("newton_tol", newton_tol) + _validate_tolerance("newton_tol", newton_tol, strictly_positive=True) _validate_tolerance("weight_tol", weight_tol) _validate_positive_int("max_iter", max_iter) _validate_positive_int("newton_max_iter", newton_max_iter) diff --git a/tests/test_cech.py b/tests/test_cech.py index f988c0c..faef51f 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -463,6 +463,16 @@ def test_public_tol_must_be_finite_and_positive(value): ellphi.cech(coefs, tol=value) +@pytest.mark.parametrize("value", [np.nan, 0.0]) +def test_public_newton_tol_must_be_finite_and_positive(value): + coefs = coef_from_cov( + np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) + ) + + with pytest.raises(ValueError, match="newton_tol must be finite and > 0"): + ellphi.cech(coefs, newton_tol=value) + + def test_public_namedtuple_field_order(): assert ellphi.CechResult._fields == ( "t", diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index a853ef0..365e4f8 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -165,6 +165,12 @@ def test_default_method_is_fw_bisect(self): res = solve_minimax(matrices, centers) assert res.method == "fw+bisect" + @pytest.mark.parametrize("newton_tol", [np.nan, 0.0]) + def test_non_positive_or_non_finite_newton_tol_raises(self, newton_tol): + matrices, centers = _random_simplex(2, 2) + with pytest.raises(ValueError, match="newton_tol must be finite and > 0"): + solve_minimax(matrices, centers, newton_tol=newton_tol) + # --------------------------------------------------------------------------- # Numerical agreement across methods From a340bd689224ff53a227f379f9ffd9b6c80b6410 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 00:21:25 +0900 Subject: [PATCH 13/29] docs: state the quasi-Newton approximation under mu-dependent conditioning Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 20 ++++++++++++++++++-- tests/test_minimax.py | 10 ++++++++-- 2 files changed, 26 insertions(+), 4 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 0e212ff..ca2a5f5 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -34,6 +34,10 @@ * For stabilization, the SLSQP and damped-Newton objectives are the regularized dual rather than ``dot(mu, f)``; this keeps their objective and Jacobian consistent with the conditioned matrix. +* Under ``condition_number_limit``, the Newton Hessian omits the derivative + of the mu-dependent epsilon-floor shift, so the Newton step uses an + approximate Hessian. The residual test uses the exact stabilised gradient; + this can increase the step count without changing the accepted result. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. @@ -876,12 +880,18 @@ def _newton_polish( ) -> tuple[np.ndarray, int, dict]: """Newton polishing on the dual restricted to the current active face. - Solves the KKT conditions r_l = f_{i_l}(x*) - f_{i_{m-1}}(x*) = 0 - using the exact (negative) Hessian of g via the reduced system: + Solves the KKT conditions using the stabilised gradient via the reduced + system: neg_H_r delta = r neg_H_r[l, l'] = neg_H[l,l'] - neg_H[l, m-1] - neg_H[m-1, l'] + neg_H[m-1, m-1] + When ``condition_number_limit`` is set, the epsilon-floor shift depends on + ``mu`` through ``||A(mu)||_2``. The Hessian above omits the derivative of + that shift, so this is a quasi-Newton step with an approximate Hessian; + the residual test still uses the exact stabilised gradient. The omitted + terms can increase the step count without changing the accepted result. + Then mu_{i_l} += delta[l], mu_{i_{m-1}} -= sum(delta), followed by simplex projection. @@ -1039,6 +1049,12 @@ def _damped_newton_polish( - Armijo backtracking line search on the Newton step - ``_ensure_finite`` guards against NaN propagation + Under ``condition_number_limit``, the epsilon-floor shift depends on + ``mu`` through ``||A(mu)||_2``. The Newton Hessian omits its derivative, + making this a quasi-Newton step with an approximate Hessian; the residual + test uses the exact stabilised gradient. The omitted terms may increase + the step count without changing the accepted result. + Returns: (mu, n_iter, metadata) """ diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 145e47b..1722105 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -583,9 +583,15 @@ def test_newton_polishing_uses_stabilized_stationarity(self): assert not np.array_equal(stabilized.weights, unadjusted.weights) def test_newton_polishing_uses_conditioning_shift_gradient(self): + """The quasi-Newton polish meets the exact stabilised residual test. + + The mu-dependent conditioning shift is omitted from the Hessian, but + the residual uses the exact stabilised gradient. + """ matrices = np.array([[[1.0]], [[2.0]]]) centers = np.array([[1e8], [2e8]]) Ax = np.einsum("kij,kj->ki", matrices, centers) + newton_tol = 1.0 stability = { "regularization": 0.0, "condition_number_limit": 1e6, @@ -608,7 +614,7 @@ def test_newton_polishing_uses_conditioning_shift_gradient(self): centers, offsets, max_iter=2, - tol=1.0, + tol=newton_tol, **stability, ) xstar, values = minimax_mod._eval_f( @@ -619,7 +625,7 @@ def test_newton_polishing_uses_conditioning_shift_gradient(self): ) assert metadata["newton_status"] == "converged" - assert abs(float(gradient[0] - gradient[1])) <= 1.0 + assert abs(float(gradient[0] - gradient[1])) < newton_tol def test_fw_gap_ignores_subthreshold_positive_weights(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) From a8736e308f3fb9bdf05404ef499d25ba5ab92187 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 11:28:36 +0900 Subject: [PATCH 14/29] fix: make many-body minimax convergence robust Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 11 + src/ellphi/_minimax_python.py | 381 ++++++++++++++++++++++++++------- src/ellphi/_minimax_python.pyi | 7 +- src/ellphi/cech.py | 12 +- src/ellphi/cech.pyi | 13 +- tests/test_cech.py | 16 +- tests/test_minimax.py | 74 +++++-- tests/test_minimax_methods.py | 40 ++-- 8 files changed, 430 insertions(+), 124 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index 1fe6f7a..2bf2255 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -42,6 +42,17 @@ strict complementarity (ND1), they coincide. For three unit balls centred at two indices, and `active_set` has three. A solver that does not converge or produces non-finite output raises `RuntimeError` with its diagnostics. +The default solver uses the away-step Frank-Wolfe (AFW) method of +Lacoste-Julien and Jaggi (2015) on the dual simplex with an adaptive Brent +line search. At each iteration it compares the ordinary FW direction with an +away direction from the least useful positive-weight vertex; a capped away +step removes that vertex exactly. AFW can still require more than the default +iteration budget before identifying a minimal face on rank-deficient +many-body problems. An exhausted AFW phase therefore starts SLSQP from its +current weights. Newton-bearing method variants subsequently polish the +thresholded fallback face. Every accepted result is checked against the +all-index stabilised FW gap. + The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index ca2a5f5..7b2482e 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -40,6 +40,15 @@ this can increase the step count without changing the accepted result. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. +* The Frank-Wolfe runners use the away-step Frank-Wolfe method of + Lacoste-Julien and Jaggi (2015) over the simplex, with exact drop steps, + instead of ellcech's plain Frank-Wolfe updates. This removes non-optimal + vertices from the active face and avoids the sublinear + support-identification bottleneck of the original method. +* An exhausted away-step run falls back to SLSQP, starting from the AFW + iterate. Hybrid methods then polish the fallback's thresholded face. This + makes the default ``fw+brentq`` path robust when AFW has not identified the + optimal face within its iteration budget. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of @@ -445,9 +454,8 @@ def _regularized_dual_value( def _exact_line_search( - s: int, - v: int, mu: np.ndarray, + direction: np.ndarray, matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, @@ -458,18 +466,16 @@ def _exact_line_search( condition_number_limit: float | None, max_conditioning_steps: int, ) -> float: - """Find gamma* in [0, gamma_max] that maximises g along the pairwise direction. + """Find gamma* in [0, gamma_max] that maximises g along ``direction``. Bisects on the stabilized dual directional derivative - ``h(gamma) = grad_s - grad_v``. + ``h(gamma) = dot(gradient(mu + gamma * direction), direction)``. """ if gamma_max <= 0.0: return 0.0 def h(gamma: float) -> float: - mu_g = mu.copy() - mu_g[s] += gamma - mu_g[v] -= gamma + mu_g = mu + gamma * direction x_g, f_g = _eval_f( mu_g, matrices, @@ -492,7 +498,7 @@ def h(gamma: float) -> float: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(gradient_g[s] - gradient_g[v]) + return float(np.dot(gradient_g, direction)) h0 = h(0.0) if h0 <= 0.0: @@ -520,9 +526,8 @@ def _ensure_finite(value: float, label: str) -> float: def _brentq_line_search( - s: int, - v: int, mu: np.ndarray, + direction: np.ndarray, matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, @@ -545,9 +550,7 @@ def _brentq_line_search( def h(gamma: float) -> float: n_fevals[0] += 1 - mu_g = mu.copy() - mu_g[s] += gamma - mu_g[v] -= gamma + mu_g = mu + gamma * direction x_g, f_g = _eval_f( mu_g, matrices, @@ -570,7 +573,7 @@ def h(gamma: float) -> float: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(gradient_g[s] - gradient_g[v]) + return float(np.dot(gradient_g, direction)) h0 = h(0.0) if h0 <= 0.0: @@ -609,6 +612,44 @@ def h(gamma: float) -> float: # --------------------------------------------------------------------------- +def _afw_direction( + mu: np.ndarray, gradient: np.ndarray +) -> tuple[np.ndarray, float, int | None]: + """Return the away-step Frank-Wolfe direction and feasible step bound.""" + s = int(np.argmax(gradient)) + mean_gradient = float(np.dot(mu, gradient)) + fw_gap = float(gradient[s] - mean_gradient) + + positive = mu > 0.0 + a = int(np.argmin(np.where(positive, gradient, np.inf))) + away_gap = float(mean_gradient - gradient[a]) + if away_gap > fw_gap: + direction = mu.copy() + direction[a] -= 1.0 + gamma_max = float(mu[a] / (1.0 - mu[a])) + return direction, gamma_max, a + + direction = -mu.copy() + direction[s] += 1.0 + return direction, 1.0, None + + +def _take_afw_step( + mu: np.ndarray, + direction: np.ndarray, + gamma: float, + gamma_max: float, + away_index: int | None, +) -> np.ndarray: + """Apply an AFW step, preserving an exact zero on an away drop step.""" + updated = mu + gamma * direction + if away_index is not None and gamma == gamma_max: + updated[away_index] = 0.0 + updated = np.clip(updated, 0.0, None) + updated /= updated.sum() + return updated + + def _run_fw_bisect( matrices: np.ndarray, Ax: np.ndarray, @@ -623,7 +664,7 @@ def _run_fw_bisect( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int]: - """Pairwise Frank-Wolfe with exact bisection line search. + """Away-step Frank-Wolfe with exact bisection line search. Returns: (mu, converged, n_iter) @@ -656,28 +697,15 @@ def _run_fw_bisect( max_conditioning_steps=max_conditioning_steps, ) - s = int(np.argmax(gradient)) - active_mask = mu > weight_tol - if not np.any(active_mask): - active_mask = np.ones_like(mu, dtype=bool) - gradient_active = np.where(active_mask, gradient, np.inf) - v = int(np.argmin(gradient_active)) - if s == v: - positive_mask = mu > 0.0 - positive_mask[s] = False - if np.any(positive_mask): - v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break - gamma_max = float(mu[v]) + direction, gamma_max, away_index = _afw_direction(mu, gradient) gamma = _exact_line_search( - s, - v, mu, + direction, matrices, Ax, centers, @@ -688,11 +716,7 @@ def _run_fw_bisect( max_conditioning_steps=max_conditioning_steps, ) - mu = mu.copy() - mu[s] += gamma - mu[v] -= gamma - mu = np.clip(mu, 0.0, None) - mu /= mu.sum() + mu = _take_afw_step(mu, direction, gamma, gamma_max, away_index) if not converged: xstar, f = _eval_f( @@ -736,7 +760,7 @@ def _run_fw_brentq( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int, dict]: - """Pairwise Frank-Wolfe with brentq line search. + """Away-step Frank-Wolfe with brentq line search. Returns: (mu, converged, n_iter, metadata) @@ -772,28 +796,15 @@ def _run_fw_brentq( max_conditioning_steps=max_conditioning_steps, ) - s = int(np.argmax(gradient)) - active_mask = mu > weight_tol - if not np.any(active_mask): - active_mask = np.ones_like(mu, dtype=bool) - gradient_active = np.where(active_mask, gradient, np.inf) - v = int(np.argmin(gradient_active)) - if s == v: - positive_mask = mu > 0.0 - positive_mask[s] = False - if np.any(positive_mask): - v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break - gamma_max = float(mu[v]) + direction, gamma_max, away_index = _afw_direction(mu, gradient) gamma, ls_evals = _brentq_line_search( - s, - v, mu, + direction, matrices, Ax, centers, @@ -805,11 +816,7 @@ def _run_fw_brentq( ) total_line_search_evals += ls_evals - mu = mu.copy() - mu[s] += gamma - mu[v] -= gamma - mu = np.clip(mu, 0.0, None) - mu /= mu.sum() + mu = _take_afw_step(mu, direction, gamma, gamma_max, away_index) if not converged: xstar, f = _eval_f( @@ -1338,6 +1345,7 @@ def _run_scipy_slsqp( offsets: np.ndarray | None, k: int, *, + initial_weights: np.ndarray | None = None, regularization: float, condition_number_limit: float | None, max_conditioning_steps: int, @@ -1364,7 +1372,11 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: max_conditioning_steps=max_conditioning_steps, ) - x0 = np.full(k, 1.0 / k) + x0 = ( + np.full(k, 1.0 / k) + if initial_weights is None + else np.asarray(initial_weights, dtype=float).copy() + ) bounds = [(0.0, None)] * k res = minimize( @@ -1385,6 +1397,73 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: return mu, bool(res.success), n_eval[0] +def _run_slsqp_fallback( + mu: np.ndarray, + matrices: np.ndarray, + Ax: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray | None, + *, + tol: float, + regularization: float, + condition_number_limit: float | None, + max_conditioning_steps: int, +) -> tuple[np.ndarray, bool, int, int]: + """Run SLSQP from an exhausted AFW iterate and enforce the global gap.""" + fallback_mu, slsqp_converged, n_eval = _run_scipy_slsqp( + matrices, + Ax, + centers, + offsets, + len(mu), + initial_weights=mu, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + xstar, f = _eval_f( + fallback_mu, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient = _dual_gradient( + fallback_mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fw_gap = float(np.max(gradient) - np.dot(fallback_mu, gradient)) + converged = slsqp_converged and np.isfinite(fw_gap) and fw_gap < tol + if converged: + return fallback_mu, True, n_eval, 0 + + fallback_mu, converged, n_refine = _run_fw_bisect( + matrices, + Ax, + centers, + offsets, + fallback_mu, + tol=tol, + max_iter=_DEFAULT_MAX_ITER, + weight_tol=0.0, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + return fallback_mu, converged, n_eval, n_refine + + # --------------------------------------------------------------------------- # Public API # --------------------------------------------------------------------------- @@ -1462,7 +1541,7 @@ def solve_minimax( centers: np.ndarray, *, offsets: np.ndarray | None = None, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = _DEFAULT_TOL, max_iter: int = _DEFAULT_MAX_ITER, weight_tol: float = _DEFAULT_WEIGHT_TOL, @@ -1485,8 +1564,8 @@ def solve_minimax( Seven solver back-ends are available via ``method``: - * ``"fw+bisect"`` (default): Pairwise FW with 52-step bisection line search. - * ``"fw+brentq"``: Pairwise FW with adaptive brentq line search. + * ``"fw+bisect"``: Away-step FW with 52-step bisection line search. + * ``"fw+brentq"`` (default): Away-step FW with adaptive brentq line search. * ``"fw+bisect+newton"``: FW(bisect) warm-start + Newton polishing. * ``"fw+brentq+newton"``: FW(brentq) warm-start + damped Newton polishing. * ``"fw+bisect+damped-newton"``: FW(bisect) + Armijo-damped Newton. @@ -1496,6 +1575,11 @@ def solve_minimax( The legacy name ``"fw+newton"`` is accepted as an alias for ``"fw+bisect+newton"`` with a deprecation warning. + If an AFW phase exhausts ``max_iter``, it falls back to SLSQP from the + current weights. Newton hybrids polish the fallback's thresholded face. + The all-index stabilised FW gap is rechecked before fallback convergence + is accepted. + Args: matrices: SPD matrices ``A_i``, shape ``(k, d, d)``, or ``(d, d)`` for a single vertex. @@ -1625,17 +1709,73 @@ def solve_minimax( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata["fw_iters"] = n_iter + if not converged: + mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + n_iter += n_eval + n_refine + metadata["fallback_method"] = "scipy-slsqp" + metadata["fallback_n_fevals"] = n_eval + metadata["fallback_refinement_fw_iters"] = n_refine + metadata["fallback_converged"] = converged elif method == "fw+brentq": mu, converged, n_iter, meta_fw = _run_fw_brentq( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata.update(meta_fw) + if not converged: + mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + n_iter += n_eval + n_refine + metadata["fallback_method"] = "scipy-slsqp" + metadata["fallback_n_fevals"] = n_eval + metadata["fallback_refinement_fw_iters"] = n_refine + metadata["fallback_converged"] = converged elif method == "fw+bisect+newton": mu, converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) + fallback_meta: dict[str, Any] = {} + if not converged: + mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fallback_meta = { + "fallback_method": "scipy-slsqp", + "fallback_n_fevals": n_eval, + "fallback_refinement_fw_iters": n_refine, + "fallback_converged": converged, + } + else: + n_eval = 0 + n_refine = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _newton_polish( mu, @@ -1651,7 +1791,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_iter_newton + n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1669,12 +1809,35 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw + metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "fw+brentq+newton": mu, converged, n_iter_fw, meta_fw = _run_fw_brentq( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) + fallback_meta = {} + if not converged: + mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fallback_meta = { + "fallback_method": "scipy-slsqp", + "fallback_n_fevals": n_eval, + "fallback_refinement_fw_iters": n_refine, + "fallback_converged": converged, + } + else: + n_eval = 0 + n_refine = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1690,7 +1853,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_iter_newton + n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1708,12 +1871,35 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata.update(meta_fw) + metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "fw+bisect+damped-newton": mu, converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) + fallback_meta = {} + if not converged: + mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fallback_meta = { + "fallback_method": "scipy-slsqp", + "fallback_n_fevals": n_eval, + "fallback_refinement_fw_iters": n_refine, + "fallback_converged": converged, + } + else: + n_eval = 0 + n_refine = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1729,7 +1915,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_iter_newton + n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1747,12 +1933,13 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw + metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "newton-cold": # Newton from uniform start (no FW warm-up) active_set_cold = list(range(k)) - mu, n_iter_newton, meta_newton = _damped_newton_polish( + mu, n_iter_cold, meta_cold = _damped_newton_polish( mu_init.copy(), active_set_cold, matrices, @@ -1767,7 +1954,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_newton + n_iter = n_iter_cold active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1778,7 +1965,7 @@ def solve_minimax( offsets, True, newton_tol, - meta_newton["newton_status"], + meta_cold["newton_status"], tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, @@ -1788,13 +1975,63 @@ def solve_minimax( mu, fallback_converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) - converged = fallback_converged n_iter += n_iter_fw - meta_newton["fallback_method"] = "fw+bisect" - meta_newton["fallback_fw_iters"] = n_iter_fw - meta_newton["fallback_converged"] = fallback_converged - meta_newton["newton_status"] = "fw_fallback" - metadata.update(meta_newton) + metadata.update({f"cold_{key}": value for key, value in meta_cold.items()}) + metadata["fallback_method"] = "fw+bisect" + metadata["fallback_fw_iters"] = n_iter_fw + if not fallback_converged: + mu, fallback_converged, n_eval, n_refine = _run_slsqp_fallback( + mu, + matrices, + Ax, + centers, + offsets, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + n_iter += n_eval + n_refine + metadata["secondary_fallback_method"] = "scipy-slsqp" + metadata["fallback_n_fevals"] = n_eval + metadata["fallback_refinement_fw_iters"] = n_refine + + active_set_fallback = [i for i in range(k) if mu[i] > weight_tol] + mu, n_iter_newton, meta_newton = _damped_newton_polish( + mu, + active_set_fallback, + matrices, + Ax, + centers, + offsets, + weight_tol=weight_tol, + max_iter=newton_max_iter, + tol=newton_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + n_iter += n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] + converged = _check_newton_convergence( + mu, + active_set_newton, + matrices, + Ax, + centers, + offsets, + fallback_converged, + newton_tol, + meta_newton["newton_status"], + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + metadata["fallback_converged"] = fallback_converged + metadata.update(meta_newton) + else: + metadata.update(meta_cold) elif method == "scipy-slsqp": mu, converged, n_iter = _run_scipy_slsqp( diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index 39c3641..3a39973 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -34,7 +34,7 @@ def solve_minimax( centers: np.ndarray, *, offsets: np.ndarray | None = None, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = 1e-09, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -43,7 +43,10 @@ def solve_minimax( max_conditioning_steps: int = 8, newton_tol: float = 1e-14, newton_max_iter: int = 20, -) -> MinimaxResult: ... +) -> MinimaxResult: + """Solve the dual with AFW and an SLSQP fallback for exhausted AFW paths.""" + ... + def solve_minimax_from_coefs( coefs: np.ndarray, **kwargs: Any, diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index d2519eb..f4b6fe5 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -229,7 +229,7 @@ def _centered_constraint_values( def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -247,7 +247,9 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. + method: Internal many-body solver method. The default uses adaptive + away-step Frank-Wolfe with an SLSQP fallback if that phase + exhausts its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. @@ -356,7 +358,7 @@ def cech( def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -393,7 +395,9 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. + method: Internal many-body solver method. The default uses adaptive + away-step Frank-Wolfe with an SLSQP fallback if that phase + exhausts its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 9696f08..29da88f 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -29,22 +29,27 @@ class CechGrad(NamedTuple): def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, newton_tol: float = 1e-14, newton_max_iter: int = 20, -) -> CechResult: ... +) -> CechResult: + """Compute the Čech time with the robust AFW/SLSQP default.""" + ... + def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+bisect", + method: MethodName | str = "fw+brentq", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, active_tol: float = 1e-9, newton_tol: float = 1e-14, newton_max_iter: int = 20, -) -> CechGrad: ... +) -> CechGrad: + """Compute the Čech time and gradient with the robust default solver.""" + ... diff --git a/tests/test_cech.py b/tests/test_cech.py index faef51f..3b656dc 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -325,8 +325,12 @@ def test_singleton_and_empty_cech_input(): ellphi.cech(np.empty((0, coefs.shape[1]))) -def test_non_convergence_raises_with_diagnostics(): +def test_non_convergence_raises_with_diagnostics(monkeypatch): coefs = _random_coefs(5, 3, seed=101) + monkeypatch.setattr( + "ellphi._minimax_python._run_slsqp_fallback", + lambda mu, *args, **kwargs: (mu, False, 0, 0), + ) with pytest.raises(RuntimeError) as exc_info: ellphi.cech(coefs, method="fw+bisect", max_iter=1, tol=1e-15) @@ -433,12 +437,10 @@ def test_public_surrogate_methods(method): constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) coefs = pack_conic(matrices, linear, constants) - if method == "scipy-slsqp": - result = ellphi.cech(coefs, method=method) - assert result.t == pytest.approx(np.sqrt(0.9024444260258915), abs=1e-8) - else: - with pytest.raises(RuntimeError): - ellphi.cech(coefs, method=method) + result = ellphi.cech(coefs, method=method) + + assert result.t**2 == pytest.approx(0.9024444260258915, rel=1e-8) + assert result.support == (1, 3, 5) @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 1722105..84885b7 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -96,6 +96,26 @@ def test_single_point_nan_offset_raises(self): ) +@pytest.mark.parametrize("method", ["fw+bisect", "fw+brentq"]) +def test_afw_drops_spurious_interior_weight_exactly(method): + matrices = np.repeat(np.eye(2)[np.newaxis], 4, axis=0) + centers = np.array( + [ + [1.0, 0.0], + [-0.5, np.sqrt(3.0) / 2.0], + [-0.5, -np.sqrt(3.0) / 2.0], + [0.0, 0.0], + ] + ) + + result = solve_minimax(matrices, centers, method=method, tol=1e-12, max_iter=10) + + assert result.converged + assert result.weights[3] == 0.0 + np.testing.assert_allclose(result.weights[:3], 1.0 / 3.0, atol=1e-15) + assert result.active_set == [0, 1, 2] + + # --------------------------------------------------------------------------- # Isotropic (A_i = I) special cases # --------------------------------------------------------------------------- @@ -539,17 +559,25 @@ def test_fw_gap_uses_conditioning_shift_gradient(self): assert raw_gap < 1.0 assert stabilized_gap > 1.0 for method in ("fw+bisect", "fw+brentq"): - result = solve_minimax( + runner = ( + minimax_mod._run_fw_bisect + if method == "fw+bisect" + else minimax_mod._run_fw_brentq + ) + runner_result = runner( matrices, + Ax, centers, - offsets=offsets, - method=method, + offsets, + mu.copy(), tol=stabilized_gap / 100.0, max_iter=1, + weight_tol=1e-10, **kwargs, ) - assert result.n_iter == 1 - assert not result.converged + _, converged, n_iter = runner_result[:3] + assert n_iter == 1 + assert not converged def test_newton_polishing_uses_stabilized_stationarity(self): matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) @@ -627,13 +655,13 @@ def test_newton_polishing_uses_conditioning_shift_gradient(self): assert metadata["newton_status"] == "converged" assert abs(float(gradient[0] - gradient[1])) < newton_tol - def test_fw_gap_ignores_subthreshold_positive_weights(self): + def test_afw_keeps_subthreshold_positive_weights_in_away_set(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) Ax = np.einsum("kij,kj->ki", matrices, centers) mu = np.array([0.405, 0.405, 0.19]) - _, converged, n_iter = minimax_mod._run_fw_bisect( + updated, converged, n_iter = minimax_mod._run_fw_bisect( matrices, Ax, centers, @@ -648,30 +676,32 @@ def test_fw_gap_ignores_subthreshold_positive_weights(self): ) assert n_iter == 1 - assert not converged + assert converged + assert updated[2] == 0.0 def test_newton_rechecks_global_gap_beyond_weight_face(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) - centers = np.array( - [ - [3.7476304, -3.7246354], - [0.8495570, -1.0704745], - [0.1480270, -3.5617054], - ] - ) + centers = np.array([[-1.0, 0.0], [1.0, 0.0], [0.0, 3.0]]) + weights = np.array([0.5, 0.5, 0.0]) + Ax = np.einsum("kij,kj->ki", matrices, centers) - result = solve_minimax( + converged = minimax_mod._check_newton_convergence( + weights, + [0, 1], matrices, + Ax, centers, - method="fw+bisect+newton", - weight_tol=0.2, + None, + True, + 1e-14, + "converged", tol=1e-3, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, ) - assert result.weights[2] > 0.0 - assert result.weights[2] < 0.2 - assert result.active_set == [0, 1] - assert result.converged is False + assert converged is False def test_hybrid_rechecks_fw_optimum_hit_on_last_iteration(self): matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index 365e4f8..c68412d 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -96,22 +96,36 @@ def test_slsqp_reference_value_and_gap(self, public_surrogate_results): assert gap <= 1e-8 assert residual <= 1e-8 + @pytest.mark.parametrize("method", CANONICAL_METHODS) + def test_all_methods_converge_accurately(self, method, public_surrogate_results): + matrices, centers, results = public_surrogate_results + result = results[method] + gap, residual = _surrogate_diagnostics(result, matrices, centers) + + assert result.converged + assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 + assert gap <= 1e-8 + assert residual <= 1e-8 + assert result.active_set == [1, 3, 5] + @pytest.mark.parametrize( - "method", [method for method in CANONICAL_METHODS if method != "scipy-slsqp"] + "method", + [ + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "newton-cold", + ], ) - def test_other_methods_are_accurate_or_report_failure( + def test_newton_hybrids_polish_the_minimal_face( self, method, public_surrogate_results ): - matrices, centers, results = public_surrogate_results + _, _, results = public_surrogate_results result = results[method] - gap, residual = _surrogate_diagnostics(result, matrices, centers) - if result.converged: - assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 - assert gap <= 1e-8 - assert residual <= 1e-8 - else: - assert result.converged is False + assert result.metadata is not None + assert result.metadata["newton_status"] == "converged" + assert len(result.active_set) <= 3 def test_newton_failures_do_not_collapse_to_a_vertex( self, public_surrogate_results @@ -160,10 +174,10 @@ def test_k0_raises(self, method): with pytest.raises(ValueError, match="k=0"): solve_minimax(np.zeros((0, 2, 2)), np.zeros((0, 2)), method=method) - def test_default_method_is_fw_bisect(self): + def test_default_method_is_fw_brentq(self): matrices, centers = _random_simplex(2, 2) res = solve_minimax(matrices, centers) - assert res.method == "fw+bisect" + assert res.method == "fw+brentq" @pytest.mark.parametrize("newton_tol", [np.nan, 0.0]) def test_non_positive_or_non_finite_newton_tol_raises(self, newton_tol): @@ -306,7 +320,7 @@ def test_converged_fw_fallback_is_reported(self): assert result.converged assert result.metadata is not None - assert result.metadata["newton_status"] == "fw_fallback" + assert result.metadata["newton_status"] == "converged" assert result.metadata["fallback_converged"] is True From 920566de66df2e47685a2dfcda2ef5f3b75bbb92 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 11:35:31 +0900 Subject: [PATCH 15/29] fix: preserve the caller FW iteration budget Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 7 ++- src/ellphi/_minimax_python.py | 102 +++++++++++++++++++++++---------- src/ellphi/_minimax_python.pyi | 2 +- src/ellphi/cech.py | 4 +- src/ellphi/cech.pyi | 2 +- tests/test_minimax_methods.py | 19 ++++++ 6 files changed, 98 insertions(+), 38 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index 2bf2255..ccaf3e8 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -49,9 +49,10 @@ away direction from the least useful positive-weight vertex; a capped away step removes that vertex exactly. AFW can still require more than the default iteration budget before identifying a minimal face on rank-deficient many-body problems. An exhausted AFW phase therefore starts SLSQP from its -current weights. Newton-bearing method variants subsequently polish the -thresholded fallback face. Every accepted result is checked against the -all-index stabilised FW gap. +current weights. If SLSQP still misses the requested gap, Newton polishes the +thresholded face without consuming additional FW iterations. Newton-bearing +method variants subsequently apply their requested polish. Every accepted +result is checked against the all-index stabilised FW gap. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 7b2482e..e8ad4d4 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -46,9 +46,11 @@ vertices from the active face and avoids the sublinear support-identification bottleneck of the original method. * An exhausted away-step run falls back to SLSQP, starting from the AFW - iterate. Hybrid methods then polish the fallback's thresholded face. This - makes the default ``fw+brentq`` path robust when AFW has not identified the - optimal face within its iteration budget. + iterate. If SLSQP still misses the all-index gap, Newton polishes its + thresholded face without spending additional FW iterations. Hybrid methods + also apply their requested Newton polish. This makes the default + ``fw+brentq`` path robust when AFW has not identified the optimal face within + its iteration budget. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of @@ -1405,6 +1407,8 @@ def _run_slsqp_fallback( offsets: np.ndarray | None, *, tol: float, + weight_tol: float, + newton_max_iter: int, regularization: float, condition_number_limit: float | None, max_conditioning_steps: int, @@ -1448,20 +1452,38 @@ def _run_slsqp_fallback( if converged: return fallback_mu, True, n_eval, 0 - fallback_mu, converged, n_refine = _run_fw_bisect( + active_set = [i for i in range(len(fallback_mu)) if fallback_mu[i] > weight_tol] + fallback_mu, n_polish, meta_newton = _newton_polish( + fallback_mu, + active_set, matrices, Ax, centers, offsets, + weight_tol=weight_tol, + max_iter=newton_max_iter, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + active_set = [i for i in range(len(fallback_mu)) if fallback_mu[i] > weight_tol] + converged = _check_newton_convergence( fallback_mu, + active_set, + matrices, + Ax, + centers, + offsets, + slsqp_converged, + tol, + meta_newton["newton_status"], tol=tol, - max_iter=_DEFAULT_MAX_ITER, - weight_tol=0.0, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return fallback_mu, converged, n_eval, n_refine + return fallback_mu, converged, n_eval, n_polish # --------------------------------------------------------------------------- @@ -1576,9 +1598,10 @@ def solve_minimax( ``"fw+bisect+newton"`` with a deprecation warning. If an AFW phase exhausts ``max_iter``, it falls back to SLSQP from the - current weights. Newton hybrids polish the fallback's thresholded face. - The all-index stabilised FW gap is rechecked before fallback convergence - is accepted. + current weights. If needed, Newton polishes the fallback's thresholded + face without spending additional FW iterations; Newton hybrids then apply + their requested polish. The all-index stabilised FW gap is rechecked + before fallback convergence is accepted. Args: matrices: SPD matrices ``A_i``, shape ``(k, d, d)``, or ``(d, d)`` for @@ -1710,21 +1733,23 @@ def solve_minimax( ) metadata["fw_iters"] = n_iter if not converged: - mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter += n_eval + n_refine + n_iter += n_eval + n_fallback_newton metadata["fallback_method"] = "scipy-slsqp" metadata["fallback_n_fevals"] = n_eval - metadata["fallback_refinement_fw_iters"] = n_refine + metadata["fallback_newton_iters"] = n_fallback_newton metadata["fallback_converged"] = converged elif method == "fw+brentq": @@ -1733,21 +1758,23 @@ def solve_minimax( ) metadata.update(meta_fw) if not converged: - mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter += n_eval + n_refine + n_iter += n_eval + n_fallback_newton metadata["fallback_method"] = "scipy-slsqp" metadata["fallback_n_fevals"] = n_eval - metadata["fallback_refinement_fw_iters"] = n_refine + metadata["fallback_newton_iters"] = n_fallback_newton metadata["fallback_converged"] = converged elif method == "fw+bisect+newton": @@ -1756,13 +1783,15 @@ def solve_minimax( ) fallback_meta: dict[str, Any] = {} if not converged: - mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1770,12 +1799,12 @@ def solve_minimax( fallback_meta = { "fallback_method": "scipy-slsqp", "fallback_n_fevals": n_eval, - "fallback_refinement_fw_iters": n_refine, + "fallback_newton_iters": n_fallback_newton, "fallback_converged": converged, } else: n_eval = 0 - n_refine = 0 + n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _newton_polish( mu, @@ -1791,7 +1820,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton + n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1818,13 +1847,15 @@ def solve_minimax( ) fallback_meta = {} if not converged: - mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1832,12 +1863,12 @@ def solve_minimax( fallback_meta = { "fallback_method": "scipy-slsqp", "fallback_n_fevals": n_eval, - "fallback_refinement_fw_iters": n_refine, + "fallback_newton_iters": n_fallback_newton, "fallback_converged": converged, } else: n_eval = 0 - n_refine = 0 + n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1853,7 +1884,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton + n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1880,13 +1911,15 @@ def solve_minimax( ) fallback_meta = {} if not converged: - mu, converged, n_eval, n_refine = _run_slsqp_fallback( + mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1894,12 +1927,12 @@ def solve_minimax( fallback_meta = { "fallback_method": "scipy-slsqp", "fallback_n_fevals": n_eval, - "fallback_refinement_fw_iters": n_refine, + "fallback_newton_iters": n_fallback_newton, "fallback_converged": converged, } else: n_eval = 0 - n_refine = 0 + n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1915,7 +1948,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_refine + n_iter_newton + n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1980,21 +2013,28 @@ def solve_minimax( metadata["fallback_method"] = "fw+bisect" metadata["fallback_fw_iters"] = n_iter_fw if not fallback_converged: - mu, fallback_converged, n_eval, n_refine = _run_slsqp_fallback( + ( + mu, + fallback_converged, + n_eval, + n_fallback_newton, + ) = _run_slsqp_fallback( mu, matrices, Ax, centers, offsets, tol=tol, + weight_tol=weight_tol, + newton_max_iter=newton_max_iter, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter += n_eval + n_refine + n_iter += n_eval + n_fallback_newton metadata["secondary_fallback_method"] = "scipy-slsqp" metadata["fallback_n_fevals"] = n_eval - metadata["fallback_refinement_fw_iters"] = n_refine + metadata["fallback_newton_iters"] = n_fallback_newton active_set_fallback = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index 3a39973..e271a89 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -44,7 +44,7 @@ def solve_minimax( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> MinimaxResult: - """Solve the dual with AFW and an SLSQP fallback for exhausted AFW paths.""" + """Solve the dual with AFW and a robust SLSQP/Newton fallback.""" ... def solve_minimax_from_coefs( diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index f4b6fe5..27135b5 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -248,7 +248,7 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default uses adaptive - away-step Frank-Wolfe with an SLSQP fallback if that phase + away-step Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. @@ -396,7 +396,7 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default uses adaptive - away-step Frank-Wolfe with an SLSQP fallback if that phase + away-step Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 29da88f..7a0648c 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -37,7 +37,7 @@ def cech( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: - """Compute the Čech time with the robust AFW/SLSQP default.""" + """Compute the Čech time with the robust AFW/SLSQP/Newton default.""" ... def cech_grad( diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index c68412d..cc423fd 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -255,6 +255,25 @@ def test_metadata_has_line_search_evals(self): assert "line_search_evals" in res.metadata assert res.metadata["line_search_evals"] > 0 + def test_fallback_respects_fw_iteration_budget(self, monkeypatch): + matrices, centers = minimax_public_surrogate() + + def unexpected_bisect(*args, **kwargs): + raise AssertionError("fallback must not start another FW run") + + monkeypatch.setattr("ellphi._minimax_python._run_fw_bisect", unexpected_bisect) + result = solve_minimax( + matrices, + centers, + method="fw+brentq", + tol=1e-15, + max_iter=1, + ) + + assert result.metadata is not None + assert result.metadata["fw_iters"] == 1 + assert "fallback_newton_iters" in result.metadata + # --------------------------------------------------------------------------- # fw+brentq+newton specific From d46001281f1ee8dc8db158edb46dde6c0083f15f Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 11:44:36 +0900 Subject: [PATCH 16/29] fix: enforce dual gap for direct SLSQP Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 67 +++++++++++++++++++++++++++++++++-- tests/test_minimax_methods.py | 16 +++++++++ 2 files changed, 81 insertions(+), 2 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index e8ad4d4..2eeff11 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -1348,6 +1348,7 @@ def _run_scipy_slsqp( k: int, *, initial_weights: np.ndarray | None = None, + tol: float, regularization: float, condition_number_limit: float | None, max_conditioning_steps: int, @@ -1396,7 +1397,31 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: if s > 0.0: mu /= s - return mu, bool(res.success), n_eval[0] + xstar, f = _eval_f( + mu, + matrices, + Ax, + centers, + offsets, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + gradient = _dual_gradient( + mu, + matrices, + Ax, + centers, + offsets, + xstar, + f, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) + converged = bool(res.success) and np.isfinite(fw_gap) and fw_gap < tol + return mu, converged, n_eval[0] def _run_slsqp_fallback( @@ -1421,6 +1446,7 @@ def _run_slsqp_fallback( offsets, len(mu), initial_weights=mu, + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, @@ -1591,7 +1617,8 @@ def solve_minimax( * ``"fw+bisect+newton"``: FW(bisect) warm-start + Newton polishing. * ``"fw+brentq+newton"``: FW(brentq) warm-start + damped Newton polishing. * ``"fw+bisect+damped-newton"``: FW(bisect) + Armijo-damped Newton. - * ``"scipy-slsqp"``: Direct SLSQP solve via scipy. + * ``"scipy-slsqp"``: Direct SLSQP solve via scipy, with Newton accuracy + polishing if SLSQP's result misses the requested global gap. * ``"newton-cold"``: Newton from uniform mu=1/k (stability baseline). The legacy name ``"fw+newton"`` is accepted as an alias for @@ -2080,11 +2107,47 @@ def solve_minimax( centers, offsets, k, + tol=tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) metadata["n_fevals"] = n_iter + if not converged: + active_set_slsqp = [i for i in range(k) if mu[i] > weight_tol] + mu, n_iter_newton, meta_newton = _newton_polish( + mu, + active_set_slsqp, + matrices, + Ax, + centers, + offsets, + weight_tol=weight_tol, + max_iter=newton_max_iter, + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + n_iter += n_iter_newton + active_set_newton = [i for i in range(k) if mu[i] > weight_tol] + converged = _check_newton_convergence( + mu, + active_set_newton, + matrices, + Ax, + centers, + offsets, + converged, + tol, + meta_newton["newton_status"], + tol=tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + ) + metadata["accuracy_polish"] = "newton" + metadata.update(meta_newton) # --- Final evaluation --- xstar, f = _eval_f( diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index cc423fd..e0c53c6 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -446,6 +446,22 @@ def test_fw_newton_alias_warns(self): class TestScipySlsqp: + def test_success_flag_does_not_override_requested_gap(self): + matrices = np.array([1e-16 * np.eye(2), 4e-16 * np.eye(2)]) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + + result = solve_minimax( + matrices, + centers, + method="scipy-slsqp", + tol=1e-20, + ) + + assert result.converged + assert result.alpha == pytest.approx(4.4444444444444444e-17, rel=1e-6) + assert result.metadata is not None + assert result.metadata["accuracy_polish"] == "newton" + @pytest.mark.parametrize("k", [2, 3, 5]) def test_alpha_agrees_with_reference(self, k): matrices, centers = _random_simplex(k, 3, seed=k * 7) From 8917630f4214e573ff208392f54e9f4b85c1aac9 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 11:52:26 +0900 Subject: [PATCH 17/29] fix: preserve active set after scale clipping Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/cech.py | 2 +- tests/test_cech.py | 11 +++++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 27135b5..0c01804 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -341,7 +341,7 @@ def cech( t_squared = float(max(alpha, 0.0)) t = float(np.sqrt(max(0.0, t_squared))) support = tuple(int(i) for i in np.flatnonzero(result.weights > weight_tol)) - active_threshold = active_tol * max(1.0, t_squared) + active_threshold = active_tol * max(1.0, t_squared) + negative_tolerance active_set = tuple( int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) ) diff --git a/tests/test_cech.py b/tests/test_cech.py index 3b656dc..fb44efc 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -134,6 +134,17 @@ def test_translated_singleton_roundoff_negative_scale_is_clipped(): assert abs(result.t) <= np.sqrt(value_roundoff) +def test_clipped_negative_scale_preserves_singleton_active_set(): + coefs = coef_from_cov(np.array([[1e6, 0.0]]), np.eye(2)[None]) + coefs[0, -1] = np.nextafter(1e12, -np.inf) + + result = ellphi.cech(coefs) + + assert result.t == 0.0 + assert result.support == (0,) + assert result.active_set == (0,) + + def test_translated_coincident_roundoff_negative_scale_is_clipped(): center = np.array([[1e6, -1e6]]) covariance = np.array([[1.0, 0.2], [0.2, 1.7]]) From 6a764780299b57467b06a79f94af896ab5ed9d63 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 12:45:40 +0900 Subject: [PATCH 18/29] fix: restore plain Frank-Wolfe steps, keep the SLSQP fallback Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 20 +++-- src/ellphi/_minimax_python.py | 129 ++++++++++++++++----------------- src/ellphi/_minimax_python.pyi | 2 +- src/ellphi/cech.py | 12 +-- src/ellphi/cech.pyi | 2 +- tests/factories.py | 6 ++ tests/test_minimax.py | 29 +------- tests/test_minimax_methods.py | 25 ++++++- 8 files changed, 114 insertions(+), 111 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index ccaf3e8..96960e4 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -42,17 +42,15 @@ strict complementarity (ND1), they coincide. For three unit balls centred at two indices, and `active_set` has three. A solver that does not converge or produces non-finite output raises `RuntimeError` with its diagnostics. -The default solver uses the away-step Frank-Wolfe (AFW) method of -Lacoste-Julien and Jaggi (2015) on the dual simplex with an adaptive Brent -line search. At each iteration it compares the ordinary FW direction with an -away direction from the least useful positive-weight vertex; a capped away -step removes that vertex exactly. AFW can still require more than the default -iteration budget before identifying a minimal face on rank-deficient -many-body problems. An exhausted AFW phase therefore starts SLSQP from its -current weights. If SLSQP still misses the requested gap, Newton polishes the -thresholded face without consuming additional FW iterations. Newton-bearing -method variants subsequently apply their requested polish. Every accepted -result is checked against the all-index stabilised FW gap. +The default solver uses plain Frank-Wolfe on the dual simplex with an adaptive +Brent line search. On the bundled surrogate, a zero-weight constraint is +nearly tight, so the all-index gap can stall while weight leaks onto that +vertex; the rank-deficient face is better handled by the primal fallback. An +exhausted FW phase therefore starts SLSQP from its current weights. If SLSQP +still misses the requested gap, Newton polishes the thresholded face without +consuming additional FW iterations. Newton-bearing method variants +subsequently apply their requested polish. Every accepted result is checked +against the all-index stabilised FW gap. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 2eeff11..1d72b46 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -40,17 +40,12 @@ this can increase the step count without changing the accepted result. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. -* The Frank-Wolfe runners use the away-step Frank-Wolfe method of - Lacoste-Julien and Jaggi (2015) over the simplex, with exact drop steps, - instead of ellcech's plain Frank-Wolfe updates. This removes non-optimal - vertices from the active face and avoids the sublinear - support-identification bottleneck of the original method. -* An exhausted away-step run falls back to SLSQP, starting from the AFW +* An exhausted Frank-Wolfe run falls back to SLSQP, starting from the FW iterate. If SLSQP still misses the all-index gap, Newton polishes its thresholded face without spending additional FW iterations. Hybrid methods also apply their requested Newton polish. This makes the default - ``fw+brentq`` path robust when AFW has not identified the optimal face within - its iteration budget. + ``fw+brentq`` path robust when plain FW has not identified the optimal face + within its iteration budget. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of @@ -456,8 +451,9 @@ def _regularized_dual_value( def _exact_line_search( + s: int, + v: int, mu: np.ndarray, - direction: np.ndarray, matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, @@ -468,16 +464,18 @@ def _exact_line_search( condition_number_limit: float | None, max_conditioning_steps: int, ) -> float: - """Find gamma* in [0, gamma_max] that maximises g along ``direction``. + """Find gamma* in [0, gamma_max] that maximises g along the pairwise direction. Bisects on the stabilized dual directional derivative - ``h(gamma) = dot(gradient(mu + gamma * direction), direction)``. + ``h(gamma) = grad_s - grad_v``. """ if gamma_max <= 0.0: return 0.0 def h(gamma: float) -> float: - mu_g = mu + gamma * direction + mu_g = mu.copy() + mu_g[s] += gamma + mu_g[v] -= gamma x_g, f_g = _eval_f( mu_g, matrices, @@ -500,7 +498,7 @@ def h(gamma: float) -> float: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(np.dot(gradient_g, direction)) + return float(gradient_g[s] - gradient_g[v]) h0 = h(0.0) if h0 <= 0.0: @@ -528,8 +526,9 @@ def _ensure_finite(value: float, label: str) -> float: def _brentq_line_search( + s: int, + v: int, mu: np.ndarray, - direction: np.ndarray, matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, @@ -552,7 +551,9 @@ def _brentq_line_search( def h(gamma: float) -> float: n_fevals[0] += 1 - mu_g = mu + gamma * direction + mu_g = mu.copy() + mu_g[s] += gamma + mu_g[v] -= gamma x_g, f_g = _eval_f( mu_g, matrices, @@ -575,7 +576,7 @@ def h(gamma: float) -> float: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - return float(np.dot(gradient_g, direction)) + return float(gradient_g[s] - gradient_g[v]) h0 = h(0.0) if h0 <= 0.0: @@ -614,44 +615,6 @@ def h(gamma: float) -> float: # --------------------------------------------------------------------------- -def _afw_direction( - mu: np.ndarray, gradient: np.ndarray -) -> tuple[np.ndarray, float, int | None]: - """Return the away-step Frank-Wolfe direction and feasible step bound.""" - s = int(np.argmax(gradient)) - mean_gradient = float(np.dot(mu, gradient)) - fw_gap = float(gradient[s] - mean_gradient) - - positive = mu > 0.0 - a = int(np.argmin(np.where(positive, gradient, np.inf))) - away_gap = float(mean_gradient - gradient[a]) - if away_gap > fw_gap: - direction = mu.copy() - direction[a] -= 1.0 - gamma_max = float(mu[a] / (1.0 - mu[a])) - return direction, gamma_max, a - - direction = -mu.copy() - direction[s] += 1.0 - return direction, 1.0, None - - -def _take_afw_step( - mu: np.ndarray, - direction: np.ndarray, - gamma: float, - gamma_max: float, - away_index: int | None, -) -> np.ndarray: - """Apply an AFW step, preserving an exact zero on an away drop step.""" - updated = mu + gamma * direction - if away_index is not None and gamma == gamma_max: - updated[away_index] = 0.0 - updated = np.clip(updated, 0.0, None) - updated /= updated.sum() - return updated - - def _run_fw_bisect( matrices: np.ndarray, Ax: np.ndarray, @@ -666,7 +629,7 @@ def _run_fw_bisect( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int]: - """Away-step Frank-Wolfe with exact bisection line search. + """Plain Frank-Wolfe with exact bisection line search. Returns: (mu, converged, n_iter) @@ -699,15 +662,28 @@ def _run_fw_bisect( max_conditioning_steps=max_conditioning_steps, ) + s = int(np.argmax(gradient)) + active_mask = mu > weight_tol + if not np.any(active_mask): + active_mask = np.ones_like(mu, dtype=bool) + gradient_active = np.where(active_mask, gradient, np.inf) + v = int(np.argmin(gradient_active)) + if s == v: + positive_mask = mu > 0.0 + positive_mask[s] = False + if np.any(positive_mask): + v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) + fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break - direction, gamma_max, away_index = _afw_direction(mu, gradient) + gamma_max = float(mu[v]) gamma = _exact_line_search( + s, + v, mu, - direction, matrices, Ax, centers, @@ -718,7 +694,11 @@ def _run_fw_bisect( max_conditioning_steps=max_conditioning_steps, ) - mu = _take_afw_step(mu, direction, gamma, gamma_max, away_index) + mu = mu.copy() + mu[s] += gamma + mu[v] -= gamma + mu = np.clip(mu, 0.0, None) + mu /= mu.sum() if not converged: xstar, f = _eval_f( @@ -762,7 +742,7 @@ def _run_fw_brentq( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int, dict]: - """Away-step Frank-Wolfe with brentq line search. + """Plain Frank-Wolfe with brentq line search. Returns: (mu, converged, n_iter, metadata) @@ -798,15 +778,28 @@ def _run_fw_brentq( max_conditioning_steps=max_conditioning_steps, ) + s = int(np.argmax(gradient)) + active_mask = mu > weight_tol + if not np.any(active_mask): + active_mask = np.ones_like(mu, dtype=bool) + gradient_active = np.where(active_mask, gradient, np.inf) + v = int(np.argmin(gradient_active)) + if s == v: + positive_mask = mu > 0.0 + positive_mask[s] = False + if np.any(positive_mask): + v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) + fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) if fw_gap < tol: converged = True break - direction, gamma_max, away_index = _afw_direction(mu, gradient) + gamma_max = float(mu[v]) gamma, ls_evals = _brentq_line_search( + s, + v, mu, - direction, matrices, Ax, centers, @@ -818,7 +811,11 @@ def _run_fw_brentq( ) total_line_search_evals += ls_evals - mu = _take_afw_step(mu, direction, gamma, gamma_max, away_index) + mu = mu.copy() + mu[s] += gamma + mu[v] -= gamma + mu = np.clip(mu, 0.0, None) + mu /= mu.sum() if not converged: xstar, f = _eval_f( @@ -1438,7 +1435,7 @@ def _run_slsqp_fallback( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int, int]: - """Run SLSQP from an exhausted AFW iterate and enforce the global gap.""" + """Run SLSQP from an exhausted FW iterate and enforce the global gap.""" fallback_mu, slsqp_converged, n_eval = _run_scipy_slsqp( matrices, Ax, @@ -1612,8 +1609,8 @@ def solve_minimax( Seven solver back-ends are available via ``method``: - * ``"fw+bisect"``: Away-step FW with 52-step bisection line search. - * ``"fw+brentq"`` (default): Away-step FW with adaptive brentq line search. + * ``"fw+bisect"``: Plain FW with 52-step bisection line search. + * ``"fw+brentq"`` (default): Plain FW with adaptive brentq line search. * ``"fw+bisect+newton"``: FW(bisect) warm-start + Newton polishing. * ``"fw+brentq+newton"``: FW(brentq) warm-start + damped Newton polishing. * ``"fw+bisect+damped-newton"``: FW(bisect) + Armijo-damped Newton. @@ -1624,7 +1621,7 @@ def solve_minimax( The legacy name ``"fw+newton"`` is accepted as an alias for ``"fw+bisect+newton"`` with a deprecation warning. - If an AFW phase exhausts ``max_iter``, it falls back to SLSQP from the + If a FW phase exhausts ``max_iter``, it falls back to SLSQP from the current weights. If needed, Newton polishes the fallback's thresholded face without spending additional FW iterations; Newton hybrids then apply their requested polish. The all-index stabilised FW gap is rechecked diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index e271a89..0c2b5c8 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -44,7 +44,7 @@ def solve_minimax( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> MinimaxResult: - """Solve the dual with AFW and a robust SLSQP/Newton fallback.""" + """Solve the dual with plain FW and a robust SLSQP/Newton fallback.""" ... def solve_minimax_from_coefs( diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 0c01804..7402965 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -247,9 +247,9 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default uses adaptive - away-step Frank-Wolfe with an SLSQP/Newton fallback if that phase - exhausts its budget. + method: Internal many-body solver method. The default uses plain + Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts + its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. @@ -395,9 +395,9 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default uses adaptive - away-step Frank-Wolfe with an SLSQP/Newton fallback if that phase - exhausts its budget. + method: Internal many-body solver method. The default uses plain + Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts + its budget. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 7a0648c..e8799e0 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -37,7 +37,7 @@ def cech( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: - """Compute the Čech time with the robust AFW/SLSQP/Newton default.""" + """Compute the Čech time with the robust FW/SLSQP/Newton default.""" ... def cech_grad( diff --git a/tests/factories.py b/tests/factories.py index 379eada..63e1718 100644 --- a/tests/factories.py +++ b/tests/factories.py @@ -82,6 +82,12 @@ def minimax_public_surrogate() -> tuple[np.ndarray, np.ndarray]: ``centers = rng.standard_normal((6, 2))``. The returned literals are the matrices and centers from instance 12; this explicit matrix-first, row-major traversal is part of the fixture definition. + + At the optimum, constraint ``f_4`` is nearly tight even though ``mu_4`` is + zero, placing the instance near a failure of strict complementarity. The + all-index Frank-Wolfe gap must become much smaller than that slack, so + plain FW can stall while weight leaks onto vertex 4. Newton polishing on + the resulting face is rank-deficient, whereas primal SLSQP is unaffected. """ matrices = np.array( [ diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 84885b7..b954eaa 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -96,26 +96,6 @@ def test_single_point_nan_offset_raises(self): ) -@pytest.mark.parametrize("method", ["fw+bisect", "fw+brentq"]) -def test_afw_drops_spurious_interior_weight_exactly(method): - matrices = np.repeat(np.eye(2)[np.newaxis], 4, axis=0) - centers = np.array( - [ - [1.0, 0.0], - [-0.5, np.sqrt(3.0) / 2.0], - [-0.5, -np.sqrt(3.0) / 2.0], - [0.0, 0.0], - ] - ) - - result = solve_minimax(matrices, centers, method=method, tol=1e-12, max_iter=10) - - assert result.converged - assert result.weights[3] == 0.0 - np.testing.assert_allclose(result.weights[:3], 1.0 / 3.0, atol=1e-15) - assert result.active_set == [0, 1, 2] - - # --------------------------------------------------------------------------- # Isotropic (A_i = I) special cases # --------------------------------------------------------------------------- @@ -655,13 +635,13 @@ def test_newton_polishing_uses_conditioning_shift_gradient(self): assert metadata["newton_status"] == "converged" assert abs(float(gradient[0] - gradient[1])) < newton_tol - def test_afw_keeps_subthreshold_positive_weights_in_away_set(self): + def test_fw_gap_includes_subthreshold_positive_weights(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) Ax = np.einsum("kij,kj->ki", matrices, centers) mu = np.array([0.405, 0.405, 0.19]) - updated, converged, n_iter = minimax_mod._run_fw_bisect( + _, converged, n_iter = minimax_mod._run_fw_bisect( matrices, Ax, centers, @@ -676,8 +656,7 @@ def test_afw_keeps_subthreshold_positive_weights_in_away_set(self): ) assert n_iter == 1 - assert converged - assert updated[2] == 0.0 + assert not converged def test_newton_rechecks_global_gap_beyond_weight_face(self): matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) @@ -726,7 +705,7 @@ def test_hybrid_rechecks_fw_optimum_hit_on_last_iteration(self): assert result.converged assert result.alpha == reference.alpha - np.testing.assert_array_equal(result.weights, reference.weights) + np.testing.assert_allclose(result.weights, reference.weights, atol=1e-15) def test_slsqp_converges_with_regularization(self): matrices = np.array( diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index e0c53c6..07c3376 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -96,6 +96,30 @@ def test_slsqp_reference_value_and_gap(self, public_surrogate_results): assert gap <= 1e-8 assert residual <= 1e-8 + def test_plain_fw_converges_with_large_budget(self): + matrices, centers = minimax_public_surrogate() + result = solve_minimax( + matrices, + centers, + method="fw+brentq", + max_iter=20000, + ) + + assert result.converged + assert result.n_iter > 2000 + assert result.metadata is not None + assert "fallback_method" not in result.metadata + assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 + + def test_default_uses_slsqp_fallback(self): + matrices, centers = minimax_public_surrogate() + result = solve_minimax(matrices, centers) + + assert result.converged + assert result.method == "fw+brentq" + assert result.metadata is not None + assert result.metadata["fallback_method"] == "scipy-slsqp" + @pytest.mark.parametrize("method", CANONICAL_METHODS) def test_all_methods_converge_accurately(self, method, public_surrogate_results): matrices, centers, results = public_surrogate_results @@ -339,7 +363,6 @@ def test_converged_fw_fallback_is_reported(self): assert result.converged assert result.metadata is not None - assert result.metadata["newton_status"] == "converged" assert result.metadata["fallback_converged"] is True From 13b88e1b182328aa5a64636eaead48367437d774 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 13:03:16 +0900 Subject: [PATCH 19/29] fix: remove automatic solver fallbacks; non-convergence raises Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 19 +-- src/ellphi/_minimax_python.py | 292 +-------------------------------- src/ellphi/_minimax_python.pyi | 2 +- src/ellphi/cech.py | 37 ++--- src/ellphi/cech.pyi | 4 +- tests/test_cech.py | 67 +++++--- tests/test_minimax.py | 2 +- tests/test_minimax_methods.py | 77 +-------- 8 files changed, 88 insertions(+), 412 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index 96960e4..dd5c821 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -40,17 +40,16 @@ Up to numerical tolerance, `support` is a subset of `active_set`; under strict complementarity (ND1), they coincide. For three unit balls centred at `(0, 0)`, `(2, 0)`, and `(0, 2)`, the point is `(1, 1)`, support has two indices, and `active_set` has three. A solver that does not converge or -produces non-finite output raises `RuntimeError` with its diagnostics. +produces non-finite output raises `RuntimeError` naming its method, iterations, +final duality gap, and `tol`. -The default solver uses plain Frank-Wolfe on the dual simplex with an adaptive -Brent line search. On the bundled surrogate, a zero-weight constraint is -nearly tight, so the all-index gap can stall while weight leaks onto that -vertex; the rank-deficient face is better handled by the primal fallback. An -exhausted FW phase therefore starts SLSQP from its current weights. If SLSQP -still misses the requested gap, Newton polishes the thresholded face without -consuming additional FW iterations. Newton-bearing method variants -subsequently apply their requested polish. Every accepted result is checked -against the all-index stabilised FW gap. +The default solver is `fw+brentq`, plain Frank-Wolfe on the dual simplex with +an adaptive Brent line search. On the bundled surrogate, a zero-weight +constraint is nearly tight, so the all-index gap can stall while weight leaks +onto that vertex; this is recorded in the test factory because it explains +why plain FW may not converge within the default budget. A non-converged +public solve raises `RuntimeError` with the method, iterations, final duality +gap, and `tol`; callers may choose a larger `max_iter` or a different `method`. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 1d72b46..da3d7a1 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -18,8 +18,7 @@ beyond the configured limit, with status ``"ill_conditioned_hessian"``. Damped Newton uses diagonal regularization at that threshold instead. * ``newton-cold`` starts at the uniform weights. If Newton does not converge, - it falls back to a freshly run ``fw+bisect`` iterate from that same uniform - start and reports the fallback's convergence status. + it reports the Newton status without running a second method. * Newton failure statuses force ``converged=False``; these statuses are ``"empty_face"``, ``"armijo_rejected"``, ``"factorization_failed"``, ``"ill_conditioned_hessian"``, ``"linear_solve_failed"``, @@ -40,13 +39,6 @@ this can increase the step count without changing the accepted result. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. -* An exhausted Frank-Wolfe run falls back to SLSQP, starting from the FW - iterate. If SLSQP still misses the all-index gap, Newton polishes its - thresholded face without spending additional FW iterations. Hybrid methods - also apply their requested Newton polish. This makes the default - ``fw+brentq`` path robust when plain FW has not identified the optimal face - within its iteration budget. - The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of ``unpack_conic`` and type annotations) or documentation. Distributed as part @@ -1421,94 +1413,6 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: return mu, converged, n_eval[0] -def _run_slsqp_fallback( - mu: np.ndarray, - matrices: np.ndarray, - Ax: np.ndarray, - centers: np.ndarray, - offsets: np.ndarray | None, - *, - tol: float, - weight_tol: float, - newton_max_iter: int, - regularization: float, - condition_number_limit: float | None, - max_conditioning_steps: int, -) -> tuple[np.ndarray, bool, int, int]: - """Run SLSQP from an exhausted FW iterate and enforce the global gap.""" - fallback_mu, slsqp_converged, n_eval = _run_scipy_slsqp( - matrices, - Ax, - centers, - offsets, - len(mu), - initial_weights=mu, - tol=tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - xstar, f = _eval_f( - fallback_mu, - matrices, - Ax, - centers, - offsets, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - gradient = _dual_gradient( - fallback_mu, - matrices, - Ax, - centers, - offsets, - xstar, - f, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - fw_gap = float(np.max(gradient) - np.dot(fallback_mu, gradient)) - converged = slsqp_converged and np.isfinite(fw_gap) and fw_gap < tol - if converged: - return fallback_mu, True, n_eval, 0 - - active_set = [i for i in range(len(fallback_mu)) if fallback_mu[i] > weight_tol] - fallback_mu, n_polish, meta_newton = _newton_polish( - fallback_mu, - active_set, - matrices, - Ax, - centers, - offsets, - weight_tol=weight_tol, - max_iter=newton_max_iter, - tol=tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - active_set = [i for i in range(len(fallback_mu)) if fallback_mu[i] > weight_tol] - converged = _check_newton_convergence( - fallback_mu, - active_set, - matrices, - Ax, - centers, - offsets, - slsqp_converged, - tol, - meta_newton["newton_status"], - tol=tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - return fallback_mu, converged, n_eval, n_polish - - # --------------------------------------------------------------------------- # Public API # --------------------------------------------------------------------------- @@ -1621,12 +1525,6 @@ def solve_minimax( The legacy name ``"fw+newton"`` is accepted as an alias for ``"fw+bisect+newton"`` with a deprecation warning. - If a FW phase exhausts ``max_iter``, it falls back to SLSQP from the - current weights. If needed, Newton polishes the fallback's thresholded - face without spending additional FW iterations; Newton hybrids then apply - their requested polish. The all-index stabilised FW gap is rechecked - before fallback convergence is accepted. - Args: matrices: SPD matrices ``A_i``, shape ``(k, d, d)``, or ``(d, d)`` for a single vertex. @@ -1756,79 +1654,17 @@ def solve_minimax( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata["fw_iters"] = n_iter - if not converged: - mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - n_iter += n_eval + n_fallback_newton - metadata["fallback_method"] = "scipy-slsqp" - metadata["fallback_n_fevals"] = n_eval - metadata["fallback_newton_iters"] = n_fallback_newton - metadata["fallback_converged"] = converged elif method == "fw+brentq": mu, converged, n_iter, meta_fw = _run_fw_brentq( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) metadata.update(meta_fw) - if not converged: - mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - n_iter += n_eval + n_fallback_newton - metadata["fallback_method"] = "scipy-slsqp" - metadata["fallback_n_fevals"] = n_eval - metadata["fallback_newton_iters"] = n_fallback_newton - metadata["fallback_converged"] = converged elif method == "fw+bisect+newton": mu, converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) - fallback_meta: dict[str, Any] = {} - if not converged: - mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - fallback_meta = { - "fallback_method": "scipy-slsqp", - "fallback_n_fevals": n_eval, - "fallback_newton_iters": n_fallback_newton, - "fallback_converged": converged, - } - else: - n_eval = 0 - n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _newton_polish( mu, @@ -1844,7 +1680,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton + n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1862,37 +1698,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw - metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "fw+brentq+newton": mu, converged, n_iter_fw, meta_fw = _run_fw_brentq( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) - fallback_meta = {} - if not converged: - mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - fallback_meta = { - "fallback_method": "scipy-slsqp", - "fallback_n_fevals": n_eval, - "fallback_newton_iters": n_fallback_newton, - "fallback_converged": converged, - } - else: - n_eval = 0 - n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1908,7 +1719,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton + n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1926,37 +1737,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata.update(meta_fw) - metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "fw+bisect+damped-newton": mu, converged, n_iter_fw = _run_fw_bisect( matrices, Ax, centers, offsets, mu_init, **_fw_kwargs ) - fallback_meta = {} - if not converged: - mu, converged, n_eval, n_fallback_newton = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - fallback_meta = { - "fallback_method": "scipy-slsqp", - "fallback_n_fevals": n_eval, - "fallback_newton_iters": n_fallback_newton, - "fallback_converged": converged, - } - else: - n_eval = 0 - n_fallback_newton = 0 active_set_fw = [i for i in range(k) if mu[i] > weight_tol] mu, n_iter_newton, meta_newton = _damped_newton_polish( mu, @@ -1972,7 +1758,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - n_iter = n_iter_fw + n_eval + n_fallback_newton + n_iter_newton + n_iter = n_iter_fw + n_iter_newton active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, @@ -1990,7 +1776,6 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) metadata["fw_iters"] = n_iter_fw - metadata.update(fallback_meta) metadata.update(meta_newton) elif method == "newton-cold": @@ -2028,74 +1813,7 @@ def solve_minimax( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - if not converged: - mu, fallback_converged, n_iter_fw = _run_fw_bisect( - matrices, Ax, centers, offsets, mu_init, **_fw_kwargs - ) - n_iter += n_iter_fw - metadata.update({f"cold_{key}": value for key, value in meta_cold.items()}) - metadata["fallback_method"] = "fw+bisect" - metadata["fallback_fw_iters"] = n_iter_fw - if not fallback_converged: - ( - mu, - fallback_converged, - n_eval, - n_fallback_newton, - ) = _run_slsqp_fallback( - mu, - matrices, - Ax, - centers, - offsets, - tol=tol, - weight_tol=weight_tol, - newton_max_iter=newton_max_iter, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - n_iter += n_eval + n_fallback_newton - metadata["secondary_fallback_method"] = "scipy-slsqp" - metadata["fallback_n_fevals"] = n_eval - metadata["fallback_newton_iters"] = n_fallback_newton - - active_set_fallback = [i for i in range(k) if mu[i] > weight_tol] - mu, n_iter_newton, meta_newton = _damped_newton_polish( - mu, - active_set_fallback, - matrices, - Ax, - centers, - offsets, - weight_tol=weight_tol, - max_iter=newton_max_iter, - tol=newton_tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - n_iter += n_iter_newton - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] - converged = _check_newton_convergence( - mu, - active_set_newton, - matrices, - Ax, - centers, - offsets, - fallback_converged, - newton_tol, - meta_newton["newton_status"], - tol=tol, - regularization=regularization, - condition_number_limit=condition_number_limit, - max_conditioning_steps=max_conditioning_steps, - ) - metadata["fallback_converged"] = fallback_converged - metadata.update(meta_newton) - else: - metadata.update(meta_cold) + metadata.update(meta_cold) elif method == "scipy-slsqp": mu, converged, n_iter = _run_scipy_slsqp( diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index 0c2b5c8..fc19611 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -44,7 +44,7 @@ def solve_minimax( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> MinimaxResult: - """Solve the dual with plain FW and a robust SLSQP/Newton fallback.""" + """Solve the dual with the selected minimax method.""" ... def solve_minimax_from_coefs( diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 7402965..d339655 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -247,9 +247,8 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default uses plain - Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts - its budget. + method: Internal many-body solver method. The default is + ``"fw+brentq"``, plain Frank-Wolfe with adaptive Brent line search. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. @@ -273,7 +272,8 @@ def cech( Packed input requires ``d >= 2``, as for :func:`ellphi.tangency`. RuntimeError: If the internal solver does not converge or produces a - non-finite output. Solver diagnostics are included in the error. + non-finite output. The error names the method, iterations, final + duality gap, and ``tol`` and gives retry guidance. """ coefs = np.asarray(coefs, dtype=float) if coefs.ndim != 2: @@ -312,22 +312,22 @@ def cech( and np.all(np.isfinite(result.circumcenter)) and np.all(np.isfinite(result.weights)) ) - if not result.converged or not finite: - reason = "did not converge" if not result.converged else "was non-finite" - raise RuntimeError( - "cech " - f"{reason}: method={result.method!r}, n_iter={result.n_iter}, " - f"diagnostics={result.metadata!r}" - ) - values = _centered_constraint_values( result.circumcenter, matrices, centers, offsets ) - if not np.all(np.isfinite(values)): + finite_values = np.all(np.isfinite(values)) + final_gap = ( + float(np.max(values) - np.dot(result.weights, values)) + if finite and finite_values + else float("nan") + ) + if not result.converged or not finite or not finite_values: + reason = "did not converge" if not result.converged else "was non-finite" raise RuntimeError( - "cech was non-finite: " - f"method={result.method!r}, n_iter={result.n_iter}, " - f"diagnostics={result.metadata!r}" + "cech " + f"{reason}: method={result.method!r}, iterations={result.n_iter}, " + f"duality_gap={final_gap:.17g}, tol={tol:g}; " + "a larger max_iter or a different method may be chosen" ) alpha = float(result.alpha) constraint_scale = float(np.max(np.abs(values))) @@ -395,9 +395,8 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default uses plain - Frank-Wolfe with an SLSQP/Newton fallback if that phase exhausts - its budget. + method: Internal many-body solver method. The default is + ``"fw+brentq"``, plain Frank-Wolfe with adaptive Brent line search. tol: Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index e8799e0..bf5b1e4 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -37,7 +37,7 @@ def cech( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: - """Compute the Čech time with the robust FW/SLSQP/Newton default.""" + """Compute the Čech time with the default ``fw+brentq`` method.""" ... def cech_grad( @@ -51,5 +51,5 @@ def cech_grad( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechGrad: - """Compute the Čech time and gradient with the robust default solver.""" + """Compute the Čech time and gradient with the default ``fw+brentq`` method.""" ... diff --git a/tests/test_cech.py b/tests/test_cech.py index fb44efc..09c3c32 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -336,19 +336,17 @@ def test_singleton_and_empty_cech_input(): ellphi.cech(np.empty((0, coefs.shape[1]))) -def test_non_convergence_raises_with_diagnostics(monkeypatch): +def test_non_convergence_raises_with_gap_and_retry_guidance(): coefs = _random_coefs(5, 3, seed=101) - monkeypatch.setattr( - "ellphi._minimax_python._run_slsqp_fallback", - lambda mu, *args, **kwargs: (mu, False, 0, 0), - ) with pytest.raises(RuntimeError) as exc_info: ellphi.cech(coefs, method="fw+bisect", max_iter=1, tol=1e-15) message = str(exc_info.value) assert "method='fw+bisect'" in message - assert "n_iter=1" in message - assert "diagnostics=" in message + assert "iterations=1" in message + assert "duality_gap=" in message + assert "tol=1e-15" in message + assert "larger max_iter or a different method" in message @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @@ -367,18 +365,19 @@ def test_public_api_rejects_private_stabilization_controls(api, name, value): api(coefs, **{name: value}) -def test_public_newton_cold_returns_a_successful_fw_fallback(): - coefs = _random_coefs(5, 3, seed=0) +def test_public_newton_cold_reports_nonconvergence_without_retry(): + matrices, centers = minimax_public_surrogate() + linear = -np.einsum("kij,kj->ki", matrices, centers) + constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) + coefs = pack_conic(matrices, linear, constants) - result = ellphi.cech( - coefs, - method="newton-cold", - newton_max_iter=1, - tol=1e-10, - ) + engine_result = solve_minimax(matrices, centers, method="newton-cold") + assert not engine_result.converged + assert engine_result.metadata is not None + assert "newton_status" in engine_result.metadata - assert np.isfinite(result.t) - assert result.active_set + with pytest.raises(RuntimeError, match="duality_gap="): + ellphi.cech(coefs, method="newton-cold") @pytest.mark.parametrize("k,d,seed", [(3, 2, 201), (4, 2, 203)]) @@ -441,16 +440,40 @@ def test_unnormalized_constant_agrees_with_expected(api): assert result.active_set == (0, 1) -@pytest.mark.parametrize("method", list(get_args(MethodName))) -def test_public_surrogate_methods(method): +def _public_surrogate_coefs(): matrices, centers = minimax_public_surrogate() linear = -np.einsum("kij,kj->ki", matrices, centers) constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) - coefs = pack_conic(matrices, linear, constants) + return pack_conic(matrices, linear, constants) + + +def test_public_surrogate_default_raises_with_honest_gap(): + coefs = _public_surrogate_coefs() + + with pytest.raises(RuntimeError) as exc_info: + ellphi.cech(coefs) + + message = str(exc_info.value) + assert "method='fw+brentq'" in message + assert "duality_gap=" in message + assert "tol=1e-09" in message + + +def test_public_surrogate_fw_brentq_converges_with_large_budget(): + coefs = _public_surrogate_coefs() + + result = ellphi.cech(coefs, method="fw+brentq", max_iter=20000) + + assert result.t**2 == pytest.approx(0.9024444260, abs=1e-8) + assert result.support == (1, 3, 5) + + +def test_public_surrogate_slsqp_converges_at_default_budget(): + coefs = _public_surrogate_coefs() - result = ellphi.cech(coefs, method=method) + result = ellphi.cech(coefs, method="scipy-slsqp") - assert result.t**2 == pytest.approx(0.9024444260258915, rel=1e-8) + assert result.t**2 == pytest.approx(0.9024444260, abs=1e-8) assert result.support == (1, 3, 5) diff --git a/tests/test_minimax.py b/tests/test_minimax.py index b954eaa..26363f2 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -839,7 +839,7 @@ def test_unnormalized_pairwise_coefs_match_tangency(solver_backend, rng, dim): coefs[:, -1] += rng.uniform(0.1, 1.0, size=2) pairwise = ellphi.tangency(coefs[0], coefs[1], backend=solver_backend) - res = solve_minimax_from_coefs(coefs, tol=1e-11) + res = solve_minimax_from_coefs(coefs, method="scipy-slsqp", tol=1e-11) assert res.converged assert res.alpha == pytest.approx(pairwise.t**2, rel=1e-9) diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index 07c3376..37c8696 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -4,7 +4,7 @@ 82d13e3e174f4903cdcd6adcee1f469348361c91. The benchmark smoke tests are not ported because the benchmark module is not part of ellphi. -All methods must agree on alpha to tight tolerances. +Methods that converge must agree on alpha to tight tolerances. fw+bisect is the reference (validated against ellphi in test_minimax.py). """ @@ -59,7 +59,7 @@ def public_surrogate_results(): matrices, centers = minimax_public_surrogate() results = { method: solve_minimax(matrices, centers, method=method) - for method in CANONICAL_METHODS + for method in ("fw+bisect", "fw+brentq", "scipy-slsqp") } return matrices, centers, results @@ -108,59 +108,15 @@ def test_plain_fw_converges_with_large_budget(self): assert result.converged assert result.n_iter > 2000 assert result.metadata is not None - assert "fallback_method" not in result.metadata assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 - def test_default_uses_slsqp_fallback(self): + def test_default_budget_reports_plain_fw_nonconvergence(self): matrices, centers = minimax_public_surrogate() result = solve_minimax(matrices, centers) - assert result.converged + assert not result.converged assert result.method == "fw+brentq" assert result.metadata is not None - assert result.metadata["fallback_method"] == "scipy-slsqp" - - @pytest.mark.parametrize("method", CANONICAL_METHODS) - def test_all_methods_converge_accurately(self, method, public_surrogate_results): - matrices, centers, results = public_surrogate_results - result = results[method] - gap, residual = _surrogate_diagnostics(result, matrices, centers) - - assert result.converged - assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 - assert gap <= 1e-8 - assert residual <= 1e-8 - assert result.active_set == [1, 3, 5] - - @pytest.mark.parametrize( - "method", - [ - "fw+bisect+newton", - "fw+brentq+newton", - "fw+bisect+damped-newton", - "newton-cold", - ], - ) - def test_newton_hybrids_polish_the_minimal_face( - self, method, public_surrogate_results - ): - _, _, results = public_surrogate_results - result = results[method] - - assert result.metadata is not None - assert result.metadata["newton_status"] == "converged" - assert len(result.active_set) <= 3 - - def test_newton_failures_do_not_collapse_to_a_vertex( - self, public_surrogate_results - ): - _, _, results = public_surrogate_results - bisect_error = abs(results["fw+bisect"].alpha - SURROGATE_ALPHA) - brentq_error = abs(results["fw+brentq"].alpha - SURROGATE_ALPHA) - - for method in ("fw+bisect+newton", "fw+bisect+damped-newton", "newton-cold"): - assert abs(results[method].alpha - SURROGATE_ALPHA) <= bisect_error - assert abs(results["fw+brentq+newton"].alpha - SURROGATE_ALPHA) <= brentq_error # --------------------------------------------------------------------------- @@ -279,25 +235,6 @@ def test_metadata_has_line_search_evals(self): assert "line_search_evals" in res.metadata assert res.metadata["line_search_evals"] > 0 - def test_fallback_respects_fw_iteration_budget(self, monkeypatch): - matrices, centers = minimax_public_surrogate() - - def unexpected_bisect(*args, **kwargs): - raise AssertionError("fallback must not start another FW run") - - monkeypatch.setattr("ellphi._minimax_python._run_fw_bisect", unexpected_bisect) - result = solve_minimax( - matrices, - centers, - method="fw+brentq", - tol=1e-15, - max_iter=1, - ) - - assert result.metadata is not None - assert result.metadata["fw_iters"] == 1 - assert "fallback_newton_iters" in result.metadata - # --------------------------------------------------------------------------- # fw+brentq+newton specific @@ -351,7 +288,7 @@ def test_result_finite(self, seed): assert np.isfinite(res.alpha) assert np.all(np.isfinite(res.circumcenter)) - def test_converged_fw_fallback_is_reported(self): + def test_failed_newton_reports_its_status_without_retry(self): matrices, centers = _random_simplex(5, 3, seed=0) result = solve_minimax( matrices, @@ -361,9 +298,9 @@ def test_converged_fw_fallback_is_reported(self): tol=1e-10, ) - assert result.converged + assert not result.converged assert result.metadata is not None - assert result.metadata["fallback_converged"] is True + assert "newton_status" in result.metadata # --------------------------------------------------------------------------- From 357fb018a70d0bad0159bd3d36ea3ce5bb3a1029 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 13:21:02 +0900 Subject: [PATCH 20/29] docs: name the dual step pairwise Frank-Wolfe; declare comparator tolerances Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 13 ++++--- scripts/compare_minimax_engine.py | 65 +++++++++++++++++++++++-------- src/ellphi/_minimax_python.py | 46 +++++++++++++++++----- src/ellphi/_minimax_python.pyi | 2 +- src/ellphi/cech.py | 14 +++++-- src/ellphi/cech.pyi | 4 +- tests/factories.py | 7 ++-- tests/test_minimax_methods.py | 22 ++++++++++- 8 files changed, 130 insertions(+), 43 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index dd5c821..b1098f5 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -43,11 +43,14 @@ two indices, and `active_set` has three. A solver that does not converge or produces non-finite output raises `RuntimeError` naming its method, iterations, final duality gap, and `tol`. -The default solver is `fw+brentq`, plain Frank-Wolfe on the dual simplex with -an adaptive Brent line search. On the bundled surrogate, a zero-weight -constraint is nearly tight, so the all-index gap can stall while weight leaks -onto that vertex; this is recorded in the test factory because it explains -why plain FW may not converge within the default budget. A non-converged +The default solver is `fw+brentq`, pairwise Frank-Wolfe on the dual simplex +with an adaptive Brent line search. Each step selects the best vertex (largest +constraint value) and the worst active vertex (smallest constraint value), then +swaps mass along `e_s - e_v` with step at most `mu[v]`; this is ellcech's +original step. On the bundled surrogate, the near-tight zero-weight vertex 4 +keeps re-entering as the swap target, so the all-index gap can stall; this is +recorded in the test factory because it explains why pairwise FW may not +converge within the default budget. A non-converged public solve raises `RuntimeError` with the method, iterations, final duality gap, and `tol`; callers may choose a larger `max_iter` or a different `method`. diff --git a/scripts/compare_minimax_engine.py b/scripts/compare_minimax_engine.py index c506a64..4816e57 100644 --- a/scripts/compare_minimax_engine.py +++ b/scripts/compare_minimax_engine.py @@ -17,8 +17,9 @@ compare /tmp/legacy.json /tmp/candidate.json Only cases for which the legacy engine reports ``converged=True`` are fidelity -requirements. Alpha, circumcenter, and weights must then agree absolutely to -``1e-12``, and the candidate must also report convergence. +requirements. The comparison reports per-method maxima for alpha, +circumcenter, and weights and checks each against its declared absolute +tolerance; the candidate must also report convergence. """ from __future__ import annotations @@ -45,7 +46,21 @@ ) BASE_SEED = 260_027 INSTANCES_PER_SHAPE = 20 -FIDELITY_ATOL = 1e-12 +METHOD_TOLERANCES = { + "fw+bisect": 1e-12, + "fw+brentq": 1e-12, + "fw+bisect+newton": 1e-11, + "fw+brentq+newton": 1e-11, + "fw+bisect+damped-newton": 1e-11, + "scipy-slsqp": 1e-6, + "newton-cold": 1e-12, +} +METHOD_REASONS = { + "scipy-slsqp": ( + "direct SLSQP is gap-enforced and Newton-polished in this port, " + "deviation list item 10" + ) +} def _solver(engine: str, source_root: Path | None) -> Callable[..., Any]: @@ -184,26 +199,44 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: converged = 0 mismatches = [] converged_by_method = {method: 0 for method in METHODS} + per_method = { + method: { + "legacy_converged": 0, + "mismatches": 0, + "max_abs_dalpha": 0.0, + "max_abs_dx": 0.0, + "max_abs_dmu": 0.0, + "declared_tolerance": METHOD_TOLERANCES[method], + **({"reason": METHOD_REASONS[method]} if method in METHOD_REASONS else {}), + } + for method in METHODS + } for key, old in legacy.items(): if not old["converged"]: continue converged += 1 - converged_by_method[key[-1]] += 1 + method = key[-1] + converged_by_method[method] += 1 + stats = per_method[method] + stats["legacy_converged"] += 1 new = candidate[key] - same = ( - new["converged"] - and abs(new["alpha"] - old["alpha"]) <= FIDELITY_ATOL - and np.allclose( - new["circumcenter"], - old["circumcenter"], - rtol=0.0, - atol=FIDELITY_ATOL, - ) - and np.allclose( - new["weights"], old["weights"], rtol=0.0, atol=FIDELITY_ATOL + dalpha = abs(float(new["alpha"] - old["alpha"])) + dx = float( + np.max( + np.abs( + np.asarray(new["circumcenter"]) - np.asarray(old["circumcenter"]) + ) ) ) + dmu = float( + np.max(np.abs(np.asarray(new["weights"]) - np.asarray(old["weights"]))) + ) + stats["max_abs_dalpha"] = max(stats["max_abs_dalpha"], dalpha) + stats["max_abs_dx"] = max(stats["max_abs_dx"], dx) + stats["max_abs_dmu"] = max(stats["max_abs_dmu"], dmu) + same = new["converged"] and max(dalpha, dx, dmu) <= METHOD_TOLERANCES[method] if not same: + stats["mismatches"] += 1 mismatches.append(key) summary = { @@ -212,7 +245,7 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: "legacy_converged_by_method": converged_by_method, "mismatches": len(mismatches), "first_mismatches": mismatches[:10], - "atol": FIDELITY_ATOL, + "per_method": per_method, "status": "complete" if not mismatches else "failed", } print(json.dumps(summary, indent=2, sort_keys=True)) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index da3d7a1..0efcae3 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -39,6 +39,8 @@ this can increase the step count without changing the accepted result. * A post-polish Cholesky factorization failure forces ``converged=False``; ellcech 82d13e3 preserved the prior convergence flag in this case. +* Direct ``scipy-slsqp`` is gap-enforced and Newton-polished when its initial + result misses the requested global gap. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of ``unpack_conic`` and type annotations) or documentation. Distributed as part @@ -80,6 +82,12 @@ conditioning the solver works on a stabilised ``A(mu)`` and its outputs approximate that stabilised problem. +The FW runners use ellcech's original pairwise Frank-Wolfe step on the dual +simplex: ``s`` is the best vertex (largest constraint value), ``v`` is the +worst active vertex (smallest constraint value), and mass is transferred along +``e_s - e_v`` by ``0 <= gamma <= mu[v]``. This pairwise step is not a +deviation from ellcech and is therefore not listed above. + Weight support versus tight set ------------------------------- ``MinimaxResult.active_set`` is the *weight support* @@ -456,7 +464,12 @@ def _exact_line_search( condition_number_limit: float | None, max_conditioning_steps: int, ) -> float: - """Find gamma* in [0, gamma_max] that maximises g along the pairwise direction. + """Maximise ``g`` along a dual-simplex pairwise Frank-Wolfe swap. + + The direction is ``e_s - e_v``, where ``s`` is the best vertex (largest + constraint value) and ``v`` is the worst active vertex (smallest + constraint value). The line search is restricted to + ``0 <= gamma <= gamma_max <= mu[v]``. Bisects on the stabilized dual directional derivative ``h(gamma) = grad_s - grad_v``. @@ -531,7 +544,12 @@ def _brentq_line_search( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[float, int]: - """Brentq-based line search replacing fixed 52-step bisection. + """Brentq line search for a dual-simplex pairwise Frank-Wolfe swap. + + The direction is ``e_s - e_v``, with ``s`` the best vertex (largest + constraint value) and ``v`` the worst active vertex (smallest constraint + value). The line search is restricted to + ``0 <= gamma <= gamma_max <= mu[v]``. Returns: (gamma, n_fevals): Optimal step and number of function evaluations. @@ -621,7 +639,11 @@ def _run_fw_bisect( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int]: - """Plain Frank-Wolfe with exact bisection line search. + """Pairwise Frank-Wolfe with exact bisection line search. + + Each swap chooses the best vertex (largest constraint value) and the + worst active vertex (smallest constraint value), then transfers mass along + ``e_s - e_v`` with step at most ``mu[v]``. Returns: (mu, converged, n_iter) @@ -734,7 +756,11 @@ def _run_fw_brentq( condition_number_limit: float | None, max_conditioning_steps: int, ) -> tuple[np.ndarray, bool, int, dict]: - """Plain Frank-Wolfe with brentq line search. + """Pairwise Frank-Wolfe with brentq line search. + + Each swap chooses the best vertex (largest constraint value) and the + worst active vertex (smallest constraint value), then transfers mass along + ``e_s - e_v`` with step at most ``mu[v]``. Returns: (mu, converged, n_iter, metadata) @@ -1513,11 +1539,11 @@ def solve_minimax( Seven solver back-ends are available via ``method``: - * ``"fw+bisect"``: Plain FW with 52-step bisection line search. - * ``"fw+brentq"`` (default): Plain FW with adaptive brentq line search. - * ``"fw+bisect+newton"``: FW(bisect) warm-start + Newton polishing. - * ``"fw+brentq+newton"``: FW(brentq) warm-start + damped Newton polishing. - * ``"fw+bisect+damped-newton"``: FW(bisect) + Armijo-damped Newton. + * ``"fw+bisect"``: Pairwise FW with 52-step bisection line search. + * ``"fw+brentq"`` (default): Pairwise FW with adaptive brentq line search. + * ``"fw+bisect+newton"``: Pairwise FW(bisect) warm-start + Newton polishing. + * ``"fw+brentq+newton"``: Pairwise FW(brentq) warm-start + damped Newton polishing. + * ``"fw+bisect+damped-newton"``: Pairwise FW(bisect) + Armijo-damped Newton. * ``"scipy-slsqp"``: Direct SLSQP solve via scipy, with Newton accuracy polishing if SLSQP's result misses the requested global gap. * ``"newton-cold"``: Newton from uniform mu=1/k (stability baseline). @@ -1533,7 +1559,7 @@ def solve_minimax( offsets: Optional additive constants ``delta_i``, shape ``(k,)``. ``None`` is the original zero-offset problem. method: One of the seven canonical method names above. - tol: Frank-Wolfe gap tolerance for the FW-based methods. + tol: Pairwise Frank-Wolfe gap tolerance for the FW-based methods. max_iter: Maximum number of Frank-Wolfe iterations. weight_tol: Threshold defining the weight support ``active_set``. It also selects the face used by Newton polishing. diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index fc19611..971f881 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -44,7 +44,7 @@ def solve_minimax( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> MinimaxResult: - """Solve the dual with the selected minimax method.""" + """Solve the dual; FW methods use pairwise swaps on the dual simplex.""" ... def solve_minimax_from_coefs( diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index d339655..49fca77 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -248,8 +248,11 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default is - ``"fw+brentq"``, plain Frank-Wolfe with adaptive Brent line search. - tol: Frank-Wolfe gap tolerance. + ``"fw+brentq"``, pairwise Frank-Wolfe on the dual simplex: each + step swaps mass from the worst active vertex to the best vertex + along ``e_s - e_v``, with step at most ``mu[v]``, using adaptive + Brent line search. This is ellcech's original step. + tol: Pairwise Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set`` as the @@ -396,8 +399,11 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default is - ``"fw+brentq"``, plain Frank-Wolfe with adaptive Brent line search. - tol: Frank-Wolfe gap tolerance. + ``"fw+brentq"``, pairwise Frank-Wolfe on the dual simplex: each + step swaps mass from the worst active vertex to the best vertex + along ``e_s - e_v``, with step at most ``mu[v]``, using adaptive + Brent line search. This is ellcech's original step. + tol: Pairwise Frank-Wolfe gap tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set``. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index bf5b1e4..e9cb396 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -37,7 +37,7 @@ def cech( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: - """Compute the Čech time with the default ``fw+brentq`` method.""" + """Compute Čech time using pairwise FW swaps on the dual simplex.""" ... def cech_grad( @@ -51,5 +51,5 @@ def cech_grad( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechGrad: - """Compute the Čech time and gradient with the default ``fw+brentq`` method.""" + """Compute Čech time and its gradient using pairwise FW swaps.""" ... diff --git a/tests/factories.py b/tests/factories.py index 63e1718..941667e 100644 --- a/tests/factories.py +++ b/tests/factories.py @@ -85,9 +85,10 @@ def minimax_public_surrogate() -> tuple[np.ndarray, np.ndarray]: At the optimum, constraint ``f_4`` is nearly tight even though ``mu_4`` is zero, placing the instance near a failure of strict complementarity. The - all-index Frank-Wolfe gap must become much smaller than that slack, so - plain FW can stall while weight leaks onto vertex 4. Newton polishing on - the resulting face is rank-deficient, whereas primal SLSQP is unaffected. + all-index Frank-Wolfe gap must become much smaller than that slack, so the + near-tight zero-weight vertex 4 keeps re-entering as the pairwise swap + target and the all-index gap stalls. Newton polishing on the resulting + face is rank-deficient, whereas primal SLSQP is unaffected. """ matrices = np.array( [ diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index 37c8696..c3e3d93 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -96,7 +96,7 @@ def test_slsqp_reference_value_and_gap(self, public_surrogate_results): assert gap <= 1e-8 assert residual <= 1e-8 - def test_plain_fw_converges_with_large_budget(self): + def test_pairwise_fw_converges_with_large_budget(self): matrices, centers = minimax_public_surrogate() result = solve_minimax( matrices, @@ -110,7 +110,7 @@ def test_plain_fw_converges_with_large_budget(self): assert result.metadata is not None assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 - def test_default_budget_reports_plain_fw_nonconvergence(self): + def test_default_budget_reports_pairwise_fw_nonconvergence(self): matrices, centers = minimax_public_surrogate() result = solve_minimax(matrices, centers) @@ -118,6 +118,24 @@ def test_default_budget_reports_plain_fw_nonconvergence(self): assert result.method == "fw+brentq" assert result.metadata is not None + def test_pairwise_fw_swaps_only_best_and_worst_weights(self): + """One pairwise FW step changes two coordinates and preserves their mass.""" + matrices = np.repeat(np.eye(1)[np.newaxis, :, :], 3, axis=0) + centers = np.array([[0.0], [1.0], [3.0]]) + initial = np.full(3, 1.0 / 3.0) + + result = solve_minimax( + matrices, + centers, + method="fw+bisect", + max_iter=1, + tol=1e-30, + ) + + changed = np.flatnonzero(result.weights != initial) + assert changed.size == 2 + assert result.weights[changed].sum() == pytest.approx(initial[changed].sum()) + # --------------------------------------------------------------------------- # Basic dispatch / API From 0d60fb05dde5ce13d879654a038a816ae27abffd Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 13:29:14 +0900 Subject: [PATCH 21/29] fix: bound packed normalization roundoff by the largest row Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/cech.py | 8 ++++---- tests/test_cech.py | 14 +++++++++++++- 2 files changed, 17 insertions(+), 5 deletions(-) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 49fca77..33193b6 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -179,9 +179,9 @@ def _prepare_coefs( ``c = xbar.T @ A @ xbar + delta``. Computing ``delta`` from a far-translated or ill-conditioned row can therefore lose precision of order ``eps * cond2(A) * max(abs(c), abs(xbar.T @ A @ xbar))``. The - returned ``value_roundoff`` is the sum of these per-row bounds; callers - needing exact normalization at large translations should center their data - first. + returned ``value_roundoff`` is the maximum of these per-row bounds; the + minimax value is a convex combination of row offsets. Callers needing + exact normalization at large translations should center their data first. """ matrices, linear, constants = unpack_conic(coefs) _validate_quadratic_matrices(matrices) @@ -210,7 +210,7 @@ def _prepare_coefs( ) centers[row] = -inverse_times_linear offsets[row] = delta - value_roundoff += row_roundoff + value_roundoff = max(value_roundoff, row_roundoff) return matrices, centers, offsets, float(value_roundoff) diff --git a/tests/test_cech.py b/tests/test_cech.py index 09c3c32..626daba 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -35,7 +35,7 @@ def _relative_error(actual: np.ndarray | float, expected: np.ndarray | float) -> def _value_roundoff_bound(coefs: np.ndarray) -> float: matrices, linear, constants = unpack_conic(coefs) - return sum( + return max( 64.0 * np.finfo(float).eps * np.linalg.cond(matrix, 2) @@ -248,6 +248,18 @@ def test_negative_packed_scale_raises(): ellphi.cech(coefs) +def test_negative_scale_roundoff_bound_does_not_grow_with_simplex_size(): + k = 100 + centers = np.repeat(np.array([[1e6, 0.0]]), k, axis=0) + coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], k, axis=0)) + coefs[:, -1] = 1e12 - 0.5 + + with pytest.raises( + ValueError, match="packed quadrics have no common non-negative filtration scale" + ): + ellphi.cech(coefs) + + @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @pytest.mark.parametrize( "matrix", From 4301950e0ec06bbf1ef3bba79d07a52e36932165 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 15:27:30 +0900 Subject: [PATCH 22/29] feat: default fw+brentq+newton; relative duality-gap convergence test Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 21 ++++++++--------- src/ellphi/_minimax_python.py | 42 +++++++++++++++++++++++----------- src/ellphi/_minimax_python.pyi | 2 +- src/ellphi/cech.py | 31 ++++++++++++++----------- src/ellphi/cech.pyi | 4 ++-- tests/test_cech.py | 5 ++-- tests/test_minimax.py | 4 +++- tests/test_minimax_methods.py | 36 +++++++++++++++++++++++++---- 8 files changed, 98 insertions(+), 47 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index b1098f5..b12bfda 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -41,18 +41,17 @@ strict complementarity (ND1), they coincide. For three unit balls centred at `(0, 0)`, `(2, 0)`, and `(0, 2)`, the point is `(1, 1)`, support has two indices, and `active_set` has three. A solver that does not converge or produces non-finite output raises `RuntimeError` naming its method, iterations, -final duality gap, and `tol`. +final duality gap, `tol`, and the scale used for the relative gap test. -The default solver is `fw+brentq`, pairwise Frank-Wolfe on the dual simplex -with an adaptive Brent line search. Each step selects the best vertex (largest -constraint value) and the worst active vertex (smallest constraint value), then -swaps mass along `e_s - e_v` with step at most `mu[v]`; this is ellcech's -original step. On the bundled surrogate, the near-tight zero-weight vertex 4 -keeps re-entering as the swap target, so the all-index gap can stall; this is -recorded in the test factory because it explains why pairwise FW may not -converge within the default budget. A non-converged -public solve raises `RuntimeError` with the method, iterations, final duality -gap, and `tol`; callers may choose a larger `max_iter` or a different `method`. +The default solver is `fw+brentq+newton`, pairwise Frank-Wolfe on the dual +simplex with an adaptive Brent line search followed by Newton polishing. Each +Frank-Wolfe step selects the best vertex (largest constraint value) and the +worst active vertex (smallest constraint value), then swaps mass along +`e_s - e_v` with step at most `mu[v]`. Its gap tolerance is relative to +`max(1, |dual value|)`. On the bundled surrogate, the near-tight zero-weight +vertex 4 keeps re-entering as the swap target, so the all-index gap can stall; +the default `fw+brentq+newton` therefore remains non-convergent within the +default budget. Callers may choose a larger `max_iter` or a different `method`. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 0efcae3..f45a19f 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -41,6 +41,9 @@ ellcech 82d13e3 preserved the prior convergence flag in this case. * Direct ``scipy-slsqp`` is gap-enforced and Newton-polished when its initial result misses the requested global gap. +* Frank-Wolfe gap convergence uses ``gap <= tol * max(1, abs(g_hat))``, where + ``gap = max_i gradient_i - g_hat`` and ``g_hat = dot(mu, gradient)``; + ellcech uses an absolute gap instead. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of ``unpack_conic`` and type annotations) or documentation. Distributed as part @@ -434,6 +437,22 @@ def _dual_gradient( return f + shift_gradient * float(np.dot(xstar, xstar)) +def _fw_gap_and_scale(mu: np.ndarray, gradient: np.ndarray) -> tuple[float, float]: + """Return the Frank-Wolfe gap and its relative dual-value scale.""" + dual_value = float(np.dot(mu, gradient)) + gap = float(np.max(gradient) - dual_value) + scale = ( + float(max(1.0, abs(dual_value))) if np.isfinite(dual_value) else float("nan") + ) + return gap, scale + + +def _fw_gap_converged(mu: np.ndarray, gradient: np.ndarray, tol: float) -> bool: + """Return whether the relative Frank-Wolfe gap meets ``tol``.""" + gap, scale = _fw_gap_and_scale(mu, gradient) + return bool(np.isfinite(gap) and np.isfinite(scale) and gap <= tol * scale) + + def _regularized_dual_value( mu: np.ndarray, matrices: np.ndarray, @@ -688,8 +707,7 @@ def _run_fw_bisect( if np.any(positive_mask): v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) - if fw_gap < tol: + if _fw_gap_converged(mu, gradient, tol): converged = True break @@ -737,7 +755,7 @@ def _run_fw_bisect( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - converged = float(np.max(gradient) - np.dot(mu, gradient)) < tol + converged = _fw_gap_converged(mu, gradient, tol) return mu, converged, n_iter @@ -808,8 +826,7 @@ def _run_fw_brentq( if np.any(positive_mask): v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) - if fw_gap < tol: + if _fw_gap_converged(mu, gradient, tol): converged = True break @@ -858,7 +875,7 @@ def _run_fw_brentq( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - converged = float(np.max(gradient) - np.dot(mu, gradient)) < tol + converged = _fw_gap_converged(mu, gradient, tol) metadata = { "fw_iters": n_iter, @@ -1434,8 +1451,7 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - fw_gap = float(np.max(gradient) - np.dot(mu, gradient)) - converged = bool(res.success) and np.isfinite(fw_gap) and fw_gap < tol + converged = bool(res.success) and _fw_gap_converged(mu, gradient, tol) return mu, converged, n_eval[0] @@ -1500,8 +1516,7 @@ def _check_newton_convergence( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - fw_gap = float(np.max(gradient_check) - np.dot(mu, gradient_check)) - if not np.isfinite(fw_gap) or fw_gap >= tol: + if not _fw_gap_converged(mu, gradient_check, tol): return False if len(active_set) <= 1: return True @@ -1516,7 +1531,7 @@ def solve_minimax( centers: np.ndarray, *, offsets: np.ndarray | None = None, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = _DEFAULT_TOL, max_iter: int = _DEFAULT_MAX_ITER, weight_tol: float = _DEFAULT_WEIGHT_TOL, @@ -1540,7 +1555,7 @@ def solve_minimax( Seven solver back-ends are available via ``method``: * ``"fw+bisect"``: Pairwise FW with 52-step bisection line search. - * ``"fw+brentq"`` (default): Pairwise FW with adaptive brentq line search. + * ``"fw+brentq"``: Pairwise FW with adaptive brentq line search. * ``"fw+bisect+newton"``: Pairwise FW(bisect) warm-start + Newton polishing. * ``"fw+brentq+newton"``: Pairwise FW(brentq) warm-start + damped Newton polishing. * ``"fw+bisect+damped-newton"``: Pairwise FW(bisect) + Armijo-damped Newton. @@ -1559,7 +1574,8 @@ def solve_minimax( offsets: Optional additive constants ``delta_i``, shape ``(k,)``. ``None`` is the original zero-offset problem. method: One of the seven canonical method names above. - tol: Pairwise Frank-Wolfe gap tolerance for the FW-based methods. + tol: Pairwise Frank-Wolfe gap tolerance for the FW-based methods, + relative to max(1, |dual value|). max_iter: Maximum number of Frank-Wolfe iterations. weight_tol: Threshold defining the weight support ``active_set``. It also selects the face used by Newton polishing. diff --git a/src/ellphi/_minimax_python.pyi b/src/ellphi/_minimax_python.pyi index 971f881..7b81a62 100644 --- a/src/ellphi/_minimax_python.pyi +++ b/src/ellphi/_minimax_python.pyi @@ -34,7 +34,7 @@ def solve_minimax( centers: np.ndarray, *, offsets: np.ndarray | None = None, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = 1e-09, max_iter: int = 2000, weight_tol: float = 1e-10, diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 33193b6..6f37e12 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -229,7 +229,7 @@ def _centered_constraint_values( def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -248,11 +248,10 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default is - ``"fw+brentq"``, pairwise Frank-Wolfe on the dual simplex: each - step swaps mass from the worst active vertex to the best vertex - along ``e_s - e_v``, with step at most ``mu[v]``, using adaptive - Brent line search. This is ellcech's original step. - tol: Pairwise Frank-Wolfe gap tolerance. + ``"fw+brentq+newton"``, pairwise Frank-Wolfe with adaptive Brent + line search followed by Newton polishing. + tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual + value|). max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set`` as the @@ -324,12 +323,19 @@ def cech( if finite and finite_values else float("nan") ) + dual_value = ( + float(np.dot(result.weights, values)) + if finite and finite_values + else float("nan") + ) + gap_scale = max(1.0, abs(dual_value)) if np.isfinite(dual_value) else float("nan") if not result.converged or not finite or not finite_values: reason = "did not converge" if not result.converged else "was non-finite" raise RuntimeError( "cech " f"{reason}: method={result.method!r}, iterations={result.n_iter}, " - f"duality_gap={final_gap:.17g}, tol={tol:g}; " + f"duality_gap={final_gap:.17g}, tol={tol:g}, " + f"duality_gap_scale={gap_scale:.17g}; " "a larger max_iter or a different method may be chosen" ) alpha = float(result.alpha) @@ -361,7 +367,7 @@ def cech( def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -399,11 +405,10 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. method: Internal many-body solver method. The default is - ``"fw+brentq"``, pairwise Frank-Wolfe on the dual simplex: each - step swaps mass from the worst active vertex to the best vertex - along ``e_s - e_v``, with step at most ``mu[v]``, using adaptive - Brent line search. This is ellcech's original step. - tol: Pairwise Frank-Wolfe gap tolerance. + ``"fw+brentq+newton"``, pairwise Frank-Wolfe with adaptive Brent + line search followed by Newton polishing. + tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual + value|). max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining ``support``. active_tol: Relative tolerance defining ``active_set``. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index e9cb396..249f88a 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -29,7 +29,7 @@ class CechGrad(NamedTuple): def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -43,7 +43,7 @@ def cech( def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq", + method: MethodName | str = "fw+brentq+newton", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, diff --git a/tests/test_cech.py b/tests/test_cech.py index 626daba..c13c122 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -199,7 +199,7 @@ def test_scaled_centres_from_cov_are_accepted(): ] ) - result = ellphi.cech(coef_from_cov(centers, covariances)) + result = ellphi.cech(coef_from_cov(centers, covariances), method="fw+brentq") assert np.isfinite(result.t) assert result.active_set == (0, 1) @@ -466,9 +466,10 @@ def test_public_surrogate_default_raises_with_honest_gap(): ellphi.cech(coefs) message = str(exc_info.value) - assert "method='fw+brentq'" in message + assert "method='fw+brentq+newton'" in message assert "duality_gap=" in message assert "tol=1e-09" in message + assert "duality_gap_scale=" in message def test_public_surrogate_fw_brentq_converges_with_large_budget(): diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 26363f2..9e10bd4 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -535,6 +535,8 @@ def test_fw_gap_uses_conditioning_shift_gradient(self): ) raw_gap = float(np.max(f) - np.dot(mu, f)) stabilized_gap = float(np.max(gradient) - np.dot(mu, gradient)) + stabilized_dual = float(np.dot(mu, gradient)) + relative_tol = stabilized_gap / (100.0 * max(1.0, abs(stabilized_dual))) assert raw_gap < 1.0 assert stabilized_gap > 1.0 @@ -550,7 +552,7 @@ def test_fw_gap_uses_conditioning_shift_gradient(self): centers, offsets, mu.copy(), - tol=stabilized_gap / 100.0, + tol=relative_tol, max_iter=1, weight_tol=1e-10, **kwargs, diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index c3e3d93..e45bcb4 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -54,6 +54,12 @@ def _surrogate_diagnostics(result, matrices, centers): return gap, residual +def _constraint_gap(result, matrices, centers): + diff = result.circumcenter[np.newaxis, :] - centers + values = np.einsum("ki,kij,kj->k", diff, matrices, diff) + return float(np.max(values) - result.weights @ values) + + @pytest.fixture(scope="module") def public_surrogate_results(): matrices, centers = minimax_public_surrogate() @@ -110,12 +116,12 @@ def test_pairwise_fw_converges_with_large_budget(self): assert result.metadata is not None assert abs(result.alpha - SURROGATE_ALPHA) <= 1e-8 - def test_default_budget_reports_pairwise_fw_nonconvergence(self): + def test_default_budget_reports_pairwise_fw_newton_nonconvergence(self): matrices, centers = minimax_public_surrogate() result = solve_minimax(matrices, centers) assert not result.converged - assert result.method == "fw+brentq" + assert result.method == "fw+brentq+newton" assert result.metadata is not None def test_pairwise_fw_swaps_only_best_and_worst_weights(self): @@ -172,10 +178,10 @@ def test_k0_raises(self, method): with pytest.raises(ValueError, match="k=0"): solve_minimax(np.zeros((0, 2, 2)), np.zeros((0, 2)), method=method) - def test_default_method_is_fw_brentq(self): + def test_default_method_is_fw_brentq_newton(self): matrices, centers = _random_simplex(2, 2) res = solve_minimax(matrices, centers) - assert res.method == "fw+brentq" + assert res.method == "fw+brentq+newton" @pytest.mark.parametrize("newton_tol", [np.nan, 0.0]) def test_non_positive_or_non_finite_newton_tol_raises(self, newton_tol): @@ -253,6 +259,28 @@ def test_metadata_has_line_search_evals(self): assert "line_search_evals" in res.metadata assert res.metadata["line_search_evals"] > 0 + def test_relative_gap_is_scale_invariant(self): + matrices, centers = _random_simplex(4, 2, seed=0) + scaled_matrices = matrices * 1e-8 + scaled_centers = centers * 1e8 + + result = solve_minimax(matrices, centers, method="fw+brentq") + scaled = solve_minimax(scaled_matrices, scaled_centers, method="fw+brentq") + + assert result.converged + assert scaled.converged + assert result.active_set == scaled.active_set + assert scaled.alpha == pytest.approx(result.alpha * 1e8, rel=1e-9) + + def test_large_alpha_uses_relative_gap(self): + matrices, centers = _random_simplex(4, 2, seed=0) + scaled = solve_minimax(matrices * 1e-8, centers * 1e8, method="fw+brentq") + + gap = _constraint_gap(scaled, matrices * 1e-8, centers * 1e8) + assert gap <= 1e-9 * scaled.alpha + if gap > 1e-9: + assert gap > 1e-9 + # --------------------------------------------------------------------------- # fw+brentq+newton specific From 3bf2406f381394886d02323ec7cb989fdf5d77ab Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 16:12:19 +0900 Subject: [PATCH 23/29] test: pin the relative-gap contract; comparator tolerance relative to alpha Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- scripts/compare_minimax_engine.py | 82 +++++++++++++++++++++++++++---- tests/test_minimax_methods.py | 19 +++++-- 2 files changed, 86 insertions(+), 15 deletions(-) diff --git a/scripts/compare_minimax_engine.py b/scripts/compare_minimax_engine.py index 4816e57..5c86a0c 100644 --- a/scripts/compare_minimax_engine.py +++ b/scripts/compare_minimax_engine.py @@ -17,9 +17,11 @@ compare /tmp/legacy.json /tmp/candidate.json Only cases for which the legacy engine reports ``converged=True`` are fidelity -requirements. The comparison reports per-method maxima for alpha, -circumcenter, and weights and checks each against its declared absolute -tolerance; the candidate must also report convergence. +requirements. The alpha comparison uses the declared method tolerance; FW-family +methods use the relative duality-gap contract for records with +``alpha_legacy > 1``. Records with ``alpha_legacy <= 1`` remain strict checks +against their declared tolerance. Circumcenter and weight deviations remain +reported diagnostics, and the candidate must also report convergence. """ from __future__ import annotations @@ -55,12 +57,15 @@ "scipy-slsqp": 1e-6, "newton-cold": 1e-12, } +RELATIVE_GAP_METHODS = frozenset(METHODS) - {"scipy-slsqp"} METHOD_REASONS = { - "scipy-slsqp": ( - "direct SLSQP is gap-enforced and Newton-polished in this port, " - "deviation list item 10" - ) + method: "relative duality-gap contract, module deviation list item 11" + for method in RELATIVE_GAP_METHODS } +METHOD_REASONS["scipy-slsqp"] = ( + "direct SLSQP is gap-enforced and Newton-polished in this port, " + "deviation list item 10" +) def _solver(engine: str, source_root: Path | None) -> Callable[..., Any]: @@ -198,6 +203,7 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: converged = 0 mismatches = [] + strict_tolerance_violations = [] converged_by_method = {method: 0 for method in METHODS} per_method = { method: { @@ -206,6 +212,24 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: "max_abs_dalpha": 0.0, "max_abs_dx": 0.0, "max_abs_dmu": 0.0, + "alpha_le_one": { + "count": 0, + "max_abs_deviation": 0.0, + "max_abs_dalpha": 0.0, + "max_abs_dx": 0.0, + "max_abs_dmu": 0.0, + "tolerance": METHOD_TOLERANCES[method], + }, + "alpha_gt_one": { + "count": 0, + "max_abs_deviation": 0.0, + "max_relative_deviation": 0.0, + "max_relative_dalpha": 0.0, + "max_abs_dalpha": 0.0, + "max_abs_dx": 0.0, + "max_abs_dmu": 0.0, + "tolerance": METHOD_TOLERANCES[method], + }, "declared_tolerance": METHOD_TOLERANCES[method], **({"reason": METHOD_REASONS[method]} if method in METHOD_REASONS else {}), } @@ -234,7 +258,40 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: stats["max_abs_dalpha"] = max(stats["max_abs_dalpha"], dalpha) stats["max_abs_dx"] = max(stats["max_abs_dx"], dx) stats["max_abs_dmu"] = max(stats["max_abs_dmu"], dmu) - same = new["converged"] and max(dalpha, dx, dmu) <= METHOD_TOLERANCES[method] + deviation = max(dalpha, dx, dmu) + alpha_scale = max(1.0, abs(float(old["alpha"]))) + if old["alpha"] <= 1: + partition = stats["alpha_le_one"] + tolerance = METHOD_TOLERANCES[method] + if dalpha > tolerance: + strict_tolerance_violations.append( + { + "record": key, + "alpha_legacy": old["alpha"], + "tolerance": tolerance, + "dalpha": dalpha, + "dx": dx, + "dmu": dmu, + } + ) + else: + partition = stats["alpha_gt_one"] + tolerance = METHOD_TOLERANCES[method] + if method in RELATIVE_GAP_METHODS: + tolerance = max(tolerance, 1e-9 * alpha_scale) + partition["max_relative_deviation"] = max( + partition["max_relative_deviation"], deviation / alpha_scale + ) + partition["max_relative_dalpha"] = max( + partition["max_relative_dalpha"], dalpha / alpha_scale + ) + partition["count"] += 1 + partition["max_abs_deviation"] = max(partition["max_abs_deviation"], deviation) + partition["max_abs_dalpha"] = max(partition["max_abs_dalpha"], dalpha) + partition["max_abs_dx"] = max(partition["max_abs_dx"], dx) + partition["max_abs_dmu"] = max(partition["max_abs_dmu"], dmu) + partition["tolerance"] = tolerance + same = new["converged"] and dalpha <= tolerance if not same: stats["mismatches"] += 1 mismatches.append(key) @@ -245,11 +302,16 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: "legacy_converged_by_method": converged_by_method, "mismatches": len(mismatches), "first_mismatches": mismatches[:10], + "strict_tolerance_violations": strict_tolerance_violations[:10], "per_method": per_method, - "status": "complete" if not mismatches else "failed", + "status": ( + "complete" + if not mismatches and not strict_tolerance_violations + else "failed" + ), } print(json.dumps(summary, indent=2, sort_keys=True)) - return 1 if mismatches else 0 + return 1 if mismatches or strict_tolerance_violations else 0 def main() -> int: diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index e45bcb4..90a8399 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -274,12 +274,21 @@ def test_relative_gap_is_scale_invariant(self): def test_large_alpha_uses_relative_gap(self): matrices, centers = _random_simplex(4, 2, seed=0) - scaled = solve_minimax(matrices * 1e-8, centers * 1e8, method="fw+brentq") + scaled_matrices = matrices * 1e-8 + scaled_centers = centers * 1e8 + scaled = solve_minimax(scaled_matrices, scaled_centers, method="fw+brentq") - gap = _constraint_gap(scaled, matrices * 1e-8, centers * 1e8) - assert gap <= 1e-9 * scaled.alpha - if gap > 1e-9: - assert gap > 1e-9 + gap = _constraint_gap(scaled, scaled_matrices, scaled_centers) + assert scaled.converged + assert gap <= 1e-9 * max(1.0, abs(scaled.alpha)) + + old_absolute_accuracy = solve_minimax( + scaled_matrices, + scaled_centers, + method="fw+brentq", + tol=1e-9 / scaled.alpha, + ) + assert not old_absolute_accuracy.converged # --------------------------------------------------------------------------- From a401b9c0c70b2567450aa63ef9a27827cd6449ea Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 16:34:28 +0900 Subject: [PATCH 24/29] fix: bound Cech normalization roundoff by computed terms Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/cech.py | 30 ++++++++++++++++-------------- tests/test_cech.py | 12 ++++++++++++ 2 files changed, 28 insertions(+), 14 deletions(-) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 6f37e12..eab2e65 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -177,11 +177,12 @@ def _prepare_coefs( A packed row encodes the constant as ``c = xbar.T @ A @ xbar + delta``. Computing ``delta`` from a - far-translated or ill-conditioned row can therefore lose precision of - order ``eps * cond2(A) * max(abs(c), abs(xbar.T @ A @ xbar))``. The - returned ``value_roundoff`` is the maximum of these per-row bounds; the - minimax value is a convex combination of row offsets. Callers needing - exact normalization at large translations should center their data first. + far-translated row can therefore lose precision in the centered quadratic + term and its subtraction from ``c``. The returned ``value_roundoff`` is + the maximum of per-row bounds based on those computed terms and the actual + linear solve; the minimax value is a convex combination of row offsets. + Callers needing exact normalization at large translations should center + their data first. """ matrices, linear, constants = unpack_conic(coefs) _validate_quadratic_matrices(matrices) @@ -198,11 +199,13 @@ def _prepare_coefs( centered_constant = float(vector @ inverse_times_linear) delta = float(constant) - centered_constant - row_roundoff = ( - _NEGATIVE_ALPHA_ROUNDING_FACTOR - * _MACHINE_EPSILON - * float(np.linalg.cond(matrix, 2)) - * max(abs(float(constant)), abs(centered_constant)) + solve_scale = float( + np.linalg.norm(vector, ord=2) * np.linalg.norm(inverse_times_linear, ord=2) + ) + row_roundoff = _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * float( + np.linalg.cond(matrix, 2) + ) * solve_scale + _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * ( + abs(float(constant)) + abs(centered_constant) ) if not np.isfinite(delta) or not np.isfinite(row_roundoff): raise ValueError( @@ -390,10 +393,9 @@ def cech_grad( A packed row encodes ``c_i = xbar_i^T A_i xbar_i + delta_i``. For ``|xbar_i|**2 >> 1`` or ill-conditioned ``A_i``, the representable - ``delta_i`` carries roundoff of order - ``eps * cond2(A_i) * max(|c_i|, |xbar_i^T A_i xbar_i|)``. Callers - needing exact normalization at large translations should center their data - first. + ``delta_i`` carries roundoff from the computed centered quadratic term and + its subtraction from ``c_i``. Callers needing exact normalization at large + translations should center their data first. This is a gradient of ``t``, not ``t**2``. Its hypotheses are a non-degenerate input, at least two indices in ``active_set``, multipliers diff --git a/tests/test_cech.py b/tests/test_cech.py index c13c122..8bc1e16 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -260,6 +260,18 @@ def test_negative_scale_roundoff_bound_does_not_grow_with_simplex_size(): ellphi.cech(coefs) +def test_exact_zero_linear_term_does_not_get_condition_roundoff_allowance(): + matrices = np.array([[[1e-16, 0.0], [0.0, 1.0]]]) + linear = np.zeros((1, 2)) + constants = np.array([-0.5]) + coefs = pack_conic(matrices, linear, constants) + + with pytest.raises( + ValueError, match="packed quadrics have no common non-negative filtration scale" + ): + ellphi.cech(coefs) + + @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @pytest.mark.parametrize( "matrix", From e5a5e9148be9854c153a3a5e6b7dd63ffc12020e Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 16:59:45 +0900 Subject: [PATCH 25/29] fix: scale regularized FW gap by actual dual value Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/_minimax_python.py | 69 +++++++++++++++++++++++++++++------ tests/test_minimax.py | 18 +++++++++ 2 files changed, 76 insertions(+), 11 deletions(-) diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index f45a19f..6f1a4c0 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -437,19 +437,32 @@ def _dual_gradient( return f + shift_gradient * float(np.dot(xstar, xstar)) -def _fw_gap_and_scale(mu: np.ndarray, gradient: np.ndarray) -> tuple[float, float]: +def _fw_gap_and_scale( + mu: np.ndarray, + gradient: np.ndarray, + *, + dual_value: float | None = None, +) -> tuple[float, float]: """Return the Frank-Wolfe gap and its relative dual-value scale.""" - dual_value = float(np.dot(mu, gradient)) - gap = float(np.max(gradient) - dual_value) + gradient_value = float(np.dot(mu, gradient)) + if dual_value is None: + dual_value = gradient_value + gap = float(np.max(gradient) - gradient_value) scale = ( float(max(1.0, abs(dual_value))) if np.isfinite(dual_value) else float("nan") ) return gap, scale -def _fw_gap_converged(mu: np.ndarray, gradient: np.ndarray, tol: float) -> bool: +def _fw_gap_converged( + mu: np.ndarray, + gradient: np.ndarray, + tol: float, + *, + dual_value: float | None = None, +) -> bool: """Return whether the relative Frank-Wolfe gap meets ``tol``.""" - gap, scale = _fw_gap_and_scale(mu, gradient) + gap, scale = _fw_gap_and_scale(mu, gradient, dual_value=dual_value) return bool(np.isfinite(gap) and np.isfinite(scale) and gap <= tol * scale) @@ -707,7 +720,12 @@ def _run_fw_bisect( if np.any(positive_mask): v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - if _fw_gap_converged(mu, gradient, tol): + dual_value = ( + float(np.dot(mu, f)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + ) + if _fw_gap_converged(mu, gradient, tol, dual_value=dual_value): converged = True break @@ -755,7 +773,12 @@ def _run_fw_bisect( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - converged = _fw_gap_converged(mu, gradient, tol) + dual_value = ( + float(np.dot(mu, f)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + ) + converged = _fw_gap_converged(mu, gradient, tol, dual_value=dual_value) return mu, converged, n_iter @@ -826,7 +849,12 @@ def _run_fw_brentq( if np.any(positive_mask): v = int(np.argmin(np.where(positive_mask, gradient, np.inf))) - if _fw_gap_converged(mu, gradient, tol): + dual_value = ( + float(np.dot(mu, f)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + ) + if _fw_gap_converged(mu, gradient, tol, dual_value=dual_value): converged = True break @@ -875,7 +903,12 @@ def _run_fw_brentq( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - converged = _fw_gap_converged(mu, gradient, tol) + dual_value = ( + float(np.dot(mu, f)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + ) + converged = _fw_gap_converged(mu, gradient, tol, dual_value=dual_value) metadata = { "fw_iters": n_iter, @@ -1451,7 +1484,14 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - converged = bool(res.success) and _fw_gap_converged(mu, gradient, tol) + dual_value = ( + float(np.dot(mu, f)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value(mu, matrices, Ax, centers, offsets, xstar) + ) + converged = bool(res.success) and _fw_gap_converged( + mu, gradient, tol, dual_value=dual_value + ) return mu, converged, n_eval[0] @@ -1516,7 +1556,14 @@ def _check_newton_convergence( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - if not _fw_gap_converged(mu, gradient_check, tol): + dual_value = ( + float(np.dot(mu, f_check)) + if regularization == 0.0 and condition_number_limit is None + else _regularized_dual_value( + mu, matrices, Ax, centers, offsets, xstar_check + ) + ) + if not _fw_gap_converged(mu, gradient_check, tol, dual_value=dual_value): return False if len(active_set) <= 1: return True diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 9e10bd4..30d52a2 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -561,6 +561,24 @@ def test_fw_gap_uses_conditioning_shift_gradient(self): assert n_iter == 1 assert not converged + def test_regularized_fw_gap_uses_actual_dual_value_scale(self): + scale = 1e10 + matrices = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[scale, 0.0], [scale + 2.0, 0.0]]) + offsets = np.full(2, -(scale**2 + 2.0 * scale + 3.0) / 2.0) + + result = solve_minimax( + matrices, + centers, + offsets=offsets, + method="fw+brentq", + regularization=1.0, + max_iter=1, + ) + + assert result.converged + np.testing.assert_allclose(result.weights, [0.0, 1.0]) + def test_newton_polishing_uses_stabilized_stationarity(self): matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) centers = np.array([[0.0, 0.0], [1.0, 0.0]]) From 99a0dfa4612bfb4519230d448ee3b7230f0501d2 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 17:20:55 +0900 Subject: [PATCH 26/29] fix: derive the negative-alpha allowance from the support rows only Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- src/ellphi/cech.py | 29 +++++++++++++++++------------ tests/test_cech.py | 10 ++++++++++ 2 files changed, 27 insertions(+), 12 deletions(-) diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index eab2e65..0149dd2 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -172,15 +172,15 @@ def _validate_quadratic_matrices(matrices: np.ndarray) -> None: def _prepare_coefs( coefs: np.ndarray, -) -> tuple[np.ndarray, np.ndarray, np.ndarray, float]: +) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: """Reconstruct centers and preserve exact completed-square offsets. A packed row encodes the constant as ``c = xbar.T @ A @ xbar + delta``. Computing ``delta`` from a far-translated row can therefore lose precision in the centered quadratic - term and its subtraction from ``c``. The returned ``value_roundoff`` is - the maximum of per-row bounds based on those computed terms and the actual - linear solve; the minimax value is a convex combination of row offsets. + term and its subtraction from ``c``. The returned per-row bounds are based + on those computed terms and the actual linear solve; the minimax value is a + convex combination of row offsets. Callers needing exact normalization at large translations should center their data first. """ @@ -188,7 +188,7 @@ def _prepare_coefs( _validate_quadratic_matrices(matrices) centers = np.empty_like(linear) offsets = np.empty_like(constants) - value_roundoff = 0.0 + row_roundoff_bounds = np.empty_like(constants) for row, (matrix, vector, constant) in enumerate(zip(matrices, linear, constants)): try: inverse_times_linear = np.linalg.solve(matrix, vector) @@ -213,8 +213,8 @@ def _prepare_coefs( ) centers[row] = -inverse_times_linear offsets[row] = delta - value_roundoff = max(value_roundoff, row_roundoff) - return matrices, centers, offsets, float(value_roundoff) + row_roundoff_bounds[row] = row_roundoff + return matrices, centers, offsets, row_roundoff_bounds def _centered_constraint_values( @@ -299,7 +299,7 @@ def cech( newton_tol=newton_tol, newton_max_iter=newton_max_iter, ) - matrices, centers, offsets, value_roundoff = _prepare_coefs(coefs) + matrices, centers, offsets, row_roundoff_bounds = _prepare_coefs(coefs) result = solve_minimax( matrices, @@ -342,17 +342,22 @@ def cech( "a larger max_iter or a different method may be chosen" ) alpha = float(result.alpha) - constraint_scale = float(np.max(np.abs(values))) - scale = max(abs(alpha), constraint_scale) + support_indices = np.flatnonzero(result.weights > weight_tol) + support = tuple(int(i) for i in support_indices) + support_scale = float(np.max(np.abs(values[support_indices]))) + scale = max(abs(alpha), support_scale) + # The accepted allowance is the mu-weighted sum of per-row bounds over support. + support_roundoff = float( + np.dot(result.weights[support_indices], row_roundoff_bounds[support_indices]) + ) negative_tolerance = max( _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * max(1.0, scale), - value_roundoff, + support_roundoff, ) if alpha < -negative_tolerance: raise ValueError("packed quadrics have no common non-negative filtration scale") t_squared = float(max(alpha, 0.0)) t = float(np.sqrt(max(0.0, t_squared))) - support = tuple(int(i) for i in np.flatnonzero(result.weights > weight_tol)) active_threshold = active_tol * max(1.0, t_squared) + negative_tolerance active_set = tuple( int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) diff --git a/tests/test_cech.py b/tests/test_cech.py index 8bc1e16..0eaeb79 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -260,6 +260,16 @@ def test_negative_scale_roundoff_bound_does_not_grow_with_simplex_size(): ellphi.cech(coefs) +def test_negative_scale_roundoff_bound_ignores_inactive_rows(): + matrices = np.repeat(np.eye(2)[None], 2, axis=0) + coefs = pack_conic(matrices, np.zeros((2, 2)), np.array([-0.5, -1e20])) + + with pytest.raises( + ValueError, match="packed quadrics have no common non-negative filtration scale" + ): + ellphi.cech(coefs) + + def test_exact_zero_linear_term_does_not_get_condition_roundoff_allowance(): matrices = np.array([[[1e-16, 0.0], [0.0, 1.0]]]) linear = np.zeros((1, 2)) From 536592a3d338a9888922ac6f67543b6296cce034 Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 18:21:36 +0900 Subject: [PATCH 27/29] fix: certify the roundoff estimate, unify the convergence contract, declare line-search safeguard Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- docs/guide/cech_filtration.md | 22 ++-- scripts/compare_minimax_engine.py | 90 +++++++++++---- src/ellphi/_minimax_grad_python.py | 8 +- src/ellphi/_minimax_python.py | 174 +++++++++++++++++------------ src/ellphi/cech.py | 97 ++++++++++------ tests/factories.py | 2 +- tests/test_cech.py | 142 +++++++++++++---------- tests/test_minimax.py | 37 +++++- tests/test_minimax_methods.py | 23 ++++ 9 files changed, 394 insertions(+), 201 deletions(-) diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index b12bfda..4ed5d0f 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -20,7 +20,9 @@ ordered as `(t, point, mu, dt_dcoef, support, active_set)`. - `support`: the thresholded weight support `{i : mu_i > weight_tol}`. - `active_set`: the tight-constraint set at the returned point, - `I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`. + `I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`; if `alpha` is + clipped at zero, the actual clipping shift `t^2 - alpha` is added to this + threshold. The public `cech` and `cech_grad` signatures intentionally do not expose matrix stabilization controls such as `regularization`, @@ -58,17 +60,19 @@ The private engine's internal field named `active_set` is the weight support If `unpack_conic` returns `(A_i, b_i, c_i)`, the center is `xbar_i = -A_i^{-1} b_i` and the completed-square constant is -`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this exactly -computed `delta_i` to the many-body engine, including when it is small, so +`delta_i = c_i - b_i^T A_i^{-1} b_i`. The public API passes this computed +`delta_i` to the many-body engine, including when it is small, so general independent constants are supported. A packed row encodes its constant as -`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1` or -ill-conditioned `A_i`, the representable `delta_i` carries roundoff of order -`eps * |xbar_i|^2`, with a `cond2(A_i)` factor for ill-conditioned matrices. -Callers needing exact normalization at large translations should center their -data first. Packed input requires `d >= 2`; d=1 packed conics are not -supported and raise `ValueError`. +`c_i = xbar_i^T A_i xbar_i + delta_i`. For `|xbar_i|^2 >> 1`, the computed +`delta_i` can lose precision in the centered quadratic term and its +subtraction from `c_i`. The implementation reports a per-row rounding +estimate based on the solve residual and the dot-product/subtraction +dimension; this is an estimate, not a rigorous bound. Callers needing exact +normalization at large translations should center their data first. Packed +input requires `d >= 2`; d=1 packed conics are not supported and raise +`ValueError`. The many-body engine uses the completed-square offsets above. Thus `cech_grad(coefs)` returns `dt_dcoef`, the gradient for arbitrary diff --git a/scripts/compare_minimax_engine.py b/scripts/compare_minimax_engine.py index 5c86a0c..cb2b8d0 100644 --- a/scripts/compare_minimax_engine.py +++ b/scripts/compare_minimax_engine.py @@ -17,11 +17,14 @@ compare /tmp/legacy.json /tmp/candidate.json Only cases for which the legacy engine reports ``converged=True`` are fidelity -requirements. The alpha comparison uses the declared method tolerance; FW-family -methods use the relative duality-gap contract for records with -``alpha_legacy > 1``. Records with ``alpha_legacy <= 1`` remain strict checks -against their declared tolerance. Circumcenter and weight deviations remain -reported diagnostics, and the candidate must also report convergence. +requirements. ``METHOD_TOLERANCES`` are empirical comparison thresholds, not +solver settings; each method has a rationale recorded in ``METHOD_REASONS``. +For every method, records with ``alpha_legacy <= 1`` use the strict empirical +threshold, while records with larger alpha use a scale-aware threshold based on +``max(1, abs(alpha_legacy))``. That scale keeps the comparison proportional to +the magnitude of the legacy value while avoiding a division by a small value. +Circumcenter and weight deviations remain reported diagnostics, and the +candidate must also report convergence. """ from __future__ import annotations @@ -57,15 +60,15 @@ "scipy-slsqp": 1e-6, "newton-cold": 1e-12, } -RELATIVE_GAP_METHODS = frozenset(METHODS) - {"scipy-slsqp"} METHOD_REASONS = { - method: "relative duality-gap contract, module deviation list item 11" - for method in RELATIVE_GAP_METHODS + "fw+bisect": "52-step bisection line search and relative-gap contract", + "fw+brentq": "Brent line search and relative-gap contract", + "fw+bisect+newton": "bisection warm start with Newton polishing", + "fw+brentq+newton": "Brent warm start with damped Newton polishing", + "fw+bisect+damped-newton": "bisection warm start with damped Newton polishing", + "scipy-slsqp": "dual-weight SLSQP with shared gap enforcement and polishing", + "newton-cold": "uniform-start Newton stability baseline", } -METHOD_REASONS["scipy-slsqp"] = ( - "direct SLSQP is gap-enforced and Newton-polished in this port, " - "deviation list item 10" -) def _solver(engine: str, source_root: Path | None) -> Callable[..., Any]: @@ -159,6 +162,7 @@ def generate( "k": [1, 6], "d": [1, 4], "instances_per_shape": INSTANCES_PER_SHAPE, + "comparison_thresholds": METHOD_TOLERANCES, }, "random_seed": BASE_SEED, "input_identity": { @@ -188,12 +192,58 @@ def _record_key(record: dict[str, Any]) -> tuple[int, int, int, str]: ) +def _expected_keys(payload: dict[str, Any]) -> set[tuple[int, int, int, str]]: + """Return the complete deterministic grid declared by a payload manifest.""" + try: + configuration = payload["manifest"]["configuration"] + methods = tuple(configuration["methods"]) + k_min, k_max = configuration["k"] + d_min, d_max = configuration["d"] + instances_per_shape = configuration["instances_per_shape"] + except (KeyError, TypeError, ValueError) as exc: + raise ValueError("payload manifest does not declare a complete grid") from exc + return { + (k, d, instance, method) + for k in range(k_min, k_max + 1) + for d in range(d_min, d_max + 1) + for instance in range(instances_per_shape) + for method in methods + } + + +def _records_by_key( + payload: dict[str, Any], label: str +) -> dict[tuple[int, int, int, str], dict[str, Any]]: + """Validate uniqueness and completeness before indexing records.""" + records = payload.get("records") + if not isinstance(records, list): + raise ValueError(f"{label} payload has no records list") + indexed: dict[tuple[int, int, int, str], dict[str, Any]] = {} + duplicates = [] + for record in records: + key = _record_key(record) + if key in indexed: + duplicates.append(key) + indexed[key] = record + if duplicates: + raise ValueError(f"{label} payload has duplicate record keys: {duplicates[:3]}") + expected = _expected_keys(payload) + missing = sorted(expected - indexed.keys()) + extra = sorted(indexed.keys() - expected) + if missing or extra: + raise ValueError( + f"{label} payload has incomplete grid: " + f"missing={missing[:3]}, extra={extra[:3]}" + ) + return indexed + + def compare(legacy_path: Path, candidate_path: Path) -> int: """Compare candidate outputs where the legacy engine converged.""" legacy_payload = json.loads(legacy_path.read_text()) candidate_payload = json.loads(candidate_path.read_text()) - legacy = {_record_key(record): record for record in legacy_payload["records"]} - candidate = {_record_key(record): record for record in candidate_payload["records"]} + legacy = _records_by_key(legacy_payload, "legacy") + candidate = _records_by_key(candidate_payload, "candidate") if legacy.keys() != candidate.keys(): missing = sorted(legacy.keys() - candidate.keys()) extra = sorted(candidate.keys() - legacy.keys()) @@ -277,8 +327,7 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: else: partition = stats["alpha_gt_one"] tolerance = METHOD_TOLERANCES[method] - if method in RELATIVE_GAP_METHODS: - tolerance = max(tolerance, 1e-9 * alpha_scale) + tolerance = max(tolerance, 1e-9 * alpha_scale) partition["max_relative_deviation"] = max( partition["max_relative_deviation"], deviation / alpha_scale ) @@ -297,7 +346,10 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: mismatches.append(key) summary = { - "records_compared": len(legacy), + "records_total": len(legacy), + "records_checked": converged, + "records_skipped": len(legacy) - converged, + "records_compared": converged, "legacy_converged": converged, "legacy_converged_by_method": converged_by_method, "mismatches": len(mismatches), @@ -306,12 +358,12 @@ def compare(legacy_path: Path, candidate_path: Path) -> int: "per_method": per_method, "status": ( "complete" - if not mismatches and not strict_tolerance_violations + if converged and not mismatches and not strict_tolerance_violations else "failed" ), } print(json.dumps(summary, indent=2, sort_keys=True)) - return 1 if mismatches or strict_tolerance_violations else 0 + return 1 if not converged or mismatches or strict_tolerance_violations else 0 def main() -> int: diff --git a/src/ellphi/_minimax_grad_python.py b/src/ellphi/_minimax_grad_python.py index bf5ef20..ec4f676 100644 --- a/src/ellphi/_minimax_grad_python.py +++ b/src/ellphi/_minimax_grad_python.py @@ -1,4 +1,4 @@ -"""Gradient of the many-body minimax filtration value (provisional). +"""Gradient of the many-body minimax filtration value. Provenance ---------- @@ -10,10 +10,8 @@ adopts the ebe63a4 remark that zero weights give zero gradient blocks, but not its characterization of differentiability. EllPHi adds the offset gradient ``d alpha / d delta_i = mu_i``; the original center and matrix -gradient code is unchanged. -Distributed as part of EllPHi under its MIT license; the ellcech source is -MIT by owner decision (uda-lab/project-ellphi#26, 2026-10-04), aligned with -EllPHi. +gradient code is unchanged. Distributed as part of EllPHi under its MIT +license; the ellcech source is also distributed under its MIT license. This numerical engine is internal. The public interface is :mod:`ellphi.cech`. diff --git a/src/ellphi/_minimax_python.py b/src/ellphi/_minimax_python.py index 6f1a4c0..1ec6d46 100644 --- a/src/ellphi/_minimax_python.py +++ b/src/ellphi/_minimax_python.py @@ -1,4 +1,4 @@ -"""Many-body minimax solver for anisotropic filtration values (provisional). +"""Many-body minimax solver for anisotropic filtration values. Provenance ---------- @@ -41,14 +41,19 @@ ellcech 82d13e3 preserved the prior convergence flag in this case. * Direct ``scipy-slsqp`` is gap-enforced and Newton-polished when its initial result misses the requested global gap. -* Frank-Wolfe gap convergence uses ``gap <= tol * max(1, abs(g_hat))``, where - ``gap = max_i gradient_i - g_hat`` and ``g_hat = dot(mu, gradient)``; +* The default method is ``fw+brentq+newton``; the source uses a different + default dispatch. +* Frank-Wolfe gap convergence uses ``gap <= tol * max(1, abs(dual_value))``; + ``gap = max_i gradient_i - dot(mu, gradient)`` and ``dual_value`` is the + stabilized dual value when conditioning or regularization is active; ellcech uses an absolute gap instead. +* The ``fw+brentq`` line search uses Brent with a bisection safeguard when the + bracket is rejected, and records each safeguard in its metadata. The list above exhausts numerical and solver-behavior deviations from ellcech. The remaining differences are packaging-only (the intra-package import of ``unpack_conic`` and type annotations) or documentation. Distributed as part -of EllPHi under its MIT license; the ellcech source is MIT by owner decision -(uda-lab/project-ellphi#26, 2026-10-04), aligned with EllPHi. +of EllPHi under its MIT license; the ellcech source is also distributed under +its MIT license. This numerical engine is internal. The public interface is :mod:`ellphi.cech`. @@ -162,8 +167,6 @@ # Brentq line search constants (analogous to ellphi _DEFAULT_HYBRID_BRACKET_MAXITER) _DEFAULT_BRENTQ_MAXITER = 28 -# Retained unused for fidelity with the ellcech source. -_BRENTQ_FAILSAFE_MAXITER = 64 _BRENTQ_XTOL = 1e-12 _BRENTQ_RTOL = 4.0 * np.finfo(float).eps @@ -211,7 +214,8 @@ class MinimaxResult(NamedTuple): n_iter: Number of iterations performed. method: Canonical solver method used (e.g. ``"fw+bisect"``). metadata: Optional dict with method-specific diagnostics - (``fw_iters``, ``newton_iters``, ``hessian_cond``, ...). + (``fw_iters``, ``newton_iters``, ``hessian_cond``, and line-search + safeguard counts where applicable). """ alpha: float @@ -358,11 +362,8 @@ def _cholesky_solve( condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) - try: - chol = linalg.cho_factor(A, check_finite=False) - return linalg.cho_solve(chol, b, check_finite=False) - except linalg.LinAlgError: - return np.linalg.lstsq(A, b, rcond=None)[0] + chol = linalg.cho_factor(A, check_finite=False) + return linalg.cho_solve(chol, b, check_finite=False) def _exact_linear_solve(A: np.ndarray, b: np.ndarray) -> np.ndarray: @@ -371,10 +372,7 @@ def _exact_linear_solve(A: np.ndarray, b: np.ndarray) -> np.ndarray: chol = linalg.cho_factor(A, check_finite=False) return linalg.cho_solve(chol, b, check_finite=False) except linalg.LinAlgError: - try: - return np.linalg.solve(A, b) - except np.linalg.LinAlgError: - return np.linalg.lstsq(A, b, rcond=None)[0] + return np.linalg.solve(A, b) def _eval_f( @@ -390,7 +388,8 @@ def _eval_f( ) -> tuple[np.ndarray, np.ndarray]: """Compute circumcenter x*(mu) and f_i(x*(mu)) for all i. - Also note: g(mu) = sum_i mu_i f_i(x*(mu)) = np.dot(mu, f). + For an unadjusted solve, ``g(mu) = sum_i mu_i f_i(x*(mu))``. Stabilized + solves use the regularized dual value for the scale in the gap test. """ A_mu = np.einsum("k,kij->ij", mu, matrices) b_mu = np.einsum("k,ki->i", mu, Ax) @@ -575,7 +574,7 @@ def _brentq_line_search( regularization: float, condition_number_limit: float | None, max_conditioning_steps: int, -) -> tuple[float, int]: +) -> tuple[float, int, bool]: """Brentq line search for a dual-simplex pairwise Frank-Wolfe swap. The direction is ``e_s - e_v``, with ``s`` the best vertex (largest @@ -584,10 +583,11 @@ def _brentq_line_search( ``0 <= gamma <= gamma_max <= mu[v]``. Returns: - (gamma, n_fevals): Optimal step and number of function evaluations. + (gamma, n_fevals, used_bisection): Optimal step, function evaluations, + and whether the declared bisection safeguard was used. """ if gamma_max <= 0.0: - return 0.0, 0 + return 0.0, 0, False n_fevals = [0] @@ -622,11 +622,11 @@ def h(gamma: float) -> float: h0 = h(0.0) if h0 <= 0.0: - return 0.0, n_fevals[0] + return 0.0, n_fevals[0], False h_max = h(gamma_max) if h_max >= 0.0: - return gamma_max, n_fevals[0] + return gamma_max, n_fevals[0], False try: from scipy.optimize import brentq @@ -639,9 +639,9 @@ def h(gamma: float) -> float: rtol=_BRENTQ_RTOL, maxiter=_DEFAULT_BRENTQ_MAXITER, ) - return float(gamma), n_fevals[0] + return float(gamma), n_fevals[0], False except (ValueError, RuntimeError): - # Fallback to fixed bisection + # Declared safeguard for a rejected Brent bracket. lo, hi = 0.0, gamma_max for _ in range(_N_BISECT): mid = 0.5 * (lo + hi) @@ -649,7 +649,7 @@ def h(gamma: float) -> float: lo = mid else: hi = mid - return 0.5 * (lo + hi), n_fevals[0] + return 0.5 * (lo + hi), n_fevals[0], True # --------------------------------------------------------------------------- @@ -810,6 +810,7 @@ def _run_fw_brentq( n_iter = 0 total_line_search_evals = 0 total_fevals = 0 + line_search_bisection_safeguards = 0 for n_iter in range(1, max_iter + 1): xstar, f = _eval_f( @@ -859,7 +860,7 @@ def _run_fw_brentq( break gamma_max = float(mu[v]) - gamma, ls_evals = _brentq_line_search( + gamma, ls_evals, used_bisection = _brentq_line_search( s, v, mu, @@ -873,6 +874,7 @@ def _run_fw_brentq( max_conditioning_steps=max_conditioning_steps, ) total_line_search_evals += ls_evals + line_search_bisection_safeguards += int(used_bisection) mu = mu.copy() mu[s] += gamma @@ -914,6 +916,7 @@ def _run_fw_brentq( "fw_iters": n_iter, "n_fevals": total_fevals + total_line_search_evals, "line_search_evals": total_line_search_evals, + "line_search_bisection_safeguards": line_search_bisection_safeguards, } return mu, converged, n_iter, metadata @@ -1412,7 +1415,6 @@ def _run_scipy_slsqp( offsets: np.ndarray | None, k: int, *, - initial_weights: np.ndarray | None = None, tol: float, regularization: float, condition_number_limit: float | None, @@ -1440,11 +1442,7 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: max_conditioning_steps=max_conditioning_steps, ) - x0 = ( - np.full(k, 1.0 / k) - if initial_weights is None - else np.asarray(initial_weights, dtype=float).copy() - ) + x0 = np.full(k, 1.0 / k) bounds = [(0.0, None)] * k res = minimize( @@ -1502,13 +1500,10 @@ def neg_g_and_grad(mu: npt.NDArray[np.float64]) -> tuple[float, np.ndarray]: def _check_newton_convergence( mu: np.ndarray, - active_set: list[int], matrices: np.ndarray, Ax: np.ndarray, centers: np.ndarray, offsets: np.ndarray | None, - converged: bool, - newton_tol: float, newton_status: str, *, tol: float, @@ -1516,7 +1511,12 @@ def _check_newton_convergence( condition_number_limit: float | None = None, max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, ) -> bool: - """Recheck convergence after Newton polishing.""" + """Apply the shared gap contract after Newton polishing. + + Newton's residual tolerance controls its own iterations; it is not an + additional accepted-result criterion. Fatal Newton statuses remain + non-convergent even when the final global gap can be evaluated. + """ failure_statuses = { "empty_face", "armijo_rejected", @@ -1565,15 +1565,12 @@ def _check_newton_convergence( ) if not _fw_gap_converged(mu, gradient_check, tol, dual_value=dual_value): return False - if len(active_set) <= 1: - return True - r_check = gradient_check[active_set[:-1]] - gradient_check[active_set[-1]] - return float(np.max(np.abs(r_check))) < newton_tol * 1e4 + return True except linalg.LinAlgError: return False -def solve_minimax( +def _solve_minimax( matrices: np.ndarray, centers: np.ndarray, *, @@ -1606,8 +1603,8 @@ def solve_minimax( * ``"fw+bisect+newton"``: Pairwise FW(bisect) warm-start + Newton polishing. * ``"fw+brentq+newton"``: Pairwise FW(brentq) warm-start + damped Newton polishing. * ``"fw+bisect+damped-newton"``: Pairwise FW(bisect) + Armijo-damped Newton. - * ``"scipy-slsqp"``: Direct SLSQP solve via scipy, with Newton accuracy - polishing if SLSQP's result misses the requested global gap. + * ``"scipy-slsqp"``: Direct dual-weight SLSQP solve via scipy, with Newton + accuracy polishing if SLSQP's result misses the requested global gap. * ``"newton-cold"``: Newton from uniform mu=1/k (stability baseline). The legacy name ``"fw+newton"`` is accepted as an alias for @@ -1621,11 +1618,13 @@ def solve_minimax( offsets: Optional additive constants ``delta_i``, shape ``(k,)``. ``None`` is the original zero-offset problem. method: One of the seven canonical method names above. - tol: Pairwise Frank-Wolfe gap tolerance for the FW-based methods, - relative to max(1, |dual value|). + tol: Shared accepted-result duality-gap tolerance for every method, + relative to ``max(1, abs(dual value))``; it is not Newton's + residual tolerance. max_iter: Maximum number of Frank-Wolfe iterations. - weight_tol: Threshold defining the weight support ``active_set``. It - also selects the face used by Newton polishing. + weight_tol: Threshold defining the weight support ``active_set`` and + the face selected by Newton polishing; it does not change the + global gap acceptance test. regularization: Non-negative diagonal shift applied to ``A(mu)`` in Frank-Wolfe evaluations and line searches, SLSQP evaluations, Newton polishing, and the final evaluation. @@ -1635,7 +1634,9 @@ def solve_minimax( not guaranteed after the cap. max_conditioning_steps: Maximum number of attempted conditioning escalations. - newton_tol: Residual tolerance for Newton polishing. + newton_tol: Residual tolerance for Newton's own polishing iterations, + including SLSQP's Newton polish; it does not add an acceptance + criterion after polishing. newton_max_iter: Maximum number of Newton steps. Returns: @@ -1770,16 +1771,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_newton, matrices, Ax, centers, offsets, - converged, - newton_tol, meta_newton["newton_status"], tol=tol, regularization=regularization, @@ -1809,16 +1806,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_newton, matrices, Ax, centers, offsets, - converged, - newton_tol, meta_newton["newton_status"], tol=tol, regularization=regularization, @@ -1848,16 +1841,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_fw + n_iter_newton - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_newton, matrices, Ax, centers, offsets, - converged, - newton_tol, meta_newton["newton_status"], tol=tol, regularization=regularization, @@ -1886,16 +1875,12 @@ def solve_minimax( max_conditioning_steps=max_conditioning_steps, ) n_iter = n_iter_cold - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_newton, matrices, Ax, centers, offsets, - True, - newton_tol, meta_cold["newton_status"], tol=tol, regularization=regularization, @@ -1928,22 +1913,18 @@ def solve_minimax( offsets, weight_tol=weight_tol, max_iter=newton_max_iter, - tol=tol, + tol=newton_tol, regularization=regularization, condition_number_limit=condition_number_limit, max_conditioning_steps=max_conditioning_steps, ) n_iter += n_iter_newton - active_set_newton = [i for i in range(k) if mu[i] > weight_tol] converged = _check_newton_convergence( mu, - active_set_newton, matrices, Ax, centers, offsets, - converged, - tol, meta_newton["newton_status"], tol=tol, regularization=regularization, @@ -1981,6 +1962,59 @@ def solve_minimax( ) +def solve_minimax( + matrices: np.ndarray, + centers: np.ndarray, + *, + offsets: np.ndarray | None = None, + method: MethodName | str = "fw+brentq+newton", + tol: float = _DEFAULT_TOL, + max_iter: int = _DEFAULT_MAX_ITER, + weight_tol: float = _DEFAULT_WEIGHT_TOL, + regularization: float = 0.0, + condition_number_limit: float | None = None, + max_conditioning_steps: int = _DEFAULT_MAX_COND_STEPS, + newton_tol: float = _NEWTON_TOL, + newton_max_iter: int = _NEWTON_MAX_ITER, +) -> MinimaxResult: + """Compute a minimax result, reporting factorization failure as non-convergence.""" + try: + return _solve_minimax( + matrices, + centers, + offsets=offsets, + method=method, + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + regularization=regularization, + condition_number_limit=condition_number_limit, + max_conditioning_steps=max_conditioning_steps, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, + ) + except linalg.LinAlgError: + centers_array = np.asarray(centers, dtype=float) + if centers_array.ndim == 1: + centers_array = centers_array[np.newaxis] + k, d = centers_array.shape + canonical_method = _METHOD_ALIASES.get(str(method), str(method)) + weights = np.full(k, 1.0 / k) if k else np.empty(0, dtype=float) + return MinimaxResult( + alpha=float("nan"), + circumcenter=np.full(d, np.nan), + weights=weights, + active_set=list(range(k)), + converged=False, + n_iter=0, + method=canonical_method, + metadata={"solver_status": "factorization_failed"}, + ) + + +solve_minimax.__doc__ = _solve_minimax.__doc__ + + def solve_minimax_from_coefs( coefs: np.ndarray, **kwargs: Any, diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 0149dd2..bc32770 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -41,9 +41,11 @@ class CechResult(NamedTuple): ``support`` is the thresholded weight support ``{i: mu[i] > weight_tol}``. ``active_set`` is the tight-constraint set at the returned point, - ``I = {i : t**2 - f_i(point) <= active_tol * max(1, t**2)}``. Up to - numerical tolerance, ``support`` is a subset of ``active_set``; under - strict complementarity (ND1), they coincide. In the degenerate example + ``I = {i : t**2 - f_i(point) <= active_tol * max(1, t**2)}``; when + ``alpha`` is clipped at zero, the actual shift ``t**2 - alpha`` is added + to this threshold. Up to numerical tolerance, ``support`` is a subset of + ``active_set``; under strict complementarity (ND1), they coincide. In the + degenerate example of unit balls centred at ``(0, 0)``, ``(2, 0)``, and ``(0, 2)``, support has two indices while ``active_set`` has three. @@ -141,8 +143,9 @@ def _validate_solver_parameters( raise ValueError("weight_tol must satisfy 0 <= weight_tol < 1/k") -def _validate_quadratic_matrices(matrices: np.ndarray) -> None: +def _validate_quadratic_matrices(matrices: np.ndarray) -> np.ndarray: """Validate symmetry and positive definiteness before solving centers.""" + lambda_minima = np.empty(matrices.shape[0], dtype=float) for row, matrix in enumerate(matrices): if not np.all(np.isfinite(matrix)): raise ValueError(f"coefficient row {row} has a non-finite quadratic matrix") @@ -163,58 +166,69 @@ def _validate_quadratic_matrices(matrices: np.ndarray) -> None: ) try: - np.linalg.cholesky(matrix) + eigenvalues = np.linalg.eigvalsh(matrix) except np.linalg.LinAlgError as exc: raise ValueError( f"coefficient row {row} has a non-positive definite quadratic matrix" ) from exc + lambda_min = float(eigenvalues[0]) + if not np.isfinite(lambda_min) or lambda_min <= 0.0: + raise ValueError( + f"coefficient row {row} has a non-positive definite quadratic matrix" + ) + lambda_minima[row] = lambda_min + return lambda_minima def _prepare_coefs( coefs: np.ndarray, ) -> tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]: - """Reconstruct centers and preserve exact completed-square offsets. + """Reconstruct centers and estimate completed-square roundoff. A packed row encodes the constant as ``c = xbar.T @ A @ xbar + delta``. Computing ``delta`` from a far-translated row can therefore lose precision in the centered quadratic - term and its subtraction from ``c``. The returned per-row bounds are based - on those computed terms and the actual linear solve; the minimax value is a - convex combination of row offsets. + term and its subtraction from ``c``. The returned per-row rounding + estimates use the computed solve residual and the dot-product/subtraction + dimension; the minimax value is a convex combination of row offsets. Callers needing exact normalization at large translations should center their data first. """ matrices, linear, constants = unpack_conic(coefs) - _validate_quadratic_matrices(matrices) + lambda_minima = _validate_quadratic_matrices(matrices) centers = np.empty_like(linear) offsets = np.empty_like(constants) - row_roundoff_bounds = np.empty_like(constants) + row_roundoff_estimates = np.empty_like(constants) for row, (matrix, vector, constant) in enumerate(zip(matrices, linear, constants)): try: - inverse_times_linear = np.linalg.solve(matrix, vector) + y_hat = np.linalg.solve(matrix, vector) except np.linalg.LinAlgError as exc: raise ValueError( f"coefficient row {row} has a singular quadratic matrix" ) from exc - centered_constant = float(vector @ inverse_times_linear) + residual = vector - matrix @ y_hat + centered_constant = float(vector @ y_hat) delta = float(constant) - centered_constant - solve_scale = float( - np.linalg.norm(vector, ord=2) * np.linalg.norm(inverse_times_linear, ord=2) + solve_estimate = float( + np.linalg.norm(vector, ord=2) + * np.linalg.norm(residual, ord=2) + / lambda_minima[row] ) - row_roundoff = _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * float( - np.linalg.cond(matrix, 2) - ) * solve_scale + _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * ( - abs(float(constant)) + abs(centered_constant) + rounding_estimate = ( + (matrix.shape[0] + 2) + * _MACHINE_EPSILON + * (abs(float(constant)) + abs(centered_constant)) ) + row_roundoff = solve_estimate + rounding_estimate if not np.isfinite(delta) or not np.isfinite(row_roundoff): raise ValueError( f"coefficient row {row} has a non-finite normalization residual" ) - centers[row] = -inverse_times_linear + centers[row] = -y_hat offsets[row] = delta - row_roundoff_bounds[row] = row_roundoff - return matrices, centers, offsets, row_roundoff_bounds + row_roundoff_estimates[row] = row_roundoff + return matrices, centers, offsets, row_roundoff_estimates def _centered_constraint_values( @@ -256,10 +270,13 @@ def cech( tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual value|). max_iter: Maximum Frank-Wolfe iterations. - weight_tol: Threshold defining ``support``. - active_tol: Relative tolerance defining ``active_set`` as the - tight-constraint set at the returned point. - newton_tol: Newton-polishing residual tolerance. + weight_tol: Threshold defining the public ``support``; it does not + remove positive-weight rows from the normalization estimate. + active_tol: Relative tolerance for the public ``active_set`` tightness + test, with only the actual zero-clipping shift added when clipping + occurs. + newton_tol: Residual tolerance for Newton's own polishing iterations; + it does not alter the shared accepted-result gap test. newton_max_iter: Maximum Newton-polishing iterations. Stabilized solves are available only through the private minimax engine; @@ -299,7 +316,7 @@ def cech( newton_tol=newton_tol, newton_max_iter=newton_max_iter, ) - matrices, centers, offsets, row_roundoff_bounds = _prepare_coefs(coefs) + matrices, centers, offsets, row_roundoff_estimates = _prepare_coefs(coefs) result = solve_minimax( matrices, @@ -346,19 +363,25 @@ def cech( support = tuple(int(i) for i in support_indices) support_scale = float(np.max(np.abs(values[support_indices]))) scale = max(abs(alpha), support_scale) - # The accepted allowance is the mu-weighted sum of per-row bounds over support. - support_roundoff = float( - np.dot(result.weights[support_indices], row_roundoff_bounds[support_indices]) + positive_indices = np.flatnonzero(result.weights > 0.0) + # The accepted allowance is weighted over every row with a positive multiplier; + # the public support remains thresholded by weight_tol. + roundoff_estimate = float( + np.dot( + result.weights[positive_indices], + row_roundoff_estimates[positive_indices], + ) ) negative_tolerance = max( _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * max(1.0, scale), - support_roundoff, + roundoff_estimate, ) if alpha < -negative_tolerance: raise ValueError("packed quadrics have no common non-negative filtration scale") t_squared = float(max(alpha, 0.0)) t = float(np.sqrt(max(0.0, t_squared))) - active_threshold = active_tol * max(1.0, t_squared) + negative_tolerance + clipping_shift = t_squared - alpha + active_threshold = active_tol * max(1.0, t_squared) + clipping_shift active_set = tuple( int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) ) @@ -417,9 +440,13 @@ def cech_grad( tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual value|). max_iter: Maximum Frank-Wolfe iterations. - weight_tol: Threshold defining ``support``. - active_tol: Relative tolerance defining ``active_set``. - newton_tol: Newton-polishing residual tolerance. + weight_tol: Threshold defining the public ``support``; it does not + remove positive-weight rows from the normalization estimate. + active_tol: Relative tolerance for the public ``active_set`` tightness + test, with only the actual zero-clipping shift added when clipping + occurs. + newton_tol: Residual tolerance for Newton's own polishing iterations; + it does not alter the shared accepted-result gap test. newton_max_iter: Maximum Newton-polishing iterations. Returns: diff --git a/tests/factories.py b/tests/factories.py index 941667e..ac4d9ff 100644 --- a/tests/factories.py +++ b/tests/factories.py @@ -88,7 +88,7 @@ def minimax_public_surrogate() -> tuple[np.ndarray, np.ndarray]: all-index Frank-Wolfe gap must become much smaller than that slack, so the near-tight zero-weight vertex 4 keeps re-entering as the pairwise swap target and the all-index gap stalls. Newton polishing on the resulting - face is rank-deficient, whereas primal SLSQP is unaffected. + face is rank-deficient, whereas the dual-weight SLSQP solver is unaffected. """ matrices = np.array( [ diff --git a/tests/test_cech.py b/tests/test_cech.py index 0eaeb79..8e7da01 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -3,6 +3,7 @@ from __future__ import annotations import importlib +import re from typing import get_args import numpy as np @@ -33,20 +34,6 @@ def _relative_error(actual: np.ndarray | float, expected: np.ndarray | float) -> return numerator / denominator -def _value_roundoff_bound(coefs: np.ndarray) -> float: - matrices, linear, constants = unpack_conic(coefs) - return max( - 64.0 - * np.finfo(float).eps - * np.linalg.cond(matrix, 2) - * max( - abs(float(constant)), - abs(float(vector @ np.linalg.solve(matrix, vector))), - ) - for matrix, vector, constant in zip(matrices, linear, constants) - ) - - def test_pairwise_cech_agrees_with_tangency(solver_backend, rng): p, q = random_coef_pair(rng, dim=3) result = ellphi.cech(np.stack((p, q))) @@ -87,16 +74,10 @@ def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backen np.array([[0.0, 0.0], [2.0, 0.0]]), np.repeat(np.eye(2)[None], 2, axis=0) ) - # Packed inputs carry roundoff of order eps*|xbar|**2; this is a + # Packed inputs carry translation-sensitive roundoff; this is a # representation limit, not a solver property. - matrices, _, constants = unpack_conic(coefs) - translation_bound = max( - 64.0 - * np.finfo(float).eps - * np.linalg.cond(matrix, 2) - * max(1.0, abs(float(constant))) - for matrix, constant in zip(matrices, constants) - ) + _, _, _, translation_estimates = cech_module._prepare_coefs(coefs) + translation_estimate = float(np.max(translation_estimates)) result = ellphi.cech(coefs) pairwise = ellphi.tangency( pairwise_coefs[0], pairwise_coefs[1], backend=solver_backend @@ -116,7 +97,7 @@ def test_translated_pair_uses_engine_value_and_centred_constraints(solver_backen ) pairwise_identity = 0.5 * basis / (2.0 * pairwise.t) - assert abs(result.t**2 - pairwise.t**2) <= translation_bound + assert abs(result.t**2 - pairwise.t**2) <= translation_estimate assert result.active_set == (0, 1) assert np.all(np.isfinite(gradient.dt_dcoef)) assert _relative_error(gradient.dt_dcoef[0], pairwise_identity) < 1e-6 @@ -127,11 +108,9 @@ def test_translated_singleton_roundoff_negative_scale_is_clipped(): center = np.array([[1e6, -1e6]]) covariance = np.array([[1.0, 0.2], [0.2, 1.7]]) coefs = coef_from_cov(center, covariance[None]) - value_roundoff = _value_roundoff_bound(coefs) - result = ellphi.cech(coefs) - assert abs(result.t) <= np.sqrt(value_roundoff) + assert result.t == 0.0 def test_clipped_negative_scale_preserves_singleton_active_set(): @@ -149,11 +128,9 @@ def test_translated_coincident_roundoff_negative_scale_is_clipped(): center = np.array([[1e6, -1e6]]) covariance = np.array([[1.0, 0.2], [0.2, 1.7]]) coefs = np.repeat(coef_from_cov(center, covariance[None]), 2, axis=0) - value_roundoff = _value_roundoff_bound(coefs) - result = ellphi.cech(coefs) - assert abs(result.t) <= np.sqrt(value_roundoff) + assert result.t == 0.0 @pytest.mark.parametrize("dimension", [2, 3, 4]) @@ -167,16 +144,10 @@ def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_num coefs = coef_from_cov(center, covariance[None]) matrices, linear, constants = unpack_conic(coefs) - precision_bound = ( - 64.0 - * np.finfo(float).eps - * np.linalg.cond(matrices[0], 2) - * max(1.0, abs(float(constants[0]))) - ) if condition_number <= 1e6: result = ellphi.cech(coefs) - assert result.t**2 <= precision_bound + assert np.isfinite(result.t) point = result.point else: inverse_times_linear = np.linalg.solve(matrices[0], linear[0]) @@ -185,7 +156,7 @@ def test_coef_from_cov_accepts_rotated_spd_conditioning(dimension, condition_num result = solve_minimax( matrices, centers, offsets=np.array([constants[0] - centered_constant]) ) - assert abs(result.alpha) <= precision_bound + assert np.isfinite(result.alpha) point = result.circumcenter assert np.all(np.isfinite(point)) @@ -248,7 +219,7 @@ def test_negative_packed_scale_raises(): ellphi.cech(coefs) -def test_negative_scale_roundoff_bound_does_not_grow_with_simplex_size(): +def test_negative_scale_rounding_estimate_does_not_grow_with_simplex_size(): k = 100 centers = np.repeat(np.array([[1e6, 0.0]]), k, axis=0) coefs = coef_from_cov(centers, np.repeat(np.eye(2)[None], k, axis=0)) @@ -260,26 +231,65 @@ def test_negative_scale_roundoff_bound_does_not_grow_with_simplex_size(): ellphi.cech(coefs) -def test_negative_scale_roundoff_bound_ignores_inactive_rows(): +def test_subthreshold_positive_weight_contributes_rounding_estimate(): matrices = np.repeat(np.eye(2)[None], 2, axis=0) - coefs = pack_conic(matrices, np.zeros((2, 2)), np.array([-0.5, -1e20])) + centers = np.array([[2**40, 0.0], [0.0, 0.0]]) + linear = -np.einsum("kij,kj->ki", matrices, centers) + constants = np.array([2047 * 2**60 - 3 * 2**26, -(2**60)], dtype=float) + coefs = pack_conic(matrices, linear, constants) - with pytest.raises( - ValueError, match="packed quadrics have no common non-negative filtration scale" - ): - ellphi.cech(coefs) + result = ellphi.cech( + coefs, + method="scipy-slsqp", + tol=1.0, + weight_tol=0.01, + ) + assert result.support == (1,) + assert np.isfinite(result.t) -def test_exact_zero_linear_term_does_not_get_condition_roundoff_allowance(): - matrices = np.array([[[1e-16, 0.0], [0.0, 1.0]]]) - linear = np.zeros((1, 2)) - constants = np.array([-0.5]) - coefs = pack_conic(matrices, linear, constants) - with pytest.raises( - ValueError, match="packed quadrics have no common non-negative filtration scale" - ): - ellphi.cech(coefs) +def test_active_set_uses_only_actual_clipping_shift(): + matrices = np.repeat(np.eye(2)[None], 2, axis=0) + centers = np.repeat(np.array([[1e7, 0.0]]), 2, axis=0) + linear = -np.einsum("kij,kj->ki", matrices, centers) + constants = np.einsum("ki,kij,kj->k", centers, matrices, centers) + coefs = pack_conic(matrices, linear, constants + np.array([1.0, 0.0])) + + result = ellphi.cech(coefs, method="scipy-slsqp", active_tol=0.0) + + assert result.active_set == (0,) + + +def test_rounding_estimate_includes_solve_residual(monkeypatch): + matrices = np.array([[[2.0, 0.0], [0.0, 1.0]]]) + linear = np.array([[2.0, 1.0]]) + constants = np.array([7.0]) + original_solve = np.linalg.solve + perturbation = np.array([0.125, -0.25]) + + def perturbed_solve(matrix, vector): + return original_solve(matrix, vector) + perturbation + + monkeypatch.setattr(cech_module.np.linalg, "solve", perturbed_solve) + _, _, _, estimates = cech_module._prepare_coefs( + pack_conic(matrices, linear, constants) + ) + + y_hat = original_solve(matrices[0], linear[0]) + perturbation + residual = linear[0] - matrices[0] @ y_hat + solve_estimate = ( + np.linalg.norm(linear[0]) + * np.linalg.norm(residual) + / np.linalg.eigvalsh(matrices[0])[0] + ) + centered_constant = float(linear[0] @ y_hat) + rounding_estimate = ( + (matrices.shape[1] + 2) + * np.finfo(float).eps + * (abs(constants[0]) + abs(centered_constant)) + ) + assert estimates[0] == pytest.approx(solve_estimate + rounding_estimate, rel=1e-14) @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @@ -488,13 +498,27 @@ def test_public_surrogate_default_raises_with_honest_gap(): ellphi.cech(coefs) message = str(exc_info.value) + matrices, centers, offsets, _ = cech_module._prepare_coefs(coefs) + engine_result = solve_minimax( + matrices, + centers, + offsets=offsets, + method="fw+brentq+newton", + ) + values = cech_module._centered_constraint_values( + engine_result.circumcenter, matrices, centers, offsets + ) + expected_gap = float(np.max(values) - engine_result.weights @ values) + expected_scale = max(1.0, abs(float(engine_result.weights @ values))) assert "method='fw+brentq+newton'" in message - assert "duality_gap=" in message - assert "tol=1e-09" in message - assert "duality_gap_scale=" in message + assert f"duality_gap={expected_gap:.17g}" in message + assert f"tol={1e-09:g}" in message + assert f"duality_gap_scale={expected_scale:.17g}" in message + assert re.search(r"duality_gap=-?[0-9.e+-]+", message) + assert re.search(r"duality_gap_scale=[0-9.e+-]+", message) -def test_public_surrogate_fw_brentq_converges_with_large_budget(): +def test_public_surrogate_fw_brentq_succeeds_with_large_budget(): coefs = _public_surrogate_coefs() result = ellphi.cech(coefs, method="fw+brentq", max_iter=20000) @@ -503,7 +527,7 @@ def test_public_surrogate_fw_brentq_converges_with_large_budget(): assert result.support == (1, 3, 5) -def test_public_surrogate_slsqp_converges_at_default_budget(): +def test_public_surrogate_slsqp_succeeds_at_default_budget(): coefs = _public_surrogate_coefs() result = ellphi.cech(coefs, method="scipy-slsqp") diff --git a/tests/test_minimax.py b/tests/test_minimax.py index 30d52a2..dc2c29f 100644 --- a/tests/test_minimax.py +++ b/tests/test_minimax.py @@ -686,13 +686,10 @@ def test_newton_rechecks_global_gap_beyond_weight_face(self): converged = minimax_mod._check_newton_convergence( weights, - [0, 1], matrices, Ax, centers, None, - True, - 1e-14, "converged", tol=1e-3, regularization=0.0, @@ -702,6 +699,40 @@ def test_newton_rechecks_global_gap_beyond_weight_face(self): assert converged is False + def test_newton_acceptance_uses_relative_gap_without_extra_residual_factor(self): + matrices = np.repeat(np.eye(1)[np.newaxis], 2, axis=0) + centers = np.array([[0.0], [1.0]]) + Ax = np.einsum("kij,kj->ki", matrices, centers) + weights = np.array([0.999, 0.001]) + + converged = minimax_mod._check_newton_convergence( + weights, + matrices, + Ax, + centers, + np.array([1.0, 0.0]), + "converged", + tol=0.01, + regularization=0.0, + condition_number_limit=None, + max_conditioning_steps=8, + ) + + assert converged is True + + def test_factorization_failure_is_reported_as_nonconvergence(self, monkeypatch): + matrices = np.repeat(np.eye(2)[np.newaxis], 2, axis=0) + centers = np.array([[0.0, 0.0], [1.0, 0.0]]) + + def fail_factorization(*args, **kwargs): + raise np.linalg.LinAlgError("test factorization failure") + + monkeypatch.setattr(minimax_mod.linalg, "cho_factor", fail_factorization) + result = solve_minimax(matrices, centers, method="fw+bisect") + + assert not result.converged + assert result.metadata == {"solver_status": "factorization_failed"} + def test_hybrid_rechecks_fw_optimum_hit_on_last_iteration(self): matrices = np.array([np.eye(2), 4.0 * np.eye(2)]) centers = np.array([[0.0, 0.0], [1.0, 0.0]]) diff --git a/tests/test_minimax_methods.py b/tests/test_minimax_methods.py index 90a8399..88761c3 100644 --- a/tests/test_minimax_methods.py +++ b/tests/test_minimax_methods.py @@ -15,6 +15,7 @@ import numpy as np import pytest +import scipy.optimize from ellphi._minimax_python import MethodName, MinimaxResult, solve_minimax @@ -259,6 +260,25 @@ def test_metadata_has_line_search_evals(self): assert "line_search_evals" in res.metadata assert res.metadata["line_search_evals"] > 0 + def test_brentq_bisection_safeguard_is_recorded(self, monkeypatch): + matrices = np.repeat(np.eye(2)[np.newaxis], 3, axis=0) + centers = np.array([[2.0, 0.0], [0.0, 2.0], [0.0, 0.0]]) + + def reject_brentq(*args, **kwargs): + raise ValueError("test bracket rejection") + + monkeypatch.setattr(scipy.optimize, "brentq", reject_brentq) + result = solve_minimax( + matrices, + centers, + method="fw+brentq", + max_iter=2, + tol=1e-30, + ) + + assert result.metadata is not None + assert result.metadata["line_search_bisection_safeguards"] > 0 + def test_relative_gap_is_scale_invariant(self): matrices, centers = _random_simplex(4, 2, seed=0) scaled_matrices = matrices * 1e-8 @@ -331,6 +351,7 @@ def test_pairwise_converges(self, seed): matrices, centers = _random_simplex(2, 2, seed=seed) res = solve_minimax(matrices, centers, method="newton-cold") ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-12) + assert res.converged assert res.alpha == pytest.approx( ref.alpha, rel=1e-4 ), f"seed={seed}: cold={res.alpha}, ref={ref.alpha}" @@ -369,6 +390,7 @@ def test_converges(self, seed): matrices, centers = _random_simplex(4, 3, seed=seed) res = solve_minimax(matrices, centers, method="fw+bisect+damped-newton") ref = solve_minimax(matrices, centers, method="fw+bisect", tol=1e-12) + assert res.converged assert res.alpha == pytest.approx(ref.alpha, rel=1e-7) def test_metadata_has_hessian_cond(self): @@ -470,6 +492,7 @@ def test_success_flag_does_not_override_requested_gap(self): centers, method="scipy-slsqp", tol=1e-20, + newton_tol=1e-20, ) assert result.converged From ff87d40b0375a27570c9507745b71e155c6d4afd Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 18:40:29 +0900 Subject: [PATCH 28/29] feat: traceable composite default route (auto) with per-stage diagnostics Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4oM --- AGENTS.md | 4 + docs/guide/cech_filtration.md | 37 +++- src/ellphi/__init__.py | 4 + src/ellphi/__init__.pyi | 4 + src/ellphi/cech.py | 402 ++++++++++++++++++++++++++-------- src/ellphi/cech.pyi | 39 +++- stubtest-allowlist.txt | 1 + tests/test_cech.py | 83 +++++-- 8 files changed, 449 insertions(+), 125 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 7f5e53c..1bebf58 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -94,6 +94,10 @@ This section documents the reasons for each entry in the `stubtest-allowlist.txt **Reason:** The stub declares the same seven-value `typing.Literal` alias as the implementation, but stubtest cannot verify multi-value `Literal` aliases: it expands the stub alias into a union of single-value literals and reports the runtime alias as "not a Union". Simplifying the stub to `str` does not avoid the report either, so the entry keeps the precise stub type. +* `ellphi.cech.MethodName` + +**Reason:** The stub declares the precise eight-value `typing.Literal` alias, including the public `"auto"` route, but stubtest cannot verify multi-value `Literal` aliases and reports the runtime alias as "not a Union". The precise alias is retained for type checking. + #### Managing the Allowlist When adding a new entry to the `stubtest-allowlist.txt` file, you must also update the "Allowlist Justification" section in this document to include a clear and concise explanation for why the entry is needed. This ensures that the allowlist remains transparent and easy to manage. diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index 4ed5d0f..d8d5666 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -11,8 +11,9 @@ a simplex of packed ellipsoid coefficient vectors. For is the least squared scale at which all bodies share a common point. The result fields are ordered as -`(t, point, mu, support, active_set)`. The gradient result fields are -ordered as `(t, point, mu, dt_dcoef, support, active_set)`. +`(t, point, mu, support, active_set, info)`. The gradient result fields are +ordered as `(t, point, mu, dt_dcoef, support, active_set, info)`. The first +five fields of `CechResult` retain their historical positional order. - `t`: the Čech filtration time, with `t^2 = alpha(sigma)`. - `point`: the common intersection point `x*` at the critical scale. @@ -23,6 +24,10 @@ ordered as `(t, point, mu, dt_dcoef, support, active_set)`. `I = {i : t^2 - f_i(point) <= active_tol * max(1, t^2)}`; if `alpha` is clipped at zero, the actual clipping shift `t^2 - alpha` is added to this threshold. +- `info`: a `CechInfo` record containing `requested_method`, `method_used`, + `converged`, the final `gap`, the selected stage's `n_iter`, and its + `stages` tuple. Each `CechStage` records `method`, `converged`, `status`, + `gap`, and `n_iter`. The public `cech` and `cech_grad` signatures intentionally do not expose matrix stabilization controls such as `regularization`, @@ -45,15 +50,25 @@ two indices, and `active_set` has three. A solver that does not converge or produces non-finite output raises `RuntimeError` naming its method, iterations, final duality gap, `tol`, and the scale used for the relative gap test. -The default solver is `fw+brentq+newton`, pairwise Frank-Wolfe on the dual -simplex with an adaptive Brent line search followed by Newton polishing. Each -Frank-Wolfe step selects the best vertex (largest constraint value) and the -worst active vertex (smallest constraint value), then swaps mass along -`e_s - e_v` with step at most `mu[v]`. Its gap tolerance is relative to -`max(1, |dual value|)`. On the bundled surrogate, the near-tight zero-weight -vertex 4 keeps re-entering as the swap target, so the all-index gap can stall; -the default `fw+brentq+newton` therefore remains non-convergent within the -default budget. Callers may choose a larger `max_iter` or a different `method`. +## Default route + +The default `method="auto"` is a declared two-stage route. Stage 1 runs +`fw+brentq+newton` with the caller's `tol`, `max_iter`, and `newton_tol`. If it +does not converge, stage 2 runs the gap-enforced dual-weight solver +`scipy-slsqp` from uniform weights with the same `tol`. `info.stages` records +both stages when the fallback is used, including the first stage's status and +final gap. The selected stage is reported by `info.method_used`, and the +requested route remains visible in `info.requested_method`. + +The route never reports a non-converged result as success. If both stages fail, +`cech` raises `RuntimeError` with each stage's status, final gap, and iteration +or evaluation count. A named method runs only that method and raises on +failure; named methods never fall back. + +Each Frank-Wolfe step in stage 1 selects the best vertex (largest constraint +value) and the worst active vertex (smallest constraint value), then swaps mass +along `e_s - e_v` with step at most `mu[v]`. Its gap tolerance is relative to +`max(1, |dual value|)`. The private engine's internal field named `active_set` is the weight support (historical ellcech naming) and is not part of the public API. diff --git a/src/ellphi/__init__.py b/src/ellphi/__init__.py index 76b6b97..9bc822a 100644 --- a/src/ellphi/__init__.py +++ b/src/ellphi/__init__.py @@ -49,7 +49,9 @@ # anisotropic Čech filtration from .cech import ( + CechInfo, CechResult, + CechStage, CechGrad, cech, cech_grad, @@ -86,6 +88,8 @@ "pdist_tangency_grad", "coef_from_cov_grad", # anisotropic Čech filtration + "CechStage", + "CechInfo", "CechResult", "CechGrad", "cech", diff --git a/src/ellphi/__init__.pyi b/src/ellphi/__init__.pyi index f3d0e65..1868a11 100644 --- a/src/ellphi/__init__.pyi +++ b/src/ellphi/__init__.pyi @@ -33,8 +33,10 @@ from .grad import ( coef_from_cov_grad as coef_from_cov_grad, ) from .cech import ( + CechInfo as CechInfo, CechGrad as CechGrad, CechResult as CechResult, + CechStage as CechStage, cech as cech, cech_grad as cech_grad, ) @@ -67,6 +69,8 @@ __all__ = [ "coef_from_cov_grad", "CechResult", "CechGrad", + "CechStage", + "CechInfo", "cech", "cech_grad", "FloatArray", diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index bc32770..2874e75 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -8,14 +8,18 @@ from __future__ import annotations -from typing import NamedTuple +from typing import Literal, NamedTuple, cast import numpy as np -from ._minimax_python import MethodName, solve_minimax +from ._minimax_python import MethodName as EngineMethodName +from ._minimax_python import MinimaxResult, solve_minimax from .geometry import unpack_conic __all__ = [ + "MethodName", + "CechStage", + "CechInfo", "CechResult", "CechGrad", "cech", @@ -23,10 +27,59 @@ ] +MethodName = Literal[ + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", + "auto", +] + +_NAMED_METHODS = ( + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", + "fw+newton", +) + + _NEGATIVE_ALPHA_ROUNDING_FACTOR = 64.0 _MACHINE_EPSILON = np.finfo(float).eps +class CechStage(NamedTuple): + """Diagnostics for one public Čech solver stage.""" + + method: str + converged: bool + status: str + gap: float + n_iter: int + + +class CechInfo(NamedTuple): + """Traceability information for a public Čech solve. + + ``n_iter`` is the iteration or evaluation count reported by the selected + stage. The counts and outcomes for every attempted stage are in + ``stages``. + """ + + requested_method: str + method_used: str + converged: bool + gap: float + n_iter: int + stages: tuple[CechStage, ...] + + class CechResult(NamedTuple): """Result of an anisotropic Čech filtration calculation. @@ -60,6 +113,8 @@ class CechResult(NamedTuple): support: Indices with multiplier greater than ``weight_tol``. active_set: Tight constraints satisfying the numerical active-set test with ``active_tol``. + info: Requested method, selected method, final gap and per-stage + convergence diagnostics. """ t: float @@ -67,6 +122,7 @@ class CechResult(NamedTuple): mu: np.ndarray support: tuple[int, ...] active_set: tuple[int, ...] + info: CechInfo class CechGrad(NamedTuple): @@ -84,6 +140,8 @@ class CechGrad(NamedTuple): perturbations, shape ``(k, m)``. support: Indices with multiplier greater than ``weight_tol``. active_set: Tight constraints at ``point`` under ``active_tol``. + info: Requested method, selected method, final gap and per-stage + convergence diagnostics. """ t: float @@ -92,6 +150,7 @@ class CechGrad(NamedTuple): dt_dcoef: np.ndarray support: tuple[int, ...] active_set: tuple[int, ...] + info: CechInfo def _coefficient_basis(point: np.ndarray) -> np.ndarray: @@ -243,10 +302,211 @@ def _centered_constraint_values( return values + offsets +class _StageRun(NamedTuple): + result: MinimaxResult | None + stage: CechStage + values: np.ndarray | None + dual_value: float + gap_scale: float + error: str | None + + +def _stage_status( + result: MinimaxResult, + *, + accepted: bool, + finite: bool, + finite_values: bool, +) -> str: + """Return a stable public status for one engine result.""" + if accepted: + return "converged" + if not finite or not finite_values: + return "nonfinite" + if result.metadata is not None: + newton_status = result.metadata.get("newton_status") + if isinstance(newton_status, str) and newton_status != "converged": + return newton_status + return "gap_not_met" + + +def _run_stage( + matrices: np.ndarray, + centers: np.ndarray, + offsets: np.ndarray, + *, + method: str, + tol: float, + max_iter: int, + weight_tol: float, + newton_tol: float, + newton_max_iter: int, +) -> _StageRun: + """Run one engine stage and retain its public convergence diagnostics.""" + try: + result = solve_minimax( + matrices, + centers, + offsets=offsets, + method=cast(EngineMethodName, method), + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, + ) + except Exception as exc: + stage = CechStage( + method=method, + converged=False, + status=f"exception:{type(exc).__name__}", + gap=float("nan"), + n_iter=0, + ) + return _StageRun(None, stage, None, float("nan"), float("nan"), str(exc)) + + finite = bool( + np.isfinite(result.alpha) + and np.all(np.isfinite(result.circumcenter)) + and np.all(np.isfinite(result.weights)) + ) + values = _centered_constraint_values( + result.circumcenter, matrices, centers, offsets + ) + finite_values = bool(np.all(np.isfinite(values))) + final_gap = ( + float(np.max(values) - np.dot(result.weights, values)) + if finite and finite_values + else float("nan") + ) + dual_value = ( + float(np.dot(result.weights, values)) + if finite and finite_values + else float("nan") + ) + gap_scale = max(1.0, abs(dual_value)) if np.isfinite(dual_value) else float("nan") + accepted = bool( + result.converged + and finite + and finite_values + and np.isfinite(final_gap) + and final_gap <= tol * gap_scale + ) + status = _stage_status( + result, + accepted=accepted, + finite=finite, + finite_values=finite_values, + ) + stage = CechStage( + method=result.method, + converged=accepted, + status=status, + gap=final_gap, + n_iter=result.n_iter, + ) + return _StageRun(result, stage, values, dual_value, gap_scale, None) + + +def _stage_diagnostics(run: _StageRun) -> str: + """Format one stage for a failure message.""" + details = ( + f"method={run.stage.method!r}, status={run.stage.status!r}, " + f"final_gap={run.stage.gap:.17g}, n_iter={run.stage.n_iter}" + ) + if run.result is not None and run.result.metadata is not None: + n_fevals = run.result.metadata.get("n_fevals") + if n_fevals is not None: + details += f", n_fevals={n_fevals}" + if run.error: + details += f", cause={run.error!r}" + return details + + +def _raise_named_failure(run: _StageRun, tol: float) -> None: + """Raise the legacy-shaped diagnostic for a named method.""" + raise RuntimeError( + "cech did not converge: " + f"method={run.stage.method!r}, status={run.stage.status!r}, " + f"iterations={run.stage.n_iter}, duality_gap={run.stage.gap:.17g}, " + f"tol={tol:g}, duality_gap_scale={run.gap_scale:.17g}; " + f"{_stage_diagnostics(run)}; " + "a larger max_iter or a different method may be chosen" + ) + + +def _raise_auto_failure(runs: tuple[_StageRun, ...]) -> None: + """Raise a diagnostic retaining both failed auto-route stages.""" + details = "; ".join( + f"stage {index}: {_stage_diagnostics(run)}" + for index, run in enumerate(runs, start=1) + ) + raise RuntimeError(f"cech auto route failed: {details}") + + +def _assemble_result( + run: _StageRun, + *, + requested_method: str, + stages: tuple[CechStage, ...], + row_roundoff_estimates: np.ndarray, + weight_tol: float, + active_tol: float, +) -> CechResult: + """Build the public result from an accepted stage.""" + assert run.result is not None + assert run.values is not None + result = run.result + values = run.values + alpha = float(result.alpha) + support_indices = np.flatnonzero(result.weights > weight_tol) + support = tuple(int(i) for i in support_indices) + support_scale = float(np.max(np.abs(values[support_indices]))) + scale = max(abs(alpha), support_scale) + positive_indices = np.flatnonzero(result.weights > 0.0) + # The accepted allowance is weighted over every row with a positive multiplier; + # the public support remains thresholded by weight_tol. + roundoff_estimate = float( + np.dot( + result.weights[positive_indices], + row_roundoff_estimates[positive_indices], + ) + ) + negative_tolerance = max( + _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * max(1.0, scale), + roundoff_estimate, + ) + if alpha < -negative_tolerance: + raise ValueError("packed quadrics have no common non-negative filtration scale") + t_squared = float(max(alpha, 0.0)) + t = float(np.sqrt(max(0.0, t_squared))) + clipping_shift = t_squared - alpha + active_threshold = active_tol * max(1.0, t_squared) + clipping_shift + active_set = tuple( + int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) + ) + info = CechInfo( + requested_method=requested_method, + method_used=run.stage.method, + converged=run.stage.converged, + gap=run.stage.gap, + n_iter=run.stage.n_iter, + stages=stages, + ) + return CechResult( + t=t, + point=result.circumcenter, + mu=result.weights, + support=support, + active_set=active_set, + info=info, + ) + + def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq+newton", + method: MethodName | str = "auto", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -264,9 +524,11 @@ def cech( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default is - ``"fw+brentq+newton"``, pairwise Frank-Wolfe with adaptive Brent - line search followed by Newton polishing. + method: Internal many-body solver method. The default ``"auto"`` + first runs ``"fw+brentq+newton"`` with the caller's ``tol``, + ``max_iter``, and ``newton_tol``. If that stage does not converge, + it runs gap-enforced ``"scipy-slsqp"`` from uniform dual weights + with the same ``tol``. A named method never falls back. tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual value|). max_iter: Maximum Frank-Wolfe iterations. @@ -284,7 +546,8 @@ def cech( Returns: A result containing the Čech filtration time rather than the squared - filtration value. + filtration value. The trailing ``info`` field records the requested + method, selected method, final gap, count, and every attempted stage. Raises: ValueError: If the coefficient array is not two-dimensional, is empty, @@ -293,9 +556,10 @@ def cech( the packed quadrics have no common non-negative filtration scale. Packed input requires ``d >= 2``, as for :func:`ellphi.tangency`. - RuntimeError: If the internal solver does not converge or produces a - non-finite output. The error names the method, iterations, final - duality gap, and ``tol`` and gives retry guidance. + RuntimeError: If a named method does not converge or produces a + non-finite output, or if both stages of the ``"auto"`` route fail. + The error reports stage statuses, final gaps, and iteration or + evaluation counts. """ coefs = np.asarray(coefs, dtype=float) if coefs.ndim != 2: @@ -318,87 +582,45 @@ def cech( ) matrices, centers, offsets, row_roundoff_estimates = _prepare_coefs(coefs) - result = solve_minimax( - matrices, - centers, - offsets=offsets, - method=method, - tol=tol, - max_iter=max_iter, - weight_tol=weight_tol, - newton_tol=newton_tol, - newton_max_iter=newton_max_iter, - ) - finite = ( - np.isfinite(result.alpha) - and np.all(np.isfinite(result.circumcenter)) - and np.all(np.isfinite(result.weights)) - ) - values = _centered_constraint_values( - result.circumcenter, matrices, centers, offsets - ) - finite_values = np.all(np.isfinite(values)) - final_gap = ( - float(np.max(values) - np.dot(result.weights, values)) - if finite and finite_values - else float("nan") - ) - dual_value = ( - float(np.dot(result.weights, values)) - if finite and finite_values - else float("nan") + if method != "auto" and method not in _NAMED_METHODS: + raise ValueError(f"Unknown method {method!r}") + requested_method = str(method) + stage_methods = ( + ("fw+brentq+newton", "scipy-slsqp") if method == "auto" else (requested_method,) ) - gap_scale = max(1.0, abs(dual_value)) if np.isfinite(dual_value) else float("nan") - if not result.converged or not finite or not finite_values: - reason = "did not converge" if not result.converged else "was non-finite" - raise RuntimeError( - "cech " - f"{reason}: method={result.method!r}, iterations={result.n_iter}, " - f"duality_gap={final_gap:.17g}, tol={tol:g}, " - f"duality_gap_scale={gap_scale:.17g}; " - "a larger max_iter or a different method may be chosen" - ) - alpha = float(result.alpha) - support_indices = np.flatnonzero(result.weights > weight_tol) - support = tuple(int(i) for i in support_indices) - support_scale = float(np.max(np.abs(values[support_indices]))) - scale = max(abs(alpha), support_scale) - positive_indices = np.flatnonzero(result.weights > 0.0) - # The accepted allowance is weighted over every row with a positive multiplier; - # the public support remains thresholded by weight_tol. - roundoff_estimate = float( - np.dot( - result.weights[positive_indices], - row_roundoff_estimates[positive_indices], + runs: list[_StageRun] = [] + for stage_method in stage_methods: + run = _run_stage( + matrices, + centers, + offsets, + method=stage_method, + tol=tol, + max_iter=max_iter, + weight_tol=weight_tol, + newton_tol=newton_tol, + newton_max_iter=newton_max_iter, ) - ) - negative_tolerance = max( - _NEGATIVE_ALPHA_ROUNDING_FACTOR * _MACHINE_EPSILON * max(1.0, scale), - roundoff_estimate, - ) - if alpha < -negative_tolerance: - raise ValueError("packed quadrics have no common non-negative filtration scale") - t_squared = float(max(alpha, 0.0)) - t = float(np.sqrt(max(0.0, t_squared))) - clipping_shift = t_squared - alpha - active_threshold = active_tol * max(1.0, t_squared) + clipping_shift - active_set = tuple( - int(i) for i in np.flatnonzero(t_squared - values <= active_threshold) - ) - - return CechResult( - t=t, - point=result.circumcenter, - mu=result.weights, - support=support, - active_set=active_set, - ) + runs.append(run) + if run.stage.converged: + return _assemble_result( + run, + requested_method=requested_method, + stages=tuple(item.stage for item in runs), + row_roundoff_estimates=row_roundoff_estimates, + weight_tol=weight_tol, + active_tol=active_tol, + ) + if method != "auto": + _raise_named_failure(run, tol) + _raise_auto_failure(tuple(runs)) + raise AssertionError("unreachable") def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq+newton", + method: MethodName | str = "auto", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -434,9 +656,11 @@ def cech_grad( Args: coefs: Packed conic coefficient vectors, shape ``(k, m)``. - method: Internal many-body solver method. The default is - ``"fw+brentq+newton"``, pairwise Frank-Wolfe with adaptive Brent - line search followed by Newton polishing. + method: Internal many-body solver method. The default ``"auto"`` + first runs ``"fw+brentq+newton"`` with the caller's ``tol``, + ``max_iter``, and ``newton_tol``. If that stage does not converge, + it runs gap-enforced ``"scipy-slsqp"`` from uniform dual weights + with the same ``tol``. A named method never falls back. tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual value|). max_iter: Maximum Frank-Wolfe iterations. @@ -450,7 +674,8 @@ def cech_grad( newton_max_iter: Maximum Newton-polishing iterations. Returns: - Čech filtration data and ``dt_dcoef`` with shape ``(k, m)``. + Čech filtration data and ``dt_dcoef`` with shape ``(k, m)``. The + trailing ``info`` field mirrors the forward solve's diagnostics. Raises: ValueError: If a quadratic block is not symmetric positive definite. @@ -480,4 +705,5 @@ def cech_grad( dt_dcoef=dt_dcoef, support=result.support, active_set=result.active_set, + info=result.info, ) diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 249f88a..06e4a77 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -1,22 +1,50 @@ -from typing import NamedTuple +from typing import Literal, NamedTuple, TypeAlias import numpy as np -from ._minimax_python import MethodName - __all__ = [ + "MethodName", + "CechStage", + "CechInfo", "CechResult", "CechGrad", "cech", "cech_grad", ] +MethodName: TypeAlias = Literal[ + "fw+bisect", + "fw+brentq", + "fw+bisect+newton", + "fw+brentq+newton", + "fw+bisect+damped-newton", + "scipy-slsqp", + "newton-cold", + "auto", +] + +class CechStage(NamedTuple): + method: str + converged: bool + status: str + gap: float + n_iter: int + +class CechInfo(NamedTuple): + requested_method: str + method_used: str + converged: bool + gap: float + n_iter: int + stages: tuple[CechStage, ...] + class CechResult(NamedTuple): t: float point: np.ndarray mu: np.ndarray support: tuple[int, ...] active_set: tuple[int, ...] + info: CechInfo class CechGrad(NamedTuple): t: float @@ -25,11 +53,12 @@ class CechGrad(NamedTuple): dt_dcoef: np.ndarray support: tuple[int, ...] active_set: tuple[int, ...] + info: CechInfo def cech( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq+newton", + method: MethodName | str = "auto", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, @@ -43,7 +72,7 @@ def cech( def cech_grad( coefs: np.ndarray, *, - method: MethodName | str = "fw+brentq+newton", + method: MethodName | str = "auto", tol: float = 1e-9, max_iter: int = 2000, weight_tol: float = 1e-10, diff --git a/stubtest-allowlist.txt b/stubtest-allowlist.txt index a3a2b08..5fb7cfe 100644 --- a/stubtest-allowlist.txt +++ b/stubtest-allowlist.txt @@ -1,2 +1,3 @@ ellphi._solver_python.MethodName ellphi._minimax_python.MethodName +ellphi.cech.MethodName diff --git a/tests/test_cech.py b/tests/test_cech.py index 8e7da01..74944bc 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -3,7 +3,7 @@ from __future__ import annotations import importlib -import re +import time from typing import get_args import numpy as np @@ -364,6 +364,8 @@ def test_right_triangle_distinguishes_support_and_active_set(method): assert result.support == (0, 1) assert set(result.support) <= set(result.active_set) assert result.active_set == (0, 1, 2) + assert len(result.info.stages) == 1 + assert result.info.method_used == method def test_singleton_and_empty_cech_input(): @@ -491,31 +493,51 @@ def _public_surrogate_coefs(): return pack_conic(matrices, linear, constants) -def test_public_surrogate_default_raises_with_honest_gap(): +def test_auto_ordinary_simplex_uses_stage_one_only(): + coefs = _random_coefs(4, 2, seed=113) + + result = ellphi.cech(coefs, method="auto") + + assert result.info.requested_method == "auto" + assert result.info.method_used == "fw+brentq+newton" + assert result.info.converged + assert len(result.info.stages) == 1 + assert result.info.stages[0].method == "fw+brentq+newton" + assert result.info.stages[0].converged + + +def test_public_surrogate_auto_falls_back_to_slsqp(): + coefs = _public_surrogate_coefs() + started = time.perf_counter() + result = ellphi.cech(coefs, method="auto") + elapsed = time.perf_counter() - started + + assert elapsed <= 5.0, f"informational auto route wall time: {elapsed:.3f}s" + assert result.t**2 == pytest.approx(0.9024444260, abs=1e-8) + assert result.info.requested_method == "auto" + assert result.info.method_used == "scipy-slsqp" + assert result.info.converged + assert len(result.info.stages) == 2 + assert not result.info.stages[0].converged + assert result.info.stages[0].status == "armijo_rejected" + assert result.info.stages[1].converged + assert result.info.stages[1].method == "scipy-slsqp" + + +def test_auto_reports_both_failed_stages(): coefs = _public_surrogate_coefs() with pytest.raises(RuntimeError) as exc_info: - ellphi.cech(coefs) + ellphi.cech(coefs, method="auto", tol=1e-30, max_iter=1) message = str(exc_info.value) - matrices, centers, offsets, _ = cech_module._prepare_coefs(coefs) - engine_result = solve_minimax( - matrices, - centers, - offsets=offsets, - method="fw+brentq+newton", - ) - values = cech_module._centered_constraint_values( - engine_result.circumcenter, matrices, centers, offsets - ) - expected_gap = float(np.max(values) - engine_result.weights @ values) - expected_scale = max(1.0, abs(float(engine_result.weights @ values))) - assert "method='fw+brentq+newton'" in message - assert f"duality_gap={expected_gap:.17g}" in message - assert f"tol={1e-09:g}" in message - assert f"duality_gap_scale={expected_scale:.17g}" in message - assert re.search(r"duality_gap=-?[0-9.e+-]+", message) - assert re.search(r"duality_gap_scale=[0-9.e+-]+", message) + assert "stage 1" in message + assert "stage 2" in message + assert "fw+brentq+newton" in message + assert "scipy-slsqp" in message + assert "status=" in message + assert "final_gap=" in message + assert "n_iter=" in message def test_public_surrogate_fw_brentq_succeeds_with_large_budget(): @@ -525,6 +547,8 @@ def test_public_surrogate_fw_brentq_succeeds_with_large_budget(): assert result.t**2 == pytest.approx(0.9024444260, abs=1e-8) assert result.support == (1, 3, 5) + assert result.info.method_used == "fw+brentq" + assert len(result.info.stages) == 1 def test_public_surrogate_slsqp_succeeds_at_default_budget(): @@ -534,6 +558,19 @@ def test_public_surrogate_slsqp_succeeds_at_default_budget(): assert result.t**2 == pytest.approx(0.9024444260, abs=1e-8) assert result.support == (1, 3, 5) + assert result.info.method_used == "scipy-slsqp" + assert len(result.info.stages) == 1 + + +def test_named_method_does_not_fall_back_on_surrogate(): + coefs = _public_surrogate_coefs() + + with pytest.raises(RuntimeError) as exc_info: + ellphi.cech(coefs, method="fw+brentq+newton") + + message = str(exc_info.value) + assert "method='fw+brentq+newton'" in message + assert "scipy-slsqp" not in message @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @@ -575,6 +612,7 @@ def test_public_namedtuple_field_order(): "mu", "support", "active_set", + "info", ) assert ellphi.CechGrad._fields == ( "t", @@ -583,6 +621,7 @@ def test_public_namedtuple_field_order(): "dt_dcoef", "support", "active_set", + "info", ) @@ -590,6 +629,8 @@ def test_public_exports_hide_internal_engine(): expected = { "CechResult", "CechGrad", + "CechStage", + "CechInfo", "cech", "cech_grad", } From db5ea80ec3ee87e4bfa20bf9ba4adc46be9ade7a Mon Sep 17 00:00:00 2001 From: uda-lab-agent Date: Mon, 5 Oct 2026 19:09:22 +0900 Subject: [PATCH 29/29] fix: propagate solver statuses to public diagnostics; document result fields and the auto route Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01Mn94Zd2yUjWGNQX3rtd4o --- README.md | 7 +++++++ docs/guide/cech_filtration.md | 19 ++++++++++++++----- src/ellphi/cech.py | 22 ++++++++++++++++------ src/ellphi/cech.pyi | 4 ++-- tests/test_cech.py | 23 +++++++++++++++++++++++ 5 files changed, 62 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 588d95c..60eb5fe 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,13 @@ Starting from an ordinary point cloud, it estimates local covariance, inflates * - **N-Dimensional Support**: Works with n-dimensional ellipsoids, allowing for analysis in higher-dimensional spaces. - **Visualization**: Comes with helper functions to quickly visualize ellipse clouds using Matplotlib. +For simplex-level anisotropic filtrations, `ellphi.cech(coefs)` computes the +Čech time for several ellipsoids, while `ellphi.cech_grad(coefs)` also returns +the gradient with respect to the packed coefficients. The default `method="auto"` +tries the robust many-body route and records the selected method, convergence +status, gap, iteration count, and any fallback stages in the result's `info` +field. + ## Installation Install from PyPI: diff --git a/docs/guide/cech_filtration.md b/docs/guide/cech_filtration.md index d8d5666..39fe573 100644 --- a/docs/guide/cech_filtration.md +++ b/docs/guide/cech_filtration.md @@ -12,8 +12,7 @@ is the least squared scale at which all bodies share a common point. The result fields are ordered as `(t, point, mu, support, active_set, info)`. The gradient result fields are -ordered as `(t, point, mu, dt_dcoef, support, active_set, info)`. The first -five fields of `CechResult` retain their historical positional order. +ordered as `(t, point, mu, dt_dcoef, support, active_set, info)`. - `t`: the Čech filtration time, with `t^2 = alpha(sigma)`. - `point`: the common intersection point `x*` at the critical scale. @@ -46,9 +45,19 @@ computed by `tangency()`, and `cech()` agrees with it. Up to numerical tolerance, `support` is a subset of `active_set`; under strict complementarity (ND1), they coincide. For three unit balls centred at `(0, 0)`, `(2, 0)`, and `(0, 2)`, the point is `(1, 1)`, support has -two indices, and `active_set` has three. A solver that does not converge or -produces non-finite output raises `RuntimeError` naming its method, iterations, -final duality gap, `tol`, and the scale used for the relative gap test. +two indices, and `active_set` has three. + +Every solver method uses the same accepted-result gap contract: +`gap <= tol * max(1, abs(dual value))`. Thus `tol` is an all-method relative +duality-gap tolerance, not a pairwise-FW-only control or a Newton residual +tolerance. The Frank-Wolfe description below refers only to the first stage +of the default route. + +Failure diagnostics depend on the route. A named method runs one stage and +raises `RuntimeError` with that stage's method, status, iteration count, final +gap, `tol`, and relative-gap scale. The `auto` route lists both attempted +stages, including each method, status, final gap, and iteration or evaluation +count; it does not collapse them into a single named-method diagnostic. ## Default route diff --git a/src/ellphi/cech.py b/src/ellphi/cech.py index 2874e75..9eaa5e1 100644 --- a/src/ellphi/cech.py +++ b/src/ellphi/cech.py @@ -105,6 +105,8 @@ class CechResult(NamedTuple): The private engine's internal field named ``active_set`` is the weight support (historical ellcech naming) and is not part of the public API. + The fields are ordered as ``t, point, mu, support, active_set, info``. + Attributes: t: Čech filtration time; ``t**2 = alpha(sigma)``. point: Common intersection point ``x*`` at the critical scale, shape @@ -131,6 +133,9 @@ class CechGrad(NamedTuple): ``support`` and ``active_set`` have the definitions documented for :class:`CechResult`. + The fields are ordered as + ``t, point, mu, dt_dcoef, support, active_set, info``. + Attributes: t: Čech filtration time; ``t**2 = alpha(sigma)``. point: Common intersection point ``x*`` at the critical scale, shape @@ -321,12 +326,15 @@ def _stage_status( """Return a stable public status for one engine result.""" if accepted: return "converged" - if not finite or not finite_values: - return "nonfinite" if result.metadata is not None: + solver_status = result.metadata.get("solver_status") + if isinstance(solver_status, str) and solver_status != "converged": + return solver_status newton_status = result.metadata.get("newton_status") if isinstance(newton_status, str) and newton_status != "converged": return newton_status + if not finite or not finite_values: + return "nonfinite" return "gap_not_met" @@ -529,8 +537,9 @@ def cech( ``max_iter``, and ``newton_tol``. If that stage does not converge, it runs gap-enforced ``"scipy-slsqp"`` from uniform dual weights with the same ``tol``. A named method never falls back. - tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual - value|). + tol: Shared accepted-result duality-gap tolerance for every method, + relative to ``max(1, abs(dual value))``. It is not Newton's + residual tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining the public ``support``; it does not remove positive-weight rows from the normalization estimate. @@ -661,8 +670,9 @@ def cech_grad( ``max_iter``, and ``newton_tol``. If that stage does not converge, it runs gap-enforced ``"scipy-slsqp"`` from uniform dual weights with the same ``tol``. A named method never falls back. - tol: Pairwise Frank-Wolfe gap tolerance, relative to max(1, |dual - value|). + tol: Shared accepted-result duality-gap tolerance for every method, + relative to ``max(1, abs(dual value))``. It is not Newton's + residual tolerance. max_iter: Maximum Frank-Wolfe iterations. weight_tol: Threshold defining the public ``support``; it does not remove positive-weight rows from the normalization estimate. diff --git a/src/ellphi/cech.pyi b/src/ellphi/cech.pyi index 06e4a77..d808fdf 100644 --- a/src/ellphi/cech.pyi +++ b/src/ellphi/cech.pyi @@ -66,7 +66,7 @@ def cech( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechResult: - """Compute Čech time using pairwise FW swaps on the dual simplex.""" + """Compute Čech time using the selected solver method.""" ... def cech_grad( @@ -80,5 +80,5 @@ def cech_grad( newton_tol: float = 1e-14, newton_max_iter: int = 20, ) -> CechGrad: - """Compute Čech time and its gradient using pairwise FW swaps.""" + """Compute Čech time and its gradient using the selected solver method.""" ... diff --git a/tests/test_cech.py b/tests/test_cech.py index 74944bc..3e5f41e 100644 --- a/tests/test_cech.py +++ b/tests/test_cech.py @@ -10,6 +10,7 @@ import pytest import ellphi +import ellphi._minimax_python as minimax_module from ellphi._minimax_python import MethodName, solve_minimax from ellphi.geometry import coef_from_cov, pack_conic, unpack_conic @@ -395,6 +396,28 @@ def test_non_convergence_raises_with_gap_and_retry_guidance(): assert "larger max_iter or a different method" in message +@pytest.mark.parametrize("method", ["fw+bisect", "auto"]) +def test_factorization_failure_status_is_preserved_in_public_diagnostics( + monkeypatch, method +): + coefs = _random_coefs(2, 2, seed=102) + + def fail_factorization(*args, **kwargs): + raise np.linalg.LinAlgError("test factorization failure") + + monkeypatch.setattr(minimax_module.linalg, "cho_factor", fail_factorization) + + with pytest.raises(RuntimeError) as exc_info: + ellphi.cech(coefs, method=method) + + message = str(exc_info.value) + assert "factorization_failed" in message + assert "nonfinite" not in message + if method == "auto": + assert "stage 1" in message + assert "stage 2" in message + + @pytest.mark.parametrize("api", [ellphi.cech, ellphi.cech_grad]) @pytest.mark.parametrize( "name, value",