vibeqc.run_rhf_periodic_multi_k_ewald3d

vibeqc.run_rhf_periodic_multi_k_ewald3d(system, basis, kmesh, options=None, *, omega=0.0, grid_shape=None, origin=None, spacing_bohr=0.3, linear_dep_threshold=1e-07, canonical_orth_normalize_diag_first=True, auto_optimize_truncation=True, level_shift_schedule=None, use_mom=False, use_oda=False, oda_trust_lambda_max=1.0, progress=None, initial_density_k=None, verbose=None, bz_integration=None, exchange_exxdiv=None)[source]

Multi-k closed-shell periodic RHF SCF with EWALD_3D Coulomb.

Parameters:

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

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

  • kmesh (vibeqc._vibeqc_core.BlochKMesh) – BlochKMesh (from vibeqc.monkhorst_pack()) defining the k-point sampling. kmesh.weights must sum to 1.

  • options – Optional PeriodicRHFOptions; uses defaults when None. max_iter, damping, conv_tol_energy, conv_tol_grad, and lattice_opts are honored. use_diis is currently ignored (multi-k DIIS is a follow-up).

  • omega (float) – Ewald splitting parameter.

  • grid_shape (Tuple[int, int, int] | int | None) – FFT-Poisson grid controls forwarded to the long-range J build.

  • origin (Sequence[float] | None) – FFT-Poisson grid controls forwarded to the long-range J build.

  • spacing_bohr (float) – FFT-Poisson grid controls forwarded to the long-range J build.

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

  • exchange_exxdiv (str | None) –

    Which q -> 0 gauge the exact-exchange arm uses. None (default) takes the corrected Ewald split at every mesh, a single Gamma point included (GitLab #23), falling back to the molecular-limit kernel only at a single Gamma point on a gauge the split does not exist for (2D slab, dim != 3). 'ewald' takes the corrected split everywhere and raises NotImplementedError when it is unavailable rather than falling back. 'none' takes the molecular-limit kernel and is accepted only at a single Gamma point, where that sum has exactly one term; it is the pre-#23 default there and reproduces run_rhf_periodic_gamma_ewald3d().

    The two are different finite-size conventions with the same infinite-k limit (Carrier, Rohra & Goerling, Phys. Rev. B 75, 205126 (2007), Sec. IV), so a Gamma-supercell energy band-folds onto a multi-k energy only when both sides name the same one – see docs/user_guide/periodic_methods.md and tests/test_periodic_exchange_gauge_band_folding.py.

  • progress (bool | ProgressLogger | None) – Live progress logging. True prints flushed per-stage and per-iteration lines to stdout (the tail -f workflow); False / None is silent; a ProgressLogger instance is used as-is. See vibeqc.progress.

  • canonical_orth_normalize_diag_first (bool)

  • auto_optimize_truncation (bool)

  • level_shift_schedule (LevelShiftSchedule | None)

  • use_mom (bool)

  • use_oda (bool)

  • oda_trust_lambda_max (float)

  • initial_density_k (Sequence | None)

  • verbose (int | None)

  • bz_integration (str | None)

Return type:

PeriodicRHFMultiKEwaldResult.