vibeqc.dump_on_failure

vibeqc.dump_on_failure(out_stem, exc, state, *, phase=None, options=None, molecule=None)[source]

Write {out_stem}.dump (TOML) plus binary attachments capturing the last known SCF state.

Parameters:

  • out_stem (str | PathLike) – Path stem identifying the failing job — typically the same stem run_job was called with. .dump and friends are appended.

  • exc (BaseException | None) – The exception that triggered the dump. May be None — used when the dump fires from a non-exceptional max-iter path.

  • state (dict[str, Any]) –

    Dictionary carrying as much of the last SCF state as the caller has on hand. Recognized keys (all optional):

    • "scf_trace" — list of SCFIteration-like records; the last entry is rendered into [scf.last_iter].

    • "density" / "density_alpha" / "density_beta" — numpy arrays, side-loaded as .dump.density.npy / .dump.density_alpha.npy / .dump.density_beta.npy.

    • "fock" / "fock_alpha" / "fock_beta" — numpy arrays, side-loaded similarly.

    • "mo_coeffs" / "mo_coeffs_alpha" / "mo_coeffs_beta" — numpy arrays, side-loaded as .dump.mo.npy / .dump.mo_alpha.npy / .dump.mo_beta.npy.

    • "phase" — overridden by the phase kwarg when set.

    • "n_iters_completed" — explicit override; otherwise inferred from the trace length.

  • phase (str | None) – Short string identifying where the failure happened (e.g. "scf_iteration_5", "basis_set_construction"). When None, derived from the last trace entry or set to "unknown".

  • options (Any) – SCF options struct. Walked via dir() and only primitive-typed attributes survive.

  • molecule (Any) – Molecule (or shape-compatible) — used to dump the [geometry] section.

Returns:

Path to the written .dump file (the binary attachments live next to it as .dump.density.npy, .dump.fock.npy, …).

Return type:

pathlib.Path

Notes

Never raises. A dump-write failure prints a one-line warning to stderr and returns the (would-be) path so the caller’s re-raise path is unchanged.