vibeqc.plot.plot_convergence

vibeqc.plot.plot_convergence(result, *, save=None, figsize=(8.0, 4.5), show_diis=True, title=None, molecule=None, basis=None)[source]

Convergence plot: |ΔE| and ‖[F,DS]‖ vs iteration on log-y.

PySCF’s scf.diis_plot() equivalent for vibe-qc — drops a publication-grade PNG with one call so users can eyeball “is the SCF actually converging?” without parsing the trace by hand.

Parameters:

  • result – Any SCF result with a scf_trace list of records carrying iter, delta_e, grad_norm and (optionally) diis_subspace — that’s RHF/UHF/RKS/UKS plus the periodic results.

  • save (str | PathLike | None) – Path to write a PNG. When None (default), the figure is returned unsaved so the caller can customise further before fig.savefig(...).

  • figsize (Tuple[float, float]) – Matplotlib figure size in inches. Default (8, 4.5) — 16:9 publication aspect.

  • show_diis (bool) – If True (default) and the trace carries non-zero DIIS subspace dims, draw them as a step plot on a third (twin) axis.

  • title (str | None) – Override the auto-derived title. The default reads method / functional from the result class and basis.name when both molecule and basis are passed.

  • molecule – Optional context for the auto-title. Both are accepted for symmetry with vibeqc.format_scf_trace(); only the basis name is currently used (molecule is reserved for future use, e.g. labeling the H/L gap on the marker line).

  • basis – Optional context for the auto-title. Both are accepted for symmetry with vibeqc.format_scf_trace(); only the basis name is currently used (molecule is reserved for future use, e.g. labeling the H/L gap on the marker line).

Returns:

The figure. When save is set, the PNG is also written before returning.

Return type:

matplotlib.figure.Figure

Notes

The first iteration has no ΔE — there’s no previous energy to subtract — so the |ΔE| trace starts at iteration 2 and falls back to the global tolerance epsilon (1e-16) for any later iteration that recorded delta_e == 0 exactly (a numerically converged step). Otherwise log10(0) would blow up the y-axis.