vibesketch.chem.formula

Chemical formulas of solids that have no molecular graph (#142).

Oxides, salts, catalysts and scales are written as formulas, not drawn as structures: Fe2O3, Pb3(CO3)2(OH)2, CuSO4·5H2O, a variable or doped composition such as Fe3−xCrxO4 or CoAlxOy, a composite such as AlOx–Fe2O3, with an optional polymorph (γ-Al2O3) and state ((s)). This module reads such a formula into its composition, the canonical form that identifies it, and, when every count is a number, its molar mass with the atomic weights RDKit gives the species report.

Grammar, informally: [polymorph-]phase[–phase…][(state)], a phase being groups and elements each with an optional count, hydrate parts after · (or ./*) with a leading multiplier, and a count a number, a variable (x, y, z or δ), or a number with a variable added or taken away (3−x).

Functions

is_solid_text(text)	The formula a canvas text writes for a solid, or None.
parse_formula(text)	Read a formula; raises FormulaError for anything else.

Classes

Formula(text, phases[, polymorph, state, ...])

A formula read: its phases' compositions, polymorph and state.

Exceptions

FormulaError

Text that is not a formula this module reads; the message says where.

class vibesketch.chem.formula.Formula(text, phases, polymorph=None, state=None, written=())

Bases: object

A formula read: its phases’ compositions, polymorph and state.

Parameters:

• text (str)

• phases (tuple[dict[str, float | str], ...])

• polymorph (str | None)

• state (str | None)

• written (tuple[str, ...])

text: str

phases: tuple[dict[str, float | str], ...]

polymorph: str | None = None

state: str | None = None

written: tuple[str, ...] = ()

Each phase as written, for display.

property numeric: bool

property composition: dict[str, float | str]

The elements of all phases together; a variable count keeps its expression.

canonical()

Each phase in Hill order, phases joined by a dash: what identifies the solid.

A variable count is kept in parentheses, Fe3−xCrxO4 as Cr(x)Fe(3-x)O4.

Return type:

str

key()

The canonical formula with polymorph and state: γ-Al2O3(s).

Return type:

str

molar_mass()

g/mol from RDKit’s atomic weights, or None with a variable count.

Return type:

float | None

monoisotopic_mass()

g/mol from each element’s most common isotope, or None with a variable count.

Return type:

float | None

counts()

Atoms per formula unit, or None with a variable count.

Return type:

dict[str, float] | None

exception vibesketch.chem.formula.FormulaError

Bases: ValueError

Text that is not a formula this module reads; the message says where.

vibesketch.chem.formula.is_solid_text(text)

The formula a canvas text writes for a solid, or None.

Only a whole text that is a formula marked as a solid counts: with the state (s) or a polymorph, so that conditions such as NaOH or H2O at an arrow keep their meaning.

Parameters:

text (str)

Return type:

Formula | None

vibesketch.chem.formula.parse_formula(text)

Read a formula; raises FormulaError for anything else.

Parameters:

text (str)

Return type:

Formula