vibesketch.document.results

Explicit, provenance-bound result imports and reaction energies (#28).

An optimisation’s converged geometry comes back with its result, as a new conformer of the species named orca:<task>:<first 12 hex digits of the source's SHA-256>, so the conformer and the result it came from name each other. An ORCA Hessian file (.hess) is checked against the run’s stationary point (#85).

ORCA text vocabulary: ORCA 6.1 manual, Hello water and Thermochemistry: https://www.faccts.de/docs/orca/6.1/manual/contents/quickstartguide/hellowater.html https://www.faccts.de/docs/orca/6.1/manual/contents/structurereactivity/thermochemistry.html QVF root energies and thermochemistry: format specification sections 3.3/3.6. No filesystem discovery, implicit run selection or companion-dependent parsing.

Functions

import_result(document, run_id, data, *, ...)	Return a copy with one verified result.
reaction_energies(document, selection)	Products minus reactants, with explicit source runs and balanced coefficients.
result_figure(document, selection)	A derived SVG preview: energies below arrows, without changing the sketch.
species_digest(species)	Bind identity, charge/spin and the exact input geometry; labels are editable.

Classes

Selection(*[, group, runs, reactions, ...])

Select a group or exactly one run per species, never an implicit latest run.

Exceptions

ResultRefused

The supplied evidence cannot support this result or comparison.

exception vibesketch.document.results.ResultRefused

Bases: ValueError

The supplied evidence cannot support this result or comparison.

class vibesketch.document.results.Selection(*, group=None, runs=None, reactions=None, coefficients=<factory>)

Bases: BaseModel

Select a group or exactly one run per species, never an implicit latest run.

Coefficients, when supplied, name every species on both chemical sides of the requested reaction. Unspecified reactions use one of each species; atom/charge balance is checked, so an omitted factor cannot pass silently.

Parameters:

• group (str | None)

• runs (list[str] | None)

• reactions (list[str] | None)

• coefficients (dict[str, dict[str, dict[str, float]]])

model_config = {'extra': 'forbid', 'strict': True}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

group: str | None

runs: list[str] | None

reactions: list[str] | None

coefficients: dict[str, dict[str, dict[str, float]]]

vibesketch.document.results.species_digest(species)

Bind identity, charge/spin and the exact input geometry; labels are editable.

Parameters:

species (Species)

Return type:

str

vibesketch.document.results.import_result(document, run_id, data, *, format, source_name, replace=False)

Return a copy with one verified result. Never read a path supplied over HTTP.

An ORCA optimisation’s converged geometry is attached to the species as a conformer; orca-hess checks a Hessian file against a run that already has its verified output.

Parameters:

• document (Document)

• run_id (str)

• data (bytes)

• format (Literal['orca', 'qvf', 'orca-hess'])

• source_name (str)

• replace (bool)

Return type:

Document

vibesketch.document.results.reaction_energies(document, selection)

Products minus reactants, with explicit source runs and balanced coefficients.

Parameters:

• document (Document)

• selection (Selection)

Return type:

list[dict[str, Any]]

vibesketch.document.results.result_figure(document, selection)

A derived SVG preview: energies below arrows, without changing the sketch.

Parameters:

• document (Document)

• selection (Selection)

Return type:

bytes