Cholesky honors pivot_epsilon: static perturbation of near-zero pivots

[sshin23]

Closes #127.

Mechanism

The Cholesky paths accepted any positive pivot (ajj > 0): a near-singular condensed KKT factored "successfully" with unbounded growth, info stayed 0, the MadNLP extension reported inertia (n, 0, 0), and the IPM diverged to NaN with no regularization signal — while cuDSS solved the same instances (6468/6470/6495/6515/1888/1951_rte, 9241_pegase). The decisive datapoint: :ldl on 6468_rte fed MadNLP ~750 inertia-triggered regularizations and still diverged — so cuDSS's rescue is not failing early, it is perturbation inside the factorization: pivot_epsilon, which the LDL/LU paths here already follow and Cholesky ignored.

Change

Cholesky now applies the same semantics on every route: a pivot in (0, pivot_epsilon] is statically perturbed to pivot_epsilon (bounded growth, info = 0); nonpositive or NaN still fails the front through the existing info channel; pivot_epsilon = 0 restores plain potrf acceptance exactly. Threaded through:

• the regime-A subtree kernels and regime-B front kernels (shared helpers, one classification evaluated identically by both column halves — race-free, no buffer writes),
• the regime-C / host-wide vendor-potrf route via a diagonal pre-clamp kernel,
• the fused pipeline (in-kernel panels share the front helpers; host-wide panels go through the clamped potrf; fused LDL mode unaffected — it has its own epsilon machinery).

Defaults are the existing cuDSS ones (1e-13 Float64, 1e-5 Float32), so this changes default behavior deliberately: it is the documented cuDSS-parity semantics the package mirrors, already live for LDL/LU.

Validation

• Discriminating probe: zero-pivot SPD system reports info = 2 on main, info = 0 (perturbed, finite solve) on this branch.
• New per-regime testset (test_numeric_cholesky_a.jl): perturbation on the kernel paths and the vendor-potrf path, the pivot_epsilon = 0 fallback, and negative pivots always failing — on every backend and element type.
• In flight, results will be posted on this PR: full CPU suite on a 32-core box; the acceptance e2e (SparseCondensedKKTSystem ACOPF on the failing RTE cases, L40S) — the benchmark cell re-run upgrades acceptance from one case to the 66-case condensed population (57/66 on main, cuDSS reference 64-66/66).

🤖 Generated with Claude Code

[sshin23]

Adversarial review round applied in 16e23d7. Confirmed and fixed: the potrf route (regime C / host wides / batched) missed elimination-time tiny pivots — now caught by a sqrt(epsilon) floor in the existing post-potrf diagonal check (equality-accepting, so the input clamp's exact-epsilon diagonals pass; dmin = 0 keeps today's strict positivity); the fused in-kernel wide panel was the one missed route and now applies the same semantics; exact-zero pivots perturb on every route ([0, epsilon], docs updated with the deliberate negative-pivot deviation from cuDSS's |pivot| rule); the two hot-path host syncs are removed; the three planted zero-pivot failure-reporting testsets pin pivot_epsilon = 0; the new testset gains a stored-tiny-diagonal case exercising the clamp and the floor's equality edge; the reference Cholesky documents its unperturbed ground-truth role; two bench scripts' direct kernel calls carry the new argument. Review also cleared: half-agreement/race-freedom of the two-half classification, exact epsilon-0 old-semantics on every route, type stability, clamp indexing, LDL isolation, allocation budgets, and that no other generator can trigger a perturbation. 20/20 route-by-route expectations green on CPU; full suite and the 66-case condensed L40S e2e next.

[sshin23]

Final acceptance (SparseCondensedKKTSystem ACOPF, L40S, MadNLP through the extension, defaults 1e-13/1e-5):

• Of main's 7 condensed failures, this PR flips 4 to solved with clean residuals: 6468_rte (715 it), 6470_rte (1344 it), 6515_rte (1766 it), 1951_rte (1496 it), all |cons| ~1.9e-9.
• The remaining cases are formulation limits, not solver gaps: 1888_rte and 6495_rte diverge identically on cuDSS CHOLESKY, on this PR's absolute epsilon, AND on an experimental scaled (pivot_epsilon_alg = algo1) build — i.e., no static-perturbation Cholesky of either placement handles them (consistent with arXiv:2508.16094's characterization of the regime that favors pivoting). 9241_pegase no longer NaNs but stalls at |cons| 2.4e-6 — an iterative-refinement/tolerance item, tracked separately.

So the fix solves every condensed case that is solvable on any available GPU Cholesky. The scaled-epsilon support was built and measured (branch scaled-epsilon-ab) and is NOT needed for these cases; it stays out of this PR. Full CPU suite green at this head (72034/72034, all four element types); the CUDA/docs CI legs are blocked by an occupied self-hosted runner GPU, not by the change.