vibeqc.format_scf_trace

vibeqc.format_scf_trace(result, *, molecule=None, basis=None, include_banner=True, include_properties=True, n_virtual=5, property_status=None, energy_label='Total energy')[source]

Return a multi-line string with a header, per-iteration lines and a summary. Safe to print, log, or write to a file.

Parameters:

  • result – Any SCF result struct with a scf_trace list and converged, n_iter, energy fields (RHFResult, UHFResult, RKSResult, UKSResult, PeriodicRHFResult, PeriodicKSResult, …).

  • molecule – Optional Molecule. When supplied, the trace is extended with an energy-component breakdown (DFT only), an orbital-energy table, and HOMO/LUMO markers. Without it we can’t infer occupation counts from the result alone, so those sections are skipped.

  • basis – Optional BasisSet. Required alongside molecule to compute the post-SCF properties block (Mulliken / Löwdin charges, Mayer bond orders, dipole moment). When absent, the properties block is skipped.

  • include_banner (bool) – Prepend the vibe-qc version banner. Default True; set False to produce a trace without provenance (e.g. for unit-test comparisons where the version string would drift).

  • include_properties (bool) – Emit the Mulliken / Löwdin / Mayer / dipole block when molecule and basis are both supplied. Default True.

  • n_virtual (int) – Number of virtual orbitals above HOMO to print in the table. Default 5.

  • property_status (dict | None) – Optional mutable dict; when supplied, the post-SCF properties block records per-analysis success into it (currently property_status["hirshfeld"]). Lets a caller gate a citation on whether a best-effort analysis actually computed, without recomputing it. Default None (no status reported).

  • energy_label (str) – Label for the scalar energy in the component breakdown. run_job uses "SCF energy" when post-SCF add-ons such as dispersion are requested, so parsers do not mistake the SCF trace for the final user-facing total.

Return type:

str