vibeqc.run_double_hybrid

vibeqc.run_double_hybrid(mol, basis, functional_name, *, density_fit=True, aux_basis='', density_fit_mp2=True, aux_basis_mp2='', dispersion=None, rks_options=None, output=None, citations=True, output_qvf=True, write_molden_file=True, write_xyz_file=True, write_population_file=True)[source]

Generic double-hybrid dispatcher.

Resolves functional_name to a Functional, runs a hybrid-DFT SCF step with that functional’s SCF piece, runs an MP2 correction on the converged KS orbitals with the functional’s mp2_c_os / mp2_c_ss scaling, optionally adds a dispersion correction, and returns a DoubleHybridResult carrying all pieces and the combined total energy.

functional_name must resolve to an is_double_hybrid functional (currently "b2plyp", "dsd-pbep86", or "pwpb95"); a ValueError is raised otherwise. The thin wrappers run_b2plyp(), run_dsd_pbep86(), and run_pwpb95() are the name-specific entry points most callers will use. "pwpb95" resolves to a meta-GGA functional, so its SCF step runs through the tau-dependent Kohn-Sham path; the dispatcher handles that transparently.

Parameters:

  • mol (Molecule, BasisSet) – The molecular system. Closed-shell runs RKS + RMP2; open-shell (multiplicity > 1) runs the spin-pure ROKS SCF half + a semicanonical ROHF-MP2 doubles correction.

  • basis (Molecule, BasisSet) – The molecular system. Closed-shell runs RKS + RMP2; open-shell (multiplicity > 1) runs the spin-pure ROKS SCF half + a semicanonical ROHF-MP2 doubles correction.

  • functional_name (str) – Name of a double-hybrid functional registered in vibe-qc’s Functional resolver.

  • density_fit (bool, default True) – Density-fit the RKS hybrid SCF step (J via RI-J, K via RI-K since double hybrids in this line all have a_HF > 0).

  • aux_basis (str, default "") – Aux basis for the SCF DF. Empty -> auto-resolve a JKfit aux from the orbital basis name.

  • density_fit_mp2 (bool, default True) – Use RI-MP2 (recommended) for the post-SCF correction. False falls back to canonical MP2 – only useful for parity validation against canonical-MP2 reference codes.

  • aux_basis_mp2 (str, default "") – Aux basis for the MP2 DF. Empty -> auto-resolve a per-zeta RIfit aux from the orbital basis name. Ignored when density_fit_mp2=False.

  • dispersion (str or None, default None) –

    Optional dispersion correction folded into DoubleHybridResult.e_total. Supported:

    • None – un-dispersed XC + MP2 total (the published “no-D” energy).

    • "d3bj" – Grimme-Antony-Ehrlich-Krieg 2010 D3 with Becke-Johnson damping, parameters for the functional read from the existing vibeqc.compute_d3bj() framework (prefers the optional dftd3 backend when installed, falls back to the vibe-qc native stub).

    • "d4" – Caldeweyher-Bannwarth-Grimme 2019 D4 via the optional dftd4 package; see vibeqc.compute_d4().

    The dispersion energy is stored on DoubleHybridResult.dispersion as either a DispersionResult (D3-BJ) or a D4Result (D4); both expose .energy so consumers can treat them uniformly.

  • rks_options (RKSOptions, optional) – Caller-provided options for the SCF step. The functional field is overridden with functional_name regardless; everything else is honoured. If None, a default RKSOptions is used with density_fit / aux_basis applied per the keyword arguments above.

  • output (str or PathLike, optional) – Output stem. When provided, the standalone dispatcher writes .out + .system and the same default-on molecular sidecars as run_job(): Molden orbitals, XYZ geometry, population/property JSON/TXT, citation siblings, and a QVF archive unless the corresponding opt-out keyword is false.

  • citations (bool, default True) – Emit .bibtex / .references siblings and record the assembled citation provenance in .system.

  • output_qvf (bool, default True) – Emit {output}.qvf. The archive contains the converged SCF wavefunction and SCF-density properties plus provenance naming the double-hybrid dispatcher; the MP2 correction contributes to the reported total energy but does not define a separate post-SCF density.

  • write_molden_file (bool, default True) – Opt out of the matching sidecars when output is provided.

  • write_xyz_file (bool, default True) – Opt out of the matching sidecars when output is provided.

  • write_population_file (bool, default True) – Opt out of the matching sidecars when output is provided.

Return type:

DoubleHybridResult