vibeqc.ScanResult

class vibeqc.ScanResult(values, energies, geometries, converged_flags, coordinate, output_path=None, extra=<factory>)

Bases: object

Container for the output of relaxed_scan().

Parameters:

• values (ndarray)

• energies (ndarray)

• geometries (list[Any])

• converged_flags (list[bool])

• coordinate (Tuple[str, int, int] | Tuple[str, int, int, int] | Tuple[str, int, int, int, int])

• output_path (Path | None)

• extra (dict[str, Any])

__init__(values, energies, geometries, converged_flags, coordinate, output_path=None, extra=<factory>)

Parameters:

• values (ndarray)

• energies (ndarray)

• geometries (list[Any])

• converged_flags (list[bool])

• coordinate (Tuple[str, int, int] | Tuple[str, int, int, int] | Tuple[str, int, int, int, int])

• output_path (Path | None)

• extra (dict[str, Any])

Return type:

None

Methods

__init__(values, energies, geometries, ...)
write_qvf(path, *[, ...])	Emit a vibe-view reaction.path QVF for animation.

Attributes

output_path	Path stem the scan wrote, or None if no output was requested.
values	Target coordinate values, shape (n_points,) — bohr or radians.
energies	Relaxed energies (Ha), shape (n_points,).
geometries	Relaxed geometries — one Molecule or PeriodicSystem per scan point.
converged_flags	Whether the relaxation at each point converged.
coordinate	The constraint definition used.
extra

values: ndarray

Target coordinate values, shape (n_points,) — bohr or radians.

energies: ndarray

Relaxed energies (Ha), shape (n_points,).

geometries: list[Any]

Relaxed geometries — one Molecule or PeriodicSystem per scan point.

converged_flags: list[bool]

Whether the relaxation at each point converged.

coordinate: Tuple[str, int, int] | Tuple[str, int, int, int] | Tuple[str, int, int, int, int]

The constraint definition used.

output_path: Path | None = None

Path stem the scan wrote, or None if no output was requested.

extra: dict[str, Any]

write_qvf(path, *, transition_state_frames=None, emit_volumes_every=None, volume_spacing=0.25, volume_padding=4.0)

Emit a vibe-view reaction.path QVF for animation.

Each scan point becomes one frame; the reaction coordinate carries the constraint values; the energy curve becomes the per-frame energies array. Endpoints are tagged as reactant / product; the highest-energy intermediate point is tagged as a point waypoint (we don’t claim it’s a TS — that requires a Hessian check).

The energy-plot x-axis is labelled from the scan coordinate (e.g. "bond 0–1 (bohr)") via the optional reaction_coordinate_label / reaction_coordinate_unit metadata.

Periodic scans (with PeriodicSystem geometries) ship as QVF v2 archives with the per-frame lattice + dim on the reaction.path section. The writer detects periodic frames automatically; vibe-view’s renderer draws the cell and wraps atoms across in-plane periodic boundaries.

Parameters:

• transition_state_frames (Sequence[int] | None) – Optional frame indices the caller has independently verified to be transition states (e.g. via a Hessian / single-imaginary-mode check). Each is tagged with a transition_state waypoint (rendered with the red TS star). We never auto-promote the energy max to a TS — a scan maximum is not a verified saddle (CLAUDE.md §7), so without this argument the max stays a point.

• emit_volumes_every (int | None) – If set to N, attach the electron density (evaluated on a shared real-space grid) for every N-th scan frame so the viewer can morph the isosurface along the scan. N=1 emits every frame; N=5 every fifth (endpoints always included). Each emitted frame costs one extra single-point SCF, so cubes are opt-in and decimated. Molecular scans only — periodic raises NotImplementedError. Grid box auto-sizes to the union of all emitted geometries with volume_padding bohr of headroom and volume_spacing bohr voxels.

• path (str | Path)

• volume_spacing (float)

• volume_padding (float)

Return type:

Path