vibeqc.run_job

vibeqc.run_job(molecule, *, basis, method='auto', functional=None, output='output', optimize=False, write_molden_file=True, fmax=0.05, max_opt_steps=200, memory_override=False, num_threads=None, dispersion=None, rhf_options=None, uhf_options=None, rks_options=None, uks_options=None)[source]

Run a vibe-qc SCF job and write the standard output files.

Parameters:

  • molecule (vibeqc._vibeqc_core.Molecule) – The Molecule describing the system (bohr coordinates).

  • basis (str) – libint-recognised basis-set name.

  • method (Literal['rhf', 'rks', 'uhf', 'uks', 'auto']) – "rhf", "uhf", "rks", "uks", or "auto" (picks restricted vs unrestricted from molecule.multiplicity and switches between HF/KS based on whether functional is set).

  • functional (str | None) – XC functional for RKS / UKS (e.g. "PBE", "B3LYP"). Ignored for HF.

  • output (str | PathLike) – Path stem for the generated files. {output}.out always; also {output}.molden unless disabled; and {output}.traj when optimize=True.

  • optimize (bool) – Run a BFGS geometry optimisation first (via ASE), then the final SCF on the optimised geometry. The trajectory is written for animation (openable with ASE-aware viewers).

  • write_molden_file (bool) – Emit {output}.molden at the converged geometry. Default True.

  • fmax (float) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True.

  • max_opt_steps (int) – Optimizer tolerance (eV/Å) and iteration limit. Ignored unless optimize=True.

  • memory_override (bool) – If False (default), the driver estimates peak memory and aborts with InsufficientMemoryError when the estimate exceeds the machine’s available RAM. Set to True to proceed anyway — at the risk of swap-thrashing or a system freeze.

  • num_threads (int | None) – If set, pin the OpenMP thread count for the duration of the calculation. None (default) leaves the current setting in place — which is usually “all cores” unless the environment variable OMP_NUM_THREADS is set or vibeqc.set_num_threads() was called earlier. The actual thread count used is recorded in the output log for reproducibility.

  • dispersion (object | None) –

    Post-SCF D3(BJ) dispersion correction. Accepts:

    • None (default) — no dispersion.

    • True or "d3bj" — use D3-BJ params for the current DFT functional.

    • A functional name ("pbe", "b3lyp", …) — use its D3-BJ params (useful for method="rhf" + "hf" dispersion, or for overriding the SCF functional in the damping lookup).

    • A D3BJParams instance — used directly.

    The energy correction is written to the .out file, added to the returned object as e_dispersion / energy_total (the raw SCF .energy is preserved untouched), and, when optimize=True, added to the forces the optimiser sees. Routes through vibeqc.compute_d3bj() with backend="auto" — the reference dftd3 backend is used when installed, otherwise the D1a framework stub. See vibeqc.dispersion for details.

  • uks_options (vibeqc._vibeqc_core.UKSOptions | None) – Optional override for the respective SCF options struct.

  • rhf_options (vibeqc._vibeqc_core.RHFOptions | None)

  • uhf_options (vibeqc._vibeqc_core.UHFOptions | None)

  • rks_options (vibeqc._vibeqc_core.RKSOptions | None)

  • uks_options

Return type:

The SCF result object (RHFResult / UHFResult / RKSResult / UKSResult).