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', fit_source='auto', classic_support_policy=None, fitted_support=None, rsgdf_omega=0.4, rsgdf_g_precision=1e-10, rsgdf_ke_cutoff=None, 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, return_lattice_density=False, lattice_density_memory_bytes=134217728, check_energy_sanity=True, progress=None, verbose=None, _lpq_cache_builder=None, retain_fit_cache=False, _chi_xc=None, xc_density_domain=vibeqc._vibeqc_core.PeriodicXCDensityDomain.AUTO)

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

A bulk Γ mesh is the one-point mesh of this engine. With the default SR/LR fit it always runs the k-mesh loop here; with gdf_method 'compcell' or 'mdf' a request that vibeqc.run_pbc_gdf_rhf() implements completely is handed to that exact-Gamma driver, and any other runs the loop here at Nk=1. Only a dim < 3 Γ mesh uses vibeqc.run_rhf_periodic_gamma_gdf().

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). A grid-based XC request with explicitly supplied HF options raises TypeError; use PeriodicKSOptions() or omit options.

• 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.

• use_compcell (bool) – Has no effect on a k-mesh: every closed-shell multi-k run builds the cached fit of its gdf_method, and an explicit False is overridden with a log line (#284, #415). At a bulk Γ mesh True skips the delegation to vibeqc.run_pbc_gdf_rhf() and runs the k-mesh engine at Nk=1. k_exchange='cosx' requires True.

• k_exchange (str) –

  Exchange backend of the cached-fit multi-k 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 multi-k fit 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), the original investigation) or 'compcell' (Sun-2017 compensated charges + AFT correction; pair-resolved and summed over the auxiliary images since 2026-09-29, #172 – before that it was q-only and catastrophically wrong on tight ionic cells, the M3b-5 finding #1 / the -2495 Ha class) or 'mdf' (mixed density fitting, vibeqc.aux_basis.build_lpq_bloch_mdf()). A multi-k run always builds this cache with the requested method: a pure-DFT dim=3 run with an explicit 'compcell' or 'mdf' promotes use_compcell=False like the default 'rsgdf' does (it used to stay on the EWALD_3D J, which builds no fit, so the method was silently ignored). The RSGDF route is also the consistent partner for k_exchange='cosx' (single-gauge pairing, M3b-4c).

• fit_source (str) – 'auto' preserves existing source selection. Explicit 'classic' selects the shared-q FFT source in a canonical modrho frame and retains its factors for compatible correlation consumers. Explicit 'sr' selects the existing SR/LR source. Explicit selection requires 3D RSGDF and excludes private adapters. These are different finite fits, not alternative exact representations of one fitted operator.

• classic_support_policy (str | None) – AO-pair support of the classic fit (fit_source='classic' on a 3-D cell). None selects 'physical_pairs': every AO pair within lattice_opts.cutoff_bohr of each other, the term set of the native three-centre integrals, so a Gamma supercell and its folded k mesh build one operator. 'historical_index_ball' replays the former cells within the cutoff of the origin, which drops the pairs crossing the face of a cell whose extent approaches the cutoff (#466); the experimental CCM producers pin it so the fold they build keeps the same operator. The physical fit is unscreened, so a positive fit_screen_threshold needs the historical replay.

• rsgdf_ke_cutoff (float | None) – Base reciprocal kinetic-energy cutoff (Ha). None (default) requests nothing: the 3D SR/LR source uses the cutoff its planner resolves from the raw integral error target, and routes without a planner use the legacy 200 Ha mesh. An explicit value is a lower bound on the SR/LR planner’s cutoff and the mesh of the other routes. The executed descriptor records the resolved domain.

• rsgdf_tail_ke_cutoff (float | None) – Optional complementary reciprocal shell for the classic RSGDF source. The SR/LR source warns and clears this inactive setting. Requested and executed values remain separate in the source metadata. Explicit classic selection uses its cached fitted J for pure DFT as well as HF/hybrids and does not inherit a Gamma auto-tail. A tail is support selection, not numerical qualification.

• 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' (every multi-k run uses the cached-Lpq SCF, pure DFT included), 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()). The engine that runs the SCF computes the gradient: at a bulk Γ mesh that is this loop at Nk=1 on the default SR/LR fit, or vibeqc.run_pbc_gdf_rhf() when a compcell/mdf request is handed to that exact-Gamma driver. The legacy molecular-limit fallback fails closed. 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.

• retain_fit_cache (bool) – True keeps the classic RSGDF per-pair fit on the result (result.fit_cache, an RSGDFFitCache: every (k_i, k_j) cderi in the eigenmode frame plus the M(q) eigensystems) instead of freeing it after the SCF, so a second consumer in the same process – the real-Γ Γ-CCM producer’s fold – can reuse the fit rather than rebuild it (2026-09-24). None is recorded, with the reason logged, on the Γ fast path, the SR/LR engine and the MDF/compcell sources. Off by default: it is memory the SCF would otherwise free.

• compcell_eta (float)

• apply_aft_correction (bool)

• aft_ft_convention (str)

• aft_precision (float)

• rcut_strategy (object | None)

• rcut_precision (float)

• rsgdf_omega (float)

• rsgdf_g_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_lattice_density (bool)

• lattice_density_memory_bytes (int)

• xc_density_domain (vibeqc._vibeqc_core.PeriodicXCDensityDomain)

Return type:

PeriodicKRHFGDFResult