Redox and finite-cluster binding recipes

Energy recipes save an ordinary writer calculation stage and a typed analysis in Document.recipes. They are available through SDK, CLI, REST and MCP. They use the existing recorded jobs, queue submission and verified result import. No calculation runs when a recipe is compiled.

Aqueous reduction potentials

Start with a balanced half-reaction, drawn in the reduction direction with electrons on the reactant side. Molecular participants are aqueous (or have no explicit phase). A proton is [H+]; its coefficient comes from the drawing. Reagents above the arrow are not thermodynamic participants. Prepare the molecular species in 3D first.

The calculation must be opt+freq with explicit CPCM or SMD water. Every non-proton participant receives that same specification. The saved recipe must state all of the following; none is chosen silently:

  • Absolute SHE potential in V and its source.

  • Electron Gibbs energy in kJ/mol and its convention/source, including an explicit zero if that is the chosen convention.

  • For proton-coupled reactions, proton gas Gibbs energy at 1 atm and proton solvation free energy in kJ/mol, each with its source. The latter must use equal gas and solution concentrations.

  • Reference electrode, pH, temperature 298.15, input thermal standard state "1 atm" and solution standard state "1 M".

energy-recipe constants lists cited choices for review: Trasatti’s 4.44 V (1986), Isse and Gennaro’s 4.281 V (2010), and Kelly, Cramer and Truhlar’s −265.9 kcal/mol proton solvation value (2006), returned in kJ/mol. These papers use different conventions; selecting values requires a consistent thermodynamic cycle, not merely a familiar numerical reference.

The analysis selects one explicit imported run per molecular species. It checks program, version, specification, species/geometry digest, thermochemistry at 298.15 K and 1 atm, and frequencies with no imaginary modes. It rejects missing, mixed or stale results. Proton energies come from the cited recipe values, not a zero-electron quantum calculation.

For each solute the analysis adds RT ln(cRT/p) to the imported thermal Gibbs energy to convert 1 atm to 1 M. The proton gas Gibbs energy receives the same correction before its equal-concentration solvation term is added. With products minus reactants coefficients, the electron term is subtracted n times. The result is E°(SHE) = −ΔG/(nF) − Eabs(SHE). The report records every correction and source. At the chosen pH, proton activity is 10^(-pH) and all other activities are unity.

Conversion subtracts the reference’s potential vs SHE: +0.197 V for Ag/AgCl saturated KCl, +0.207 V for Ag/AgCl 3 M KCl (Metrohm, Table 1), +0.241 V for SCE (Isse and Gennaro, 2010). RHE uses −RT ln(10) pH/F with unit hydrogen pressure. The implementation does not extrapolate these values to other temperatures, nonaqueous solvents or liquid junctions.

A derived SVG prints potential, reference, pH, method and solvent below the arrow, with the full result report in SVG metadata. The editable drawing is unchanged. The pH-adjusted value is labelled E, not E°.

Finite-cluster binding

Supply distinct molecular species for the cluster, adsorbate and complex, with explicit 3D coordinates, charges and multiplicities. The complex must contain exactly the atoms and total charge of the two fragments. An optional surface id links the recipe to a schematic partner; that picture does not generate or establish the physical model.

Binding recipes use sp at the supplied geometries and evaluate Ebind = Ecomplex − Ecluster − Eadsorbate. The result is an electronic energy, not a free energy. Relaxed fragments give a binding energy including deformation; fragments at complex geometry give an interaction energy. Choosing those geometries remains explicit. Results use the same provenance and compatible-specification checks as redox recipes.

The request must explicitly set counterpoise. A true value refuses: Boys–Bernardi counterpoise requires ghost-basis fragment jobs at the complex geometry, which the writer contract does not yet represent. It never substitutes an uncorrected result. Models containing elements beyond Kr also refuse until an explicit ECP/relativistic contract is available in these recipes. In particular, aryl–Au cluster requests give this reason for both ORCA and vibe-qc. Unsupported methods and solvents retain the underlying writers’ refusals; SMD is supported by the ORCA writer and refused by the vibe-qc writer.

Interfaces

An electron-only half-reaction can use a parameter file like this, after choosing the stated conventions for the intended calculation:

{
  "id": "redox1",
  "program": "orca",
  "spec": {
    "task": "opt+freq", "method": "PBE0", "basis": "def2-SVP",
    "solvent": {"model": "SMD", "name": "water"}
  },
  "analysis": {
    "kind": "redox", "reaction": "r1",
    "absolute_she_v": {"value": 4.281, "source": "Isse and Gennaro (2010), doi:10.1021/jp100402x"},
    "electron_gibbs_kj_mol": {"value": 0, "source": "Zero-temperature electron, Isse and Gennaro (2010)"},
    "reference": "SHE", "ph": 0, "temperature_k": 298.15,
    "input_standard_state": "1 atm", "solution_standard_state": "1 M"
  }
}

For proton-coupled reactions add proton_gas_gibbs_kj_mol and proton_solvation_kj_mol, each {value, source}. Binding analysis instead contains kind: "binding", complex, cluster, adsorbate, optional surface, and counterpoise: false, with task sp.

from vibesketch.document.electrochemical_recipes import (
    with_energy_recipe,
    compile_energy_recipe,
    energy_recipe_result,
    energy_recipe_figure,
)

document = with_energy_recipe(
    document,
    **{
        "identifier": request["id"],
        "analysis": request["analysis"],
        "spec": request["spec"],
        "program": request["program"],
    },
)
document, bundle = compile_energy_recipe(document, request["id"])
# Submit the recorded jobs and import their outputs using the normal result API.
report = energy_recipe_result(document, request["id"], ["run-ox", "run-red"])
svg = energy_recipe_figure(document, request["id"], ["run-ox", "run-red"])

vibe-sketch energy-recipe constants
vibe-sketch energy-recipe set drawing.vsk parameters.json
vibe-sketch energy-recipe compile drawing.vsk redox1 > inputs.json
vibe-sketch energy-recipe result drawing.vsk redox1 --run run-ox --run run-red --figure potential.svg

Compilation records jobs and returns their input files in JSON, without submitting. It refuses an existing job id rather than replacing runs. Use a new recipe id for another compilation. The publication MACE/DFT/DLPNO campaign driver refuses this ordinary-job stage and directs clients to the energy-recipe compiler.

REST operation

Request

GET /api/energy-recipes/constants

Cited choices and offsets

POST /api/documents/{id}/energy-recipes

Parameter object above plus revision

POST /api/documents/{id}/energy-recipes/{recipe}/jobs

{revision}

POST /api/documents/{id}/energy-recipes/{recipe}/results

{runs: [...]}, optional figure: true for SVG

MCP tools are energy_constants, add_energy_recipe, compile_energy_recipe and energy_recipe_results. The last accepts figure: true to return SVG text. Saved recipes can also be inspected or removed through the existing recipe interfaces. Binding reports have no reaction arrow; requesting a binding result figure refuses explicitly.

Scientific checks and their limits

The regression set replays the aqueous SMD free-energy changes and computed potentials for four couples from Ho, Coote, Cramer and Truhlar, Organic Electrochemistry, 5th ed., chapter 4, Table 3 (author manuscript): 4-COOH-TEMPO, 3-CONH2-TCPO, benzoquinone and 2,3-dimethylnaphthoquinone. The reproduced values agree within 0.006 V, allowing for the published rounding. That table uses 4.28 V and its stated electron convention. These are computational reference values, not experimental accuracy targets.

This is a thermodynamic replay of published calculations, not a fresh G3(MP2)-RAD(+) calculation or a validation of a chosen DFT protocol. Separate synthetic output tests exercise imports, proton corrections, reference changes, figures and refusals. No new quantum calculation or heavy-element binding energy is claimed by these tests.