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, 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, 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^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).

  • 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 reproduce the unscreened energy to well below SCF accuracy. 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.

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

  • rsgdf_tail_ke_cutoff (float | None)

  • mdf_ke_cutoff (float)

  • 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