Handover: periodic initial-guess catch-up (v0.14)

Status record for the periodic SCF-guess catch-up worked by the periodic-SCF / EWALD-core chat. Written 2026-06-21, ahead of the v0.14 release cut. All landed work is on main; nothing is stranded on a wip branch.

What shipped (release-ready, on main)

Guess

Scope

Commits

Tests

FRAGMO (molecular)

Fragment-superposition guess: block-diagonal assembly of converged fragment densities, injected like READ

72638077

tests/test_fragmo.py (guess-independence, beats SAD iteration count on weakly-interacting dimers)

SAP (periodic)

Closed-shell Gamma + multi-k RHF/RKS. Fock-mode guess F_SAP = T + V_SAP, V_SAP = lattice-summed SAP potential via Ewald split (compute_vsap_lattice)

6763af2a 23b43547 dd59ad5c 85c3c014

tests/test_periodic_sap.py (integral + molecular parity + Gamma/multi-k same-basin); tests/test_guess.py::test_sap_periodic_gamma_reaches_same_basin_as_sad

MINAO (periodic)

Closed-shell Gamma + multi-k RHF/RKS. Density-mode guess: ANO-RCC reference density projected with lattice-summed Gamma overlaps P = S(G)^-1 S_tm(G), D = P D_ref P^T, placed on the g=0 cell

f594da1b

tests/test_periodic_minao.py (Gamma + multi-k RHF/RKS same-basin)

Guess-independence was the acceptance criterion: each guess reaches the same converged SCF energy as SAD on He/Ne insulator cells. A metallic case (Li, STO-3G) is convergence-limited for every guess (tight cell + minimal basis + smearing), which is an SCF-convergence matter, not a guess one.

CHANGELOG [Unreleased] carries one ### Added block per item; the user guide (docs/user_guide/initial_guess.md) and the AUTO policy table are in parity.

Honestly gated (raise a clean, accurate error; not half-built)

These paths do not build SAP/MINAO and say so clearly; AUTO resolves to SAD for periodic, so nothing silently mis-routes:

  • Periodic open-shell (UHF/UKS) for SAP and MINAO. There is no C++ open-shell periodic driver; open-shell periodic SCF lives in the Python Ewald/BIPOLE drivers, so wiring these is Python-driver work, not a C++ driver branch.

  • Python periodic drivers (Ewald / GDF / BIPOLE) for SAP and MINAO. The Python guess seam (_check_periodic_guess_supported) intercepts and raises.

  • PATOM / HUECKEL on any periodic system. The GuessEngine raises with a roadmap pointer.

Deferred, with design notes for whoever resumes

  • Periodic HUECKEL (the other half of the original task). A lattice GWH Fock-mode guess: H_GWH(g)_uv = (K/2) S(g)_uv (eps_u + eps_v), diagonal eps_u. It is structurally the SAP multi-k pattern (build a guess Fock lattice set, diagonalise per k via sap_initial_density_multik), so most of the plumbing is reusable. The new piece is the per-AO atomic-energy mapping eps_u (the molecular huckel_mo_coefficients is Phi-projected, not raw-AO, so it does not transfer directly; the raw-AO GWH form is the natural periodic variant).

  • Periodic PATOM. Needs a periodic JKBuilder for the in-field re-polarisation step; the heaviest of the remaining items.

  • Open-shell + Python-driver SAP/MINAO. See gating above; both are Python-driver integrations (build the guess Fock / density, inject per k-per-spin).

Tag-ready for v0.14

YES for FRAGMO + periodic SAP + periodic MINAO. Each builds green, ships its tests, and is documented. No half-finished code paths; incomplete-by-design work is gated and the gating is documented above.

Final pre-tag check that this chat could not run locally (no built tree on a shared checkout): the full periodic SCF suite under scripts/test_gate/ on a dev box, per CLAUDE.md section 14. The same-basin tests plus a green CI build-test (build + collect gate) are the evidence gathered here.