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, mdf_ke_cutoff=40.0, check_energy_sanity=True, progress=None, verbose=None)[source]

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.

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.

  • 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 (forwarded to build_lpq_bloch_native()).

  • 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²) 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), HANDOVER_GDF_OUTSTANDING.md § 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).

  • 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·ΣZ², 100) Ha) or positive (unbound) energy RAISES RuntimeError instead of returning a converged garbage number (CLAUDE.md §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)

Return type:

PeriodicKRHFGDFResult