Results and reaction energies

Import completed calculation outputs onto their recorded runs, then explicitly choose the source group or runs for a reaction-energy report. The original sketch stays editable. A derived figure puts energies below its arrows; the report and exported QVF retain every source run, method and file digest.

In the browser

After submitting calculations, open Reaction results below the calculation list. Choose Source run and its Result file, then Import result. Repeat for the other participants. Replacing an existing, different result requires Replace existing result.

Choose a Result group and a reaction, or all reactions. Confirm the coefficients on both chemical sides; they start at one. For a retrosynthetic arrow, the chemical reactants are the precursors at its head and the chemical products are the target at its tail. Reagents are not added to the energy sum. If an apparent reagent is consumed, draw it as a reactant first.

Preview reaction energies opens a read-only figure with ΔE and, when all participants have compatible thermochemistry, ΔH and ΔG. Download its SVG, a JSON energy report, or a QVF carrying the selected energies. The figure is computed afresh from the stored results, with space checked below each arrow; spread out the drawing if the preview refuses an overcrowded layout. The SVG metadata also contains the report and source identities. This preview does not add permanent energy text that could go stale in the editable sketch.

Acceptance and limitations

The local reader supports ORCA 6 text output for sp, opt, freq and opt+freq. It requires one normally terminated calculation, an SCF convergence marker and an exact normalized match between its echoed input and this job’s input, including coordinates, charge, multiplicity and all options. Full-line metadata comments and ORCA’s appended end-of-input marker are excluded from that comparison, so a later app version or display label does not invalidate the output. Repeated enthalpy in the Gibbs summary must agree. Optimisations also require the optimisation-converged marker. Frequency jobs require one complete thermochemistry block with absolute enthalpy/Gibbs energy, temperature and pressure. Multiple-temperature or compound-job output, property JSON/text, output without echoed input and other tasks are refused. Isotope-labelled inputs are refused because the current reader cannot verify the masses used by the calculation. No optional companion changes which parser is used.

Geometries

An ORCA optimisation (opt or opt+freq) brings its converged geometry back. The reader takes the CARTESIAN COORDINATES (ANGSTROEM) block printed after the optimisation-converged marker; if ORCA prints it more than once, the copies must agree. The atoms must be the species’ input atoms in their input order, or the output is refused: nothing is re-mapped. The geometry becomes a further 3D structure of the species, named orca:<task>:<12 hex digits> after the output’s SHA-256, so the structure and the result it came from name each other. The input geometry stays first, the drawing is not changed, and replacing the result replaces its geometry. The species card lists it beside the first 3D structure, and it is saved in .vsk and QVF.

An ORCA Hessian file (.hess, format orca-hess) is checked against the run it belongs to: a freq or opt+freq run whose ORCA output is already imported. The geometry in its $atoms block (bohr) must be that run’s stationary point within 1e-4 Å: the input geometry for freq, the optimised one for opt+freq. A common translation is removed before comparison because ORCA may use a different coordinate origin in its Hessian file. Atom order and the 1e-4 Å tolerance remain strict; rotations, reflections, scaling and internal distortions are not accepted. The stored conformers are not moved. The Hessian file adds no second copy of a geometry the species already holds. Optimisation trajectories are not kept as structures of the species.

The output vocabulary follows the ORCA 6.1 quick-start manual and thermochemistry chapter.

For vibe-qc, import the finished QVF job container. The existing optional QVF library validates the archive, including member hashes and energy consistency. The reader requires one successful, converged run record and a matching job specification and input structure. It reads energies.total, or provenance.scf_energy when the former is absent; when both exist they must agree within 1e-8 hartree. Thermochemistry uses the QVF root fields and must state temperature and pressure. Multi-run containers are currently refused. Install the documented QVF extra if the reader is unavailable. Input files are limited to 32 MiB, with bounded uncompressed QVF members.

The parser records what the completed output states; it does not independently validate a potential-energy minimum, transition state, imaginary modes, model adequacy or chemical mechanism. Those scientific acceptance checks remain part of the staged workflow and paper protocol.

A comparison requires exactly one selected result per participant, matching program/version and job specification (resource counts may differ), and matching thermochemistry temperature/pressure. Missing, conflicting, stale, non-finite or atom/charge-unbalanced data are refused. Supply explicit positive coefficients for non-unit stoichiometry; coefficients belong to the requested report, not to a new reaction-schema field. Resonance arrows have no reaction energy. Changing the species or input geometry invalidates a stored result; changing its display label does not.

SDK, CLI and REST

from pathlib import Path
from vibesketch.document import load, save
from vibesketch.document.results import Selection, import_result, reaction_energies, result_figure

sketch = load("scheme.vsk")
sketch = import_result(
    sketch, "run1", Path("run1.out").read_bytes(), format="orca", source_name="run1.out"
)
save(sketch, "scheme-with-results.vsk")
# Import the other participant outputs before requesting this comparison.
selection = Selection(group="g1", reactions=["r1"])
report = reaction_energies(sketch, selection)
Path("reaction-energies.svg").write_bytes(result_figure(sketch, selection))

vibe-sketch import-result scheme.vsk run1 run1.out --format orca --output with-results.vsk
vibe-sketch reaction-energies with-results.vsk --group g1 --reaction r1
vibe-sketch reaction-energies with-results.vsk --group g1 --format svg --output energies.svg
vibe-sketch reaction-energies with-results.vsk --run run1 --run run2 --format qvf --output energies.qvf

Use --coefficients coefficients.json when needed, for example:

{"r1": {"reactants": {"m1": 2}, "products": {"m2": 1}}}

POST /api/documents/{id}/results takes revision, run, format (orca or qvf), source_name, base64 data and optional replace. It returns the new document revision; stale edits return 409. No server filesystem path is accepted. POST /api/documents/{id}/results/report takes group or runs, optional reactions and coefficients, and format (json, svg or qvf). Unsupported results/comparisons return 422; an unavailable optional backend returns 503. The MCP tools are import_run_result and show_reaction_energies.

The optional Run.result stores absolute energies in hartree, the full job specification, parser/program version, retrieval timestamp, source basename and SHA-256, input-species digest, and each value’s source line/key. Source basenames may contain spaces and Unicode; paths and control characters are refused. Existing schema v1 documents remain valid. Reaction deltas are computed on demand as the sum of product energies minus reactant energies with their coefficients. Conversion to kcal/mol uses the shared CODATA 2018 factor, 627.509474.

A selected QVF export writes the report under each step’s x_vibesketch.energies, with canonical participant coefficients. Ordinary VSK and QVF saves preserve the absolute run results without choosing a comparison. The original output file is not embedded; archive it alongside the figure and report to retain auditable calculation evidence.

Energy tables

Use Download energy CSV, Download Markdown table, or Download LaTeX table with the same explicit group/reaction selection and coefficients as the figure. Each table has one row per reaction, with its participants, coefficients, absolute energies, method, conditions and source run IDs. Missing thermal values are empty in CSV and a dash in presentation tables; they are never zero.

vibe-sketch reaction-energies with-results.vsk --group g1 --format csv --output energies.csv
vibe-sketch reaction-energies with-results.vsk --group g1 --format markdown --output energies.md
vibe-sketch reaction-energies with-results.vsk --group g1 --format latex --output energies.tex

The SDK is vibesketch.document.tables.reaction_table(document, selection, format="csv"), returning UTF-8 bytes. The existing results/report REST endpoint also accepts csv, markdown and latex. MCP export_energy_table returns format, media_type and text; it uses the same selection fields.

CSV retains round-trip floating-point precision, deltas in both hartree and kcal/mol, and full provenance. The reactants_json and products_json cells contain JSON arrays so reactions with different numbers of participants still occupy one CSV row. Decode them with json.loads; coefficients are positive on each chemical side. specification_json describes the shared method. Subtract the coefficient-weighted reactant absolute energies from the products to replay the reported delta. Potential spreadsheet formulas in text cells are prefixed with an apostrophe; numeric columns remain numeric.

Markdown and LaTeX display absolute energies to 12 decimal places in hartree and deltas to 3 decimal places in kcal/mol. Use CSV or the JSON report for numerical replay at full precision. Text is escaped for the selected markup. LaTeX exports are fragments requiring \usepackage{booktabs}; use LuaLaTeX or XeLaTeX when identifiers contain Unicode. The table uses paragraph columns relative to the current line width. For long schemes, place the table in a wide page or split it by selecting reactions; the fragment does not paginate itself.