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 |
|---|---|
|
Its own ID, unique in the document. |
|
|
|
As printed: |
|
Atoms per formula unit, such as |
|
Net charge per formula unit. An electron is always -1. Everything else defaults to 0. |
|
Sites held per formula unit, by site type. |
|
A periodic structure of the document this state is drawn from. |
|
Site IDs of that structure that belong to this participant. |
|
The bulk or slab structure this state belongs to. |
|
A molecular species, for a gas, a solute or an adsorbate. |
|
Free text, such as |
The formula comes from one of three places:
the
atomsof 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 forCuO(s));the stated
formulaalone, 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
Monolayer coverage per adsorbate. |
|
Lattice-site maps |
|
Atom maps |
|
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/examplesandGET /api/solid-reactions/examples/{name}list and return the worked schemes.GET /api/documents/{id}/solid-reactionsreturns the report.POST /api/documents/{id}/solid-reactionstakesrevision,participants,stepsandreplace.POST .../solid-reactions/removetakesrevisionandids.POST .../solid-reactions/exampletakesrevisionandname.POST .../solid-reactions/checktakesstepand optional extraparticipants, and changes nothing.POST .../solid-reactions/figuretakes optionalstepsandstyle, 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.