UKS stagnation recovery

The default published EDIIS/DIIS policy can encounter a nearly flat occupied-virtual direction while the physical residual remains above its requested tolerance. UKSOptions.auto_trah_stagnation defaults to true. Setting it to false preserves the first-order policy.

Recovery activates after restart_opts.max_stall_iters consecutive eligible residuals below 1e-3 show less than a factor-two reduction relative to the first residual in that window. This is an explicit application heuristic, not a literature convergence theorem or a replacement convergence tolerance. A converged residual, disabled recovery, a changed Fock map, or an unsupported route resets the window.

Only the default published EDIIS/DIIS mode with no explicit Newton, TRAH, SOSCF or active quadratic phase is eligible. RSH, meta-GGA, VV10, DFT+U, held occupations, mixed densities, Fock mixing, and coarse Fock maps do not enter automatic recovery. The legacy recovery diagnostic is unchanged. The memory estimator accounts for the dense XC response tables that recovery may allocate.

Once entered, the existing orbital trust-region controller retains each evaluated reference until its trial is judged, even when the new residual exceeds the entry threshold. Rejected trials cannot pass terminal acceptance. Exhausted large-space secular solves are projected into the trust ball, and their model decrease is recomputed from the actual Hessian action rather than an unfulfilled shifted-system identity. These large-space steps remain approximate and do not certify positive curvature or a global minimum.

The formulation follows the orbital rotations and actual/model energy acceptance in Helmich-Paris, J. Chem. Phys. 154, 164104 (2021), DOI:10.1063/5.0040798, sections II B-D. The current implementation uses shifted PCG rather than that paper’s augmented-Hessian Davidson solver. No general stable-root guarantee is implied. Original energy, gradient and iteration limits remain authoritative.