vibeqc.run_krhf_periodic_gdf

vibeqc.run_krhf_periodic_gdf(system, basis, kmesh=(1, 1, 1), options=None, *, functional=None, aux_basis=None, aux_drop_eta=0.0, linear_dep_threshold=1e-07, gdf_linear_dep_threshold=1e-09, apply_modrho=True, fock_mixing=None, level_shift_warmup_cycles=None, use_compcell=False, compcell_eta=1.0, apply_aft_correction=True, aft_ft_convention='libint', aft_precision=1e-10, rcut_strategy='pyscf_auto', rcut_precision=1e-08, k_exchange='gdf', gdf_method='rsgdf', rsgdf_ke_cutoff=200.0, rsgdf_tail_ke_cutoff=None, fit_screen_threshold=0.0, mdf_ke_cutoff=40.0, ibz_native=False, bz_integration=None, density_mixer=None, density_mixer_depth=8, density_mixer_beta=0.5, density_mixer_kerker=False, kerker_k0=1.5, kerker_strength=1.0, kerker_cutoff_ha=120.0, dft_plus_u_sites=None, initial_density_k=None, compute_gradient=False, check_energy_sanity=True, progress=None, verbose=None, _lpq_cache_builder=None)

Run closed-shell periodic HF / KS multi-k SCF via native GDF.

For a single Γ point this delegates to vibeqc.run_rhf_periodic_gamma_gdf() (kept in lock-step with the multi-k path); for any other kmesh it runs the full multi-k loop here.

For system.dim == 2, this entry selects the dedicated signed slab-truncated fit on a full Gamma-centered (n1,n2,1) tuple mesh. That bounded route supports zero-temperature closed-shell RHF/RKS and full-range hybrids only, including compute_gradient=True (the analytic slab gradient, G-PBC-002 § 6). Custom/IBZ meshes, range separation, DFT+U, and density restart remain fail-closed; jk_method='auto' continues to select the independent direct SLAB_EWALD_2D route.

Parameters:

• system (vibeqc._vibeqc_core.PeriodicSystem) – Periodic system and AO basis.

• basis (vibeqc._vibeqc_core.BasisSet) – Periodic system and AO basis.

• kmesh (Sequence[int] | KPoints | vibeqc._vibeqc_core.BlochKMesh) –

  (n1, n2, n3) Monkhorst-Pack mesh, a KPoints instance, or a BlochKMesh. Defaults to Γ-only.

  Mesh-convention caveat: the tuple form samples the Γ-centered (Γ-inclusive) mesh — the same convention as PySCF cell.make_kpts([n1, n2, n3]) and the convention every PySCF-parity pin in the test suite uses. A KPoints built via KPoints.monkhorst_pack(system, mesh, symmetry=False) instead samples the half-step-shifted original Monkhorst-Pack mesh (no Γ point). Both are legitimate BZ quadratures, but they are different samplings: on MgO primitive FCC / STO-3G at (2,2,2) they differ by ~44 mHa (both vibe-qc and PySCF agree on the size of that shift). Pass the tuple (or a Γ-centered KPoints) when comparing against PySCF defaults or the pinned references. Symmetry-reduced (IBZ) meshes are expanded up front to their full parent BZ mesh (same shift, same dims) — correct, not cheaper; see _expand_ibz_kmesh_to_full_bz.

• options (vibeqc._vibeqc_core.PeriodicRHFOptions | vibeqc._vibeqc_core.PeriodicKSOptions | None) – PeriodicRHFOptions (HF) or PeriodicKSOptions (KS).

• functional (str | None) – libxc functional name when running KS; None means HF.

• aux_basis (str | None) – Auxiliary basis name. Defaults to default_aux_for(basis.name).

• aux_drop_eta (float) – Auxiliary primitive cull threshold passed to make_aux_basis_set().

• linear_dep_threshold (float) – Per-k overlap eigenvalue floor for canonical orthogonalisation.

• gdf_linear_dep_threshold (float) – Auxiliary metric eigenvalue floor for Lpq Cholesky-style fitting. RSGDF FFT builders interpret this as an absolute eigenvalue threshold, matching PySCF’s convention; legacy compcell/MDF/bare builders interpret it relative to their largest metric eigenvalue. Keep the default when comparing builder families unless you intentionally want builder-specific truncation behavior.

• apply_modrho (bool) – Whether the auxiliary basis is renormalised via aux_basis.modrho_renormalise() before fitting (default on; matches the Γ-only driver).

• fock_mixing (float | None) – Override the resolver-resolved CRYSTAL FMIXING fraction.

• level_shift_warmup_cycles (int | None) – Override the resolver-resolved level-shift warm-up length.

• k_exchange (str) –

  Exchange backend on the use_compcell=True path: 'gdf' (default) contracts the cached per-(k_i, k_j) Lpq tensors – O(N_k^2) pair contractions per iteration; 'cosx' (EXPERIMENTAL) builds K via the real-space multi-k COSX engine (vibeqc.periodic_cosx_k.KPointCosxK, M3b-3): one K(g) block build per iteration (mesh-size independent) + Bloch folds, and the off-diagonal Lpq tensors are skipped at setup (only the diagonal J pairs are built). The Coulomb J stays on GDF either way; the exxdiv=’ewald’ correction applies identically to both backends. Requires use_compcell=True and a multi-k mesh (the Γ-only fast path ignores it, like use_compcell).

  Since M3b-4b the COSX K is the composed SR+LR exchange – matrix-level validated at ~1e-4 against the independent RSGDF route. Pair it with gdf_method='rsgdf' for a single-gauge Fock (see below); a runtime warning documents the remaining experimental status (dense-mesh SCF convergence – M3b-4c).

• gdf_method (str) – Lpq builder for the use_compcell=True cache: 'rsgdf' (default – the (k_i,k_j)-ket-resolved all-FT Bloch-pair route, vibeqc.aux_basis.build_lpq_bloch_native_fft(); validated at µHa parity vs PySCF on LiH FCC (2,2,2), handovers/HANDOVER_GDF_OUTSTANDING.md Sec. 1) or 'compcell' (Sun-2017 compensated charges + AFT correction – q-only cderi, exact only in the vacuum-box limit; catastrophically wrong on tight ionic cells, the M3b-5 finding #1 / the -2495 Ha class – keep it off the default until the compcell builder is pair-resolved). The RSGDF route is also the consistent partner for k_exchange='cosx' (single-gauge pairing, M3b-4c).

• rsgdf_ke_cutoff (float) – Dense-FFT-mesh kinetic-energy cutoff (Ha) for gdf_method='rsgdf' (default 200).

• rsgdf_tail_ke_cutoff (float | None) – Optional high-|G| tail completion (Ha) for the rsgdf cderi: extends the fit’s 2c-metric and 3c-tensor G-sums over the exact complementary reciprocal shell, needed on dense-core cells (P01/MgO class) whose tight AO products are unresolved at any affordable base mesh; a parity-sized tail (>= _RSGDF_PARITY_TAIL_RATIO x zeta_max) lifts the +PARITY_HELD tag. rsgdf-only (any other gdf_method fails closed). Setting it on a pure-DFT dim=3 multi-k run routes the Hartree through the cached-Lpq GDF J (the same tail-consuming machinery HF/hybrids ride) instead of the default EWALD_3D J, which builds no cderi and cannot consume a tail (IID 146); None (default) keeps the EWALD_3D routing.

• fit_screen_threshold (float) – Cauchy-Schwarz pre-screen of the three-centre GDF fit on the gdf_method='rsgdf' path (default 0.0 = off, exact). AO pairs whose Schwarz bound max_P sqrt((P|P)).sqrt((muν|muν)) stays below the threshold are dropped from every per-(k_i,k_j) fit tensor; kept/dropped pair counts are logged (no silent truncation). 1e-10-class values have reproduced the unscreened energy to well below SCF accuracy on the current s/p-heavy regression set; for higher angular momentum the polynomial factor is a conservative screening estimate rather than a formally proven bound. Forwarded to vibeqc.aux_basis.build_lpq_bloch_native_fft() – every consumer of this driver (CCM run_ccm_rhf_gdf / run_ccm_rks_gdf, RIJCOSX diagonal-J, KS) inherits it.

• bz_integration (str | None) – None / "smearing" use the existing global Aufbau or Fermi-Dirac occupation path. "gilat" selects the parameter-free Gilat-Raubenheimer net at T = 0; it cannot be combined with finite-temperature smearing.

• dft_plus_u_sites (Sequence[object] | None) – Optional Dudarev +U sites. For true multi-k meshes, the driver builds the k-averaged per-spin occupation matrix and adds the resulting S(k) V_U S(k) shift to each closed-shell Fock block.

• compute_gradient (bool) – When True, compute the analytic nuclear gradient of the converged total energy and store it on result.gradient ((n_atoms, 3) Ha/bohr). G-PBC-002 Item 4: the multi-k assembly rebuilds the SCF’s exact shared-q rsgdf fit and differentiates every energy term (one-electron/W/nn, DF-J, DF-K over all q groups, exxdiv W-shift, XC Pulay for KS) – full-SCF FD gates on H2 (2,1,1) sit at 1.1e-8 (KRHF) / 4.1e-10 (KRKS lda) / 1.5e-8 (KRKS pbe0) Ha/bohr. Supported envelope: 3D cells, gdf_method='rsgdf' with the cached-Lpq SCF (use_compcell=True; HF/hybrids promote automatically), uniform full-BZ meshes, T = 0 Aufbau occupations OR finite-temperature Fermi-Dirac smearing (the gradient is then dA/dR of the reported Mermin free_energy = E - T.S at the fractional-occupation D(k)/W(k) – the occupation and mu responses vanish at self-consistency), pure and global-hybrid functionals; Schwarz-screened fits are differentiated at the SCF’s fixed pair mask, and bz_integration='smearing' is accepted (it is the same occupation path). Non-Fermi-Dirac smearing flavors, bz_integration='gilat', IBZ/custom-weight k-points, range-separated functionals, k_exchange='cosx', and DFT+U raise NotImplementedError naming the reason (_reject_unsupported_multik_gradient()). Γ-only tuple meshes delegate the gradient to vibeqc.run_pbc_gdf_rhf() on the pure Γ fast path and fail closed on the legacy molecular-limit fallback. On a dim=2 slab the dedicated route assembles the slab analytic gradient instead (G-PBC-002 § 6: bare 2D-Ewald nn + slab V_ne + S/T/W folds + signed-fit DF-J/K + BvK probe-charge W-shift, plus the XC Pulay for KS) inside the slab route’s own envelope; full-SCF FD gates on the compact H2 (2,2,1) slab fixture sit in tests/test_slab_2d_routing.py.

• check_energy_sanity (bool) – When True (default) a post-SCF guard rejects a non-physical total energy: a converged run that lands at a runaway (|E| > max(10.SZ^2, 100) Ha) or positive (unbound) energy RAISES RuntimeError instead of returning a converged garbage number (CLAUDE.md Sec.7 silent-corruption). Set False to bypass the guard for parity/debug scripts that want the raw value back; see _check_energy_sanity().

• progress (bool | ProgressLogger | None) – Live progress logging passthrough.

• verbose (int | None) – Live progress logging passthrough.

• use_compcell (bool)

• compcell_eta (float)

• apply_aft_correction (bool)

• aft_ft_convention (str)

• aft_precision (float)

• rcut_strategy (object | None)

• rcut_precision (float)

• mdf_ke_cutoff (float)

• ibz_native (bool)

• density_mixer (str | None)

• density_mixer_depth (int)

• density_mixer_beta (float)

• density_mixer_kerker (bool)

• kerker_k0 (float)

• kerker_strength (float)

• kerker_cutoff_ha (float)

• initial_density_k (Sequence[ndarray] | None)

Return type:

PeriodicKRHFGDFResult