vibeqc.run_pbc_bipole_rhf

vibeqc.run_pbc_bipole_rhf(system, basis, kmesh, options=None, *, linear_dep_threshold=1e-07, canonical_orth_normalize_diag_first=True, level_shift_schedule=None, use_mom=False, use_oda=False, oda_trust_lambda_max=1.0, use_ewald_j_split=None, ewald_omega=None, ewald_precision=1e-08, v_ne_grid_options=None, use_multipole_diag=False, use_multipole_far_field=None, multipole_l_max=2, progress=None, verbose=None, initial_density=None)[source]

Multi-k closed-shell RHF via the CRYSTAL-gauge BIPOLE scaffold.

Algorithm (matches CRYSTAL BIELET):

  1. Real-space one-electron integrals S(g), T(g), V_ne(g) at opts.lattice_opts.cutoff_bohr. For 3D systems V_ne uses the same Ewald α as E_nn.

  2. Bloch-sum to S(k), Hcore(k) per k-point; canonical-orth X(k).

  3. Initial guess via opts.initial_guess (default SAD).

  4. SCF iter: a. Build F^{2e}(g). With use_ewald_j_split=True this is

    J_SR(g;ω) + J_LR(g;ω) + V_bg·S(g) - ½K_full(g). With the flag off, use the legacy direct-only build_fock_2e_real_space scaffold.

    1. Bloch-sum F^{2e}(g) → F(k); add Hcore(k).

    2. Energy: E_elec = Σ_g tr[D(g)Hcore(g)] + ½Σ_g tr[D(g)F²e(g)] in real-space block form (CRYSTAL/TOTENY convention).

    3. Optional DIIS extrapolation of F(k) via [F,DS] errors.

    4. Optional LEVSHIFT shift on F(k).

    5. Diagonalise F(k) → C(k), ε(k).

    6. Optional MOM reorder of occupied subspace.

    7. Rebuild D_real via real_space_density_from_kpoints.

    8. Optional ODA mixing on density.

  5. E_total = E_elec + E_nuc.

use_ewald_j_split defaults to None. In that mode the driver automatically uses the CRYSTAL-gauge Ewald-J split for 3D systems and keeps the old direct-only path for dim < 3 diagnostic runs. Pass False explicitly only when you want the legacy direct-only F²e scaffold for debugging.

For 3D systems the default V_ne implementation is analytic: erfc-screened nuclear attraction from libint plus a reciprocal-space AO-pair Fourier-transform sum. Passing v_ne_grid_options opts into the older grid-quadrature long-range V_ne path for diagnostics.

Parameters:

  • system (vibeqc._vibeqc_core.PeriodicSystem)

  • basis (vibeqc._vibeqc_core.BasisSet)

  • kmesh (vibeqc._vibeqc_core.BlochKMesh)

  • linear_dep_threshold (float)

  • canonical_orth_normalize_diag_first (bool)

  • level_shift_schedule (LevelShiftSchedule | None)

  • use_mom (bool)

  • use_oda (bool)

  • oda_trust_lambda_max (float)

  • use_ewald_j_split (bool | None)

  • ewald_omega (float | None)

  • ewald_precision (float)

  • v_ne_grid_options (vibeqc._vibeqc_core.GridOptions | None)

  • use_multipole_diag (bool)

  • use_multipole_far_field (bool | None)

  • multipole_l_max (int)

  • progress (bool | ProgressLogger | None)

  • verbose (int | None)

  • initial_density (Sequence[ndarray] | None)

Return type:

PBCBipoleRHFResult