Electrode reactions¶

A half-reaction is drawn like any reaction, with what SMILES cannot write added as text. vibe-sketch reads that text back, so the reaction knows its electrons, the states of its participants and the potential at the arrow, and can check that atoms and charge balance.

Drawn	Read as
`2e⁻`, `2 e-` or `2e−` among a side’s participants, joined by plus signs	Electrons taken up (reactants) or given off (products), counted in the charge balance
`+ 2e⁻` or `− 2e⁻` above or below the arrow	Electrons taken up or given off
`(s)`, `(l)`, `(g)`, `(aq)`, `(ads)` or `*` just right of a molecule	Its state
A number just left of a molecule, as in `2 H₂O`	Its coefficient
`−1.2 V vs Ag/AgCl (3 M KCl)` at the arrow	A potential with its reference electrode: SHE, NHE, SCE, RHE or Ag/AgCl, with the KCl concentration (`sat.` reads as 4.2 M)
`pH 7.4`, `25 °C` or `298 K`, `2 h` at the arrow	pH, temperature, time

The text stays in the drawing, so figures and the chemfig export print it as drawn. Superscripts such as e⁻ and Pb²⁺ are set raised and smaller in every figure format, since the publication font has no superscript minus. A reaction records what it read as electrons, states, coefficients and quantities (see the document format); its condition lines stay as written.

Electrons are not a species: SMILES has no electron, so they are a participant of their own, kept beside the reaction. A molecule’s coefficient and state labels belong to it when the derivation decides which molecules a plus sign joins, so 2 H⁺(aq) + 4e⁻ reads as one side.

Solids given by their formula¶

Catalysts, oxides, salts and scales have no molecular graph, so they are written as formulas: C(s), Fe2O3(s), Pb3(CO3)2(OH)2(s), CuSO4·5H2O(s), a variable or doped composition such as Fe3−xCrxO4(s) or CoAlxOy(s), a composite such as AlOx–Fe2O3(s), or with a polymorph, γ-Al2O3. A text that is such a formula, marked as a solid by (s) or a polymorph, takes part in the reaction as a molecule would: on a side, joined by plus signs and with a coefficient before it, or at the arrow as a reagent, such as a catalyst. A plain formula text such as NaOH or H2O at an arrow stays a condition.

The species it becomes has a solid record instead of a SMILES: the formula as drawn, its canonical form (each phase in Hill order, a variable count in parentheses: Cr(x)Fe(3-x)O4), the polymorph and state, the composition and, when every count is a number, the molar mass, from the same atomic weights as the species report. The canonical formula with polymorph and state, such as γ-Al2O3(s), identifies it in place of an InChI, so the same solid drawn twice is one species.

A solid’s atoms count in the balance check; a variable composition cannot be counted, and the check says so. Its molar mass serves the stoichiometry table. Figures print the formula with its counts lowered, Fe₃₋ₓCrₓO₄(s), and the chemfig export with \textsubscript. Nothing is calculated for a solid: every input writer, 3D embedding and QVF export refuse it, because it needs its structure, which crystal and slab models will give (roadmap Phase 5). MOL, SDF, RXN, SMILES and InChI cannot hold it and refuse the document; KET, CDXML, .vsk and figures keep it.

vibe-sketch half-reaction cvd.vsk --reactant C --product "formula:C;s" \
    --product "2*[H][H]" --over "formula:Fe3−xCrxO4"

A participant formula:FORMULA is a solid, and --over puts a reagent such as a catalyst above the arrow. The SDK, REST and MCP take a participant as {formula, coefficient, state} and the reagents above the arrow as over.

Draw one¶

vibe-sketch half-reaction cell.vsk --reactant "[Pb+2];aq" --product "[Pb];s" \
    --electrons 2 --condition "−1.2 V vs Ag/AgCl (3 M KCl)"
vibe-sketch half-reaction cell.vsk --reactant "2*O;l" --product "O=O;g" \
    --product "4*[H+];aq" --electrons 4 --electron-side products \
    --condition "1.23 V vs RHE"

A participant is [COEF*]SMILES[;STATE]. --at-arrow draws the electrons above the arrow. The document is created when it does not exist, and the balance of each new reaction is printed.

Check the balance¶

vibe-sketch balance DOC [REACTION] counts, for each side, the atoms (implicit hydrogens included) and the charge, each times its coefficient, less one charge per electron. It prints balanced, or what the products have more of than the reactants:

r1: unbalanced, products minus reactants: charge -1

It exits 1 when a reaction does not balance and never changes one. Reagents drawn at the arrow are not counted.

The stoichiometry table takes a drawn coefficient when none other than 1 was entered, and lists a half-reaction’s electrons with their amount from the limiting reactant and the charge passed, Q = n(e⁻)·F (F = 96 485.332 12 C/mol).

Every interface¶

SDK: vibesketch.document.electrochem has with_half_reaction, balance, describe and quantities. REST: POST /api/documents/{id}/half-reactions (revision, reactants, products, electrons {count, side, at_arrow}, conditions, arrow) and GET /api/documents/{id}/balance; the document’s reactions carry electrons and states. MCP: add_half_reaction and check_balance.

A metal electrode drawn as an atom, such as Pb(s), is a lead atom to the chemistry: a triplet with two unpaired electrons, drawn with them. Solids without a molecular graph are a later step (#142).

See energy recipes for cited aqueous reduction-potential calculations, explicit result selection and reference conversion.