Skip to content

ChemicalFormula

A class to represent a single chemical formula.

API docs: ChemicalFormula

Formula object initialization

To create a formula object from a string:

from chemsynthcalc import ChemicalFormula

formula_string = "(NH4)2SO4"
formula = ChemicalFormula(formula_string)

Important

The symbols allowed for the ChemicalFormula input string are: a-z A-Z 0-9 . () {} [] * · • whitespace

Whitespaces will be ignored. If there are any other symbols in the string, they will not be ignored, instead InvalidCharacter error will be raised.

All brackets in formula should be paired bracket-type-wise (), {}, []. If not, BracketsNotPaired error will be raised.

Important

Only one adduct (like X*H2O) per formula is allowed. If parser detects more than one adduct symbols (*·•) it will raise MoreThanOneAdduct error.

There is an optional rounding_order (int) parameter for rounding precision:

from chemsynthcalc import ChemicalFormula

formula_string = "(NH4)2SO4"
formula = ChemicalFormula(
    formula = formula_string,
    rounding_order = 8
    )

Formula object properties

After the object initialization, we can access ChemicalFormula properties:

Custom oxides

The oxide_percent property calculates relative percentages of oxides of non-oxygen elements in the formula (tipycally metals). The default oxide formulas are listed in PeriodicTable. One can feed their custom oxide formulas while instantiating an object:

>>> from chemsynthcalc import ChemicalFormula

>>> ChemicalFormula("(NH4)2SO4").oxide_percent
{'NO2': 37.68939937, 'H2O': 29.51742331, 'SO3': 32.79317732}

>>> ChemicalFormula("(NH4)2SO4", "S2O3").oxide_percent
{'NO2': 41.79831326, 'H2O': 32.73542499, 'S2O3': 25.46626175}

Output

A typical ChemicalFormula results output will look like this:

>>> from chemsynthcalc import ChemicalFormula

>>> ChemicalFormula("(NH4)2SO4").print_results()

formula: (NH4)2SO4
parsed formula: {'N': 2.0, 'H': 8.0, 'S': 1.0, 'O': 4.0}
molar mass: 132.134
mass percent: {'N': 21.2012, 'H': 6.1029, 'S': 24.2632, 'O': 48.4327}
atomic percent: {'N': 13.3333, 'H': 53.3333, 'S': 6.6667, 'O': 26.6667}
oxide percent: {'NO2': 37.6894, 'H2O': 29.5174, 'SO3': 32.7932}

One can output ChemicalFormula results using one of the 4 methods: