vibe-sketcherDocumentation

Solid-state and surface reaction schemes

A solid-state or surface reaction scheme lists participants and the steps between them. A participant is one physical state: a bulk phase, a clean or adsorbed slab, an empty surface site *, a surface vacancy, an adsorbate, a gas or solution species, or an electron. A step is an adsorption, desorption, dissociation, diffusion, surface transformation or balanced bulk synthesis, written with formula coefficients. Every step is checked for its atom, charge and site balance. A quantity that does not balance is refused unless the step states an open reservoir for it.

The scheme lives in two additive document fields, solid_participants and solid_steps. Documents without a scheme are unchanged. Molecular reactions (reactions) stay as they are; the two kinds of scheme do not share entries.

Participants

Field

Meaning

id

Its own ID, unique in the document.

kind

bulk_phase, slab, adsorbed_slab, empty_site, surface_vacancy, adsorbate, gas, solution or electron.

label

As printed: CO*, CuO(s), *, V_O, e^-.

formula

Atoms per formula unit, such as {"Cu": 1, "O": 1}.

charge

Net charge per formula unit. An electron is always -1. Everything else defaults to 0.

sites

Sites held per formula unit, by site type.

structure

A periodic structure of the document this state is drawn from.

atoms

Site IDs of that structure that belong to this participant.

parent

The bulk or slab structure this state belongs to.

species

A molecular species, for a gas, a solute or an adsorbate.

state, note

Free text, such as 0.1 M KOH.

The formula comes from one of three places:

  • the atoms of a structure, for an adsorbate on a slab model;

  • the whole structure, for a slab. A stated formula is then a formula unit, and the structure must hold a whole number of them (a CuO cell with four formula units for CuO(s));

  • the stated formula alone, for a participant without geometry.

A species-backed participant takes its formula, hydrogens included, and its charge from the species. Partial occupancy has no integer formula, so such a structure needs a stated one.

Empty sites, vacancies and electrons carry no atoms. Site types are free names. * is an adsorption site; an empty site and an adsorbate hold {"*": 1} unless they say otherwise. A vacancy must name the lattice site it leaves empty, such as {"O_site": 1}. As in Kröger-Vink notation, the vacancy still occupies that site, so O_O -> V_O + 1/2 O2(g) balances its O_site count.

Several participants may draw on the same structure, or name the same parent, and still keep their own IDs: the clean slab, the adsorbed slab and the CO* on it are three participants. The report groups them under parents.

Steps and balances

Field

Meaning

kind

adsorption, desorption, dissociation, diffusion, surface_transformation or bulk_synthesis.

reactants, products

[{participant, coefficient}]; coefficients may be fractions such as 0.5.

arrow

forward or equilibrium.

reservoirs

[{quantity, description, participant?}]: what is exchanged outside the scheme.

conditions

facet, temperature_k, pressures [{value, unit, of}], potential {value_v, reference}, notes.

coverages

Monolayer coverage per adsorbate.

site_map

Lattice-site maps [{from: {participant, site}, to: {participant, site}, image}].

atom_map

Atom maps [{from: {participant, site}, to: {participant, site}}].

schematic

True for a scheme kept as drawn in a paper.

Each step balances three kinds of quantity, products minus reactants:

  • atoms, element by element;

  • charge;

  • sites, per site type (site:*, site:O_site).

A non-zero quantity is refused unless a reservoir names it. The quantity is an element symbol, charge or site:<type>, and the description says what the reservoir is: O2(g) at the stated pressure, the electrode at the stated potential, a surface of many sites. A bulk synthesis never takes a reservoir; it balances or is refused. The step kind is checked too:

  • an adsorption takes a gas or solute to an adsorbate, and a desorption takes an adsorbate back;

  • a dissociation gives two or more products, adsorbates among them;

  • a diffusion moves an adsorbate or a vacancy and needs a site map;

  • a bulk synthesis has only bulk phases, gases and solutes.

Coefficients, coverages, site maps and atom maps are separate fields. A coefficient never implies a coverage, and a site map never implies an atom map.

Conditions annotate a step. They state no rate, barrier, equilibrium constant or reaction order. Every report says so. Nothing in the scheme claims a balanced kinetics.

Diffusion and periodic images

A diffusion step maps a site of the start state to a site of the end state in the lattice cell image. Both endpoints must reference structures with the same cell and periodicity. The image must be zero along a nonperiodic axis. The report gives the hop vector and length in angstrom and says whether the stated image is the minimum image. A longer hop is kept as stated and flagged; it is never wrapped. In the test fixture an O atom hops from x = 0.9 to x = 0.1 of a 5 A cell. With image [1, 0, 0] the hop is 1 A, the minimum image. With [0, 0, 0] it is 4 A back across the cell, and it is flagged.

This page covers endpoints only. Paths, nudged elastic bands and barriers are not part of a scheme. They belong to admitted periodic engine routes.

Schematic paper schemes

A scheme copied from a paper can stay schematic: participants with labels and formulas but no structure, and steps marked schematic: true. Nothing makes up a geometry for them. A schematic step whose participants name a structure is refused, so the flag stays honest.

Worked examples

co-adsorption is CO(g) + * <=> CO* on Pt(111) at 300 K and 1 mbar CO. cuo-reduction is CuO(s) + H2(g) -> Cu(s) + H2O(g), a balanced bulk reduction at 573 K. Both are schematic.

from vibesketcher.document import new_document
from vibesketcher.document import solid_reactions as sr
from vibesketcher.render.solid_reactions import scheme_svg

document = sr.apply_example(new_document(), "co-adsorption")
document = sr.add(
    document,
    participants=[
        {"id": "Hp", "kind": "solution", "label": "H^+ (aq)", "formula": {"H": 1}, "charge": 1},
        {"id": "e", "kind": "electron", "label": "e^-"},
        {"id": "H_ads", "kind": "adsorbate", "label": "H*", "formula": {"H": 1}},
    ],
    steps=[
        {
            "id": "volmer",
            "kind": "adsorption",
            "reactants": [{"participant": "Hp"}, {"participant": "e"}, {"participant": "site"}],
            "products": [{"participant": "H_ads"}],
            "conditions": {"potential": {"value_v": -0.1, "reference": "RHE"}},
        }
    ],
)
report = sr.report(document)
dry_run = sr.check_step(
    document,
    {
        "id": "x",
        "kind": "desorption",
        "reactants": [{"participant": "CO_ads"}],
        "products": [{"participant": "CO_g"}],
    },
)
svg = scheme_svg(document)

The dry run is refused, because the site * freed by the desorption is not a product. Add the empty site to the products, or state a site:* reservoir.

Command line, REST and MCP

vibe-sketcher solid reaction examples
vibe-sketcher solid reaction add scheme.vsk --example co-adsorption
vibe-sketcher solid reaction add scheme.vsk --participant '{"id": "O2", "kind": "gas", "label": "O2(g)", "formula": {"O": 2}}'
vibe-sketcher solid reaction check scheme.vsk --step '{"id": "x", "kind": "desorption", "reactants": [{"participant": "CO_ads"}], "products": [{"participant": "CO_g"}]}'
vibe-sketcher solid reaction show scheme.vsk
vibe-sketcher solid reaction figure scheme.vsk -o scheme.svg
vibe-sketcher solid reaction remove scheme.vsk co_adsorption

solid reaction check prints the balance as JSON and exits with status 3 when the step would be refused. --replace on add changes entries whose IDs exist already. remove refuses a participant that a remaining step still uses.

  • GET /api/solid-reactions/examples and GET /api/solid-reactions/examples/{name} list and return the worked schemes.

  • GET /api/documents/{id}/solid-reactions returns the report.

  • POST /api/documents/{id}/solid-reactions takes revision, participants, steps and replace.

  • POST .../solid-reactions/remove takes revision and ids.

  • POST .../solid-reactions/example takes revision and name.

  • POST .../solid-reactions/check takes step and optional extra participants, and changes nothing.

  • POST .../solid-reactions/figure takes optional steps and style, and returns SVG.

A stale revision is answered with 409, and a refused step with 422 and its reasons. The MCP tools are solid_reactions (report, dry-run check, worked example), edit_solid_reactions (add, replace, remove, example) and solid_reaction_figure.

Figures

The figure has one row per step: reactants, an arrow with the facet and pressures above it, and the temperature, potential, notes and open reservoirs below it. The products and the step kind follow. Every participant label is its own <text> element with a data-participant attribute, and every step is a <g data-step> group, so the figure stays editable in a vector editor. Text sizes and line widths follow the document’s figure style preset. In a label, digits after a letter or a closing bracket print as subscripts, and ^ starts a superscript that runs to the next space (e^-, O^2-).

Export

Molecular formats cannot carry these participants. MOL, SDF, RXN, SMILES, InChI, CDXML, KET, chemfig and the document figures refuse a document with a solid reaction scheme and name its participants, rather than dropping them silently. VSK and QVF keep the scheme. Draw it with solid reaction figure.