vibe-sketcherDocumentation

vibesketcher.document.solid_reactions

Authoring solid-state and surface reaction schemes in a document (#192).

The data model and the balance arithmetic are in vibesketcher.document.solid_reaction_model; this module edits a Document with them and reports on it. Every edit returns a new, validated document: a step whose atoms, charge or sites do not balance is refused unless it states an open reservoir for each quantity that does not.

A participant may come from a periodic structure (a bulk phase, a slab, the atoms of an adsorbate on a slab), from a molecular species (a gas or solute), or from a formula alone. A scheme copied from a paper can stay schematic: participants without structures, and steps marked schematic, so no computational geometry is made up for them.

Molecular formats (MOL, SDF, RXN, SMILES, InChI, CDXML, KET, chemfig) cannot carry these participants; export_refusal() gives the reason the exporters refuse with, so nothing is dropped silently. VSK and QVF keep them.

Module Attributes

KINETICS_NOTE

What condition annotations do not say; repeated in every report.

EXAMPLES

Worked schemes; each a dict of participants and steps for add().

KEEPING_FORMATS

Formats that keep solid reaction schemes whole.

Functions

add(document, *[, participants, steps, replace])

document with participants and steps added, as one checked edit.

apply_example(document, name)

document with a worked scheme added.

check_step(document, step[, participants])

A dry run: the balance and every refusal of step; the document is unchanged.

equation(step, participants)

The step as one line of text: CO(g) + * -> CO*.

example(name)

A copy of a worked scheme from EXAMPLES.

export_refusal(document, fmt)

Why fmt cannot carry the document's solid reaction scheme; None if it can.

remove(document, identifiers)

document without these participants and steps.

report(document)

Participants with resolved formula, charge and sites; steps with their balances.

vibesketcher.document.solid_reactions.EXAMPLES: dict[str, dict[str, Any]] = {'co-adsorption': {'description': 'CO(g) + * -> CO* on Pt(111), a schematic paper scheme.', 'participants': [{'formula': {'C': 1, 'O': 1}, 'id': 'CO_g', 'kind': 'gas', 'label': 'CO(g)'}, {'id': 'site', 'kind': 'empty_site', 'label': '*'}, {'formula': {'C': 1, 'O': 1}, 'id': 'CO_ads', 'kind': 'adsorbate', 'label': 'CO*'}], 'steps': [{'arrow': 'equilibrium', 'conditions': {'facet': 'Pt(111)', 'pressures': [{'of': 'CO', 'unit': 'mbar', 'value': 1}], 'temperature_k': 300}, 'id': 'co_adsorption', 'kind': 'adsorption', 'products': [{'participant': 'CO_ads'}], 'reactants': [{'participant': 'CO_g'}, {'participant': 'site'}], 'schematic': True}]}, 'cuo-reduction': {'description': 'CuO(s) + H2(g) -> Cu(s) + H2O(g), a balanced bulk reduction.', 'participants': [{'formula': {'Cu': 1, 'O': 1}, 'id': 'CuO_s', 'kind': 'bulk_phase', 'label': 'CuO(s)'}, {'formula': {'H': 2}, 'id': 'H2_g', 'kind': 'gas', 'label': 'H2(g)'}, {'formula': {'Cu': 1}, 'id': 'Cu_s', 'kind': 'bulk_phase', 'label': 'Cu(s)'}, {'formula': {'H': 2, 'O': 1}, 'id': 'H2O_g', 'kind': 'gas', 'label': 'H2O(g)'}], 'steps': [{'conditions': {'notes': ['H2 flow'], 'temperature_k': 573}, 'id': 'cuo_reduction', 'kind': 'bulk_synthesis', 'products': [{'participant': 'Cu_s'}, {'participant': 'H2O_g'}], 'reactants': [{'participant': 'CuO_s'}, {'participant': 'H2_g'}], 'schematic': True}]}}

Worked schemes; each a dict of participants and steps for add().

vibesketcher.document.solid_reactions.KINETICS_NOTE = 'Conditions annotate a step; they state no rate, barrier, equilibrium constant or reaction order, and the scheme does not imply a balanced kinetics.'

What condition annotations do not say; repeated in every report.

vibesketcher.document.solid_reactions.add(document, *, participants=(), steps=(), replace=False)[source]

document with participants and steps added, as one checked edit.

An ID that exists already is refused unless replace is true, which swaps the entry in place. A species-backed participant takes its formula and charge from the species.

Parameters:
Return type:

Document

vibesketcher.document.solid_reactions.apply_example(document, name)[source]

document with a worked scheme added.

Parameters:
Return type:

Document

vibesketcher.document.solid_reactions.check_step(document, step, participants=())[source]

A dry run: the balance and every refusal of step; the document is unchanged.

participants are considered beside the document’s own, as if added.

Parameters:
Return type:

dict[str, Any]

vibesketcher.document.solid_reactions.example(name)[source]

A copy of a worked scheme from EXAMPLES.

Parameters:

name (str)

Return type:

dict[str, Any]

vibesketcher.document.solid_reactions.export_refusal(document, fmt)[source]

Why fmt cannot carry the document’s solid reaction scheme; None if it can.

Parameters:
Return type:

str | None

vibesketcher.document.solid_reactions.remove(document, identifiers)[source]

document without these participants and steps.

A participant still used by a step that stays is refused.

Parameters:
Return type:

Document

vibesketcher.document.solid_reactions.report(document)[source]

Participants with resolved formula, charge and sites; steps with their balances.

parents groups participants that share a bulk or slab parent (or structure) while keeping their own IDs.

Parameters:

document (Document)

Return type:

dict[str, Any]