vibeqc.write_opt_trajectory

vibeqc.write_opt_trajectory(path, frames, energies_ha=None, *, rms_grad=None, append=False)[source]

Write a geometry-optimization history as a multi-XYZ trajectory with per-step energies on the comment line.

Same on-disk format as write_xyz_trajectory() — multi-XYZ with one frame per optimization iteration. The convention here is just the comment-line content: each frame’s comment reads:

step N  E = -76.026123456789 Ha  |grad| = 1.23e-04

so the file self-documents. moltui, OVITO, ASE, and Avogadro all happily read this back as a regular multi-XYZ trajectory; the E = … token in the comment is also recognized by ASE (ase.io.read parses it into the per-frame Atoms.info dict).

Standard extension is .opt (matching the ORCA-style geometry-history convention) but the writer doesn’t enforce it — pass any path you like.

Parameters:

  • path (str | PathLike) – Output file path (default extension .opt by convention).

  • frames (Sequence[vibeqc._vibeqc_core.Molecule]) – Optimization iterates, frames[k] = geometry at step k.

  • energies_ha (Sequence[float] | None) – Optional (N,) per-step total energies in Hartree. Goes into the comment line. If None, the comment is just "step N".

  • rms_grad (Sequence[float] | None) – Optional (N,) per-step RMS gradient (any consistent unit; we just print the number). When supplied, joined into the comment as "|grad| = ..." (literal pipe characters around grad) so converged steps are easy to spot.

  • append (bool) – If True, extend an existing .opt file rather than overwriting. Useful when an optimizer writes incrementally.

Returns:

Number of frames written.

Return type:

int

Examples

>>> opt_geoms, opt_energies = run_optimization(mol)
>>> vq.write_opt_trajectory("h2o.opt", opt_geoms, opt_energies)