vibesketch.document.electrochem

Electrochemical half-reactions: electrons, states, coefficients and potentials (#141).

An electrode reaction is drawn like any reaction, with what SMILES cannot say written as text, and read from the drawing like the rest of it:

• electrons, 2e⁻ (also 2 e- or 2e−), drawn on a side among the participants, or at the arrow as + 2e⁻ (taken up, a reactant) or − 2e⁻ (given off, a product);

• a state, (s), (l), (g), (aq) or (ads), or the asterisk of an adsorbed species, just right of a participant;

• a coefficient, such as the 2 of 2H2O, just left of a participant;

• conditions at the arrow that read as a value and a unit: a potential with its reference electrode (−1.2 V vs Ag/AgCl (3 M KCl), SHE, NHE, SCE, RHE), pH 7.4, a temperature in °C or K, a time.

The texts stay in the drawing, so figures print them as drawn. The balance check counts atoms (implicit hydrogens included) and charge, with each participant’s coefficient and the electrons’ charge of −1 each, and reports what does not match; it never changes the reaction.

Module Attributes

FARADAY

exact, from e and N_A).

Functions

balance(document, reaction_id)	Atoms and charge on each side of a reaction, with the electrons, and the imbalance.
describe(report)	One line saying whether a reaction balances, and if not, by how much.
electron_text(text)	A text that writes electrons as its sign and count, or None.
half_reaction_canvas(reactants, products, *)	A KET drawing of a half-reaction, laid out in a row as the derivation reads it.
quantities(lines)	The conditions among lines that read as a value with its unit.
read_half_reaction(scene, arrow, sides, ...)	The electrons, states and coefficients drawn for one step, and warnings.
widened(scene)	scene with each molecule's box taken out over its coefficient and state texts.
with_half_reaction(document, reactants, ...)	document with a half-reaction drawn beside its drawing, derived, and the warnings.

Classes

BalanceReport

A reaction's atom and charge balance: what each side holds and what does not match.

Exceptions

HalfReactionRefused

A half-reaction that cannot be drawn as asked; the message says why.

vibesketch.document.electrochem.FARADAY = 96485.33212

exact, from e and N_A).

Type:

The Faraday constant, C/mol (CODATA 2018

class vibesketch.document.electrochem.BalanceReport

Bases: dict[str, Any]

A reaction’s atom and charge balance: what each side holds and what does not match.

exception vibesketch.document.electrochem.HalfReactionRefused

Bases: ValueError

A half-reaction that cannot be drawn as asked; the message says why.

vibesketch.document.electrochem.balance(document, reaction_id)

Atoms and charge on each side of a reaction, with the electrons, and the imbalance.

Reagents drawn at the arrow are not counted. A side’s count is the sum of coefficient times atoms, and of coefficient times charge, less one per electron on that side. balanced is true only when every element and the charge match. Raises KeyError for an unknown reaction.

Parameters:

• document (Document)

• reaction_id (str)

Return type:

BalanceReport

vibesketch.document.electrochem.describe(report)

One line saying whether a reaction balances, and if not, by how much.

Parameters:

report (BalanceReport)

Return type:

str

vibesketch.document.electrochem.electron_text(text)

A text that writes electrons as its sign and count, or None.

Parameters:

text (str)

Return type:

tuple[str | None, int] | None

vibesketch.document.electrochem.half_reaction_canvas(reactants, products, *, electrons=None, conditions=(), arrow='forward', over=())

A KET drawing of a half-reaction, laid out in a row as the derivation reads it.

A participant is a SMILES or {smiles, coefficient, state}; coefficients are drawn before it and states after it, the electrons {count, side, at_arrow} as 2e⁻ among the participants of their side or, with at_arrow, as + 2e⁻ or − 2e⁻ above the arrow, and the conditions below it. A participant may also be a solid {formula, coefficient, state} (#142), drawn as its formula. over are drawn above the arrow as reagents: a solid catalyst {formula} or a SMILES. Raises HalfReactionRefused.

Parameters:

• reactants (Sequence[Any])

• products (Sequence[Any])

• electrons (dict[str, Any] | None)

• conditions (Sequence[str])

• arrow (str)

• over (Sequence[Any])

Return type:

dict[str, Any]

vibesketch.document.electrochem.quantities(lines)

The conditions among lines that read as a value with its unit.

Parameters:

lines (Sequence[str])

Return type:

list[Quantity]

vibesketch.document.electrochem.read_half_reaction(scene, arrow, sides, species_of, used)

The electrons, states and coefficients drawn for one step, and warnings.

sides are the step’s reactant, reagent and product fragments; species_of maps a fragment to its species; texts read here are added to used so they do not become condition lines.

Parameters:

• scene (KetScene)

• arrow (KetArrow)

• sides (tuple[list[int], list[int], list[int]])

• species_of (dict[int, str])

• used (set[int])

Return type:

tuple[dict[str, Any], list[str]]

vibesketch.document.electrochem.widened(scene)

scene with each molecule’s box taken out over its coefficient and state texts.

So a plus sign between 2 H⁺(aq) and its neighbour joins them as it joins bare molecules; only the boxes change, never which texts there are.

Parameters:

scene (KetScene)

Return type:

KetScene

vibesketch.document.electrochem.with_half_reaction(document, reactants, products, *, electrons=None, conditions=(), arrow='forward', over=())

document with a half-reaction drawn beside its drawing, derived, and the warnings.

See half_reaction_canvas(). Raises HalfReactionRefused.

Parameters:

• document (Document)

• reactants (Sequence[Any])

• products (Sequence[Any])

• electrons (dict[str, Any] | None)

• conditions (Sequence[str])

• arrow (str)

• over (Sequence[Any])

Return type:

tuple[Document, list[str]]