Chemical Formulas

Representing Chemical Substances in pyEQL

pyEQL interprets the chemical formula of a substance to calculate its molecular weight and formal charge. The formula is also used as a key to search the database for parameters (e.g. diffusion coefficient) that are used in subsequent calculations.

How to Enter Valid Chemical Formulas

Generally speaking, type the chemical formula of your solute the “normal” way and pyEQL should be able to inerpret it. Here are some examples:

  • Sodium Chloride - NaCl
  • Sodium Sulfate - Na(SO4)2
  • Methanol - CH4OH or CH5O
  • Magnesium Ion - Mg+2
  • Chloride Ion - Cl-

Formula Rules:

  1. Are composed of valid atomic symbols that start with capital letters
  2. Contain no non-alphanumeric characters other than ‘(‘, ‘)’, ‘+’, or ‘-‘
  3. If a ‘+’ or ‘-‘ is present, the formula must contain ONLY ‘+’ or ‘-‘ (e.g. ‘Na+-‘ is invalid) and the formula must end with either a series of charges (e.g. ‘Fe+++’) or a numeric charge (e.g. ‘Fe+3’)
  4. Formula must contain matching numbers of ‘(‘ and ‘)’
  5. Open parentheses must precede closed parentheses

Alternate Formulas and Isomers

Many complex molecules can be written in multiple ways. pyEQL cares only about the number and identity of the elements and the formal charge on the molecule, so you can use any form you choose. The hill_order() method takes a formula and reduces it to its simplest form, like so:

>>> pyEQL.chemical_formula.hill_order('CH2(CH3)4COOH')
'C6H15O2'

When searching the parameters database, pyEQL uses this method to reduce both user-entered formulas AND keys in the database. So even if you created a solution containing ‘ClNa’, pyEQL would still match it with parameters for ‘NaCl’.

Currently pyEQL does not distinguish between isomers.

API Documentation (chemical_formula.py)

This module contains classes, functions, and methods to facilitate the input, output, and parsing of chemical formulas for pyEQL.

The correct case must be used when specifying elements.

copyright:2013-2015 by Ryan S. Kingsbury
license:LGPL, see LICENSE for more details.
pyEQL.chemical_formula.get_element_names(formula)

Return the names of the elements in a chemical formula

Parameters:

formula: str

String representing a chemical formula

Examples

>>> get_element_names('FeSO4')
['Iron', 'Sulfur', 'Oxygen']
pyEQL.chemical_formula.get_element_numbers(formula)

Return the atomic numbers of the elements in a chemical formula

Parameters:

formula: str

String representing a chemical formula

Examples

>>> get_element_numbers('FeSO4')
[26, 16, 8]
pyEQL.chemical_formula.get_elements(formula)

Return a list of strings representing the elements in a molecular formula, with no duplicates.

See also

_check_formula

Examples

>>> get_elements('FeSO4')
['Fe', 'S', 'O']
>>> get_elements('CH3(CH2)4(CO)3')
['C', 'H', 'O']
pyEQL.chemical_formula.get_formal_charge(formula)

Return the formal charge on a molecule based on its formula

See also

_check_formula

Examples

>>> get_formal_charge('Na+')
1
>>> get_formal_charge('PO4-3')
-3
>>> get_formal_charge('Fe+++')
3
pyEQL.chemical_formula.get_molecular_weight(formula)

compute the molecular weight of a formula

>>> get_molecular_weight('Na+')
22.98977
>>> get_molecular_weight('H2O')
18.01528
>>> get_molecular_weight('CH3CH2CH3')
44.09562

See also

_consolidate_formula, elements

pyEQL.chemical_formula.hill_order(formula)

Return a string representing the simplest form of ‘formula’ in the Hill order (Carbon, Hydrgen, then other elements in alphabetical order). If no Carbon is present, then all elements are listed in alphabetical order.

NOTE: this function does NOT (yet) honor exceptions to the Hill Order for acids, hydroxides, oxides, and ionic compounds. It follows the rule above no matter what.

Examples

>>> hill_order('CH2(CH3)4COOH')
'C6H15O2'

>>> hill_order('NaCl')
'ClNa'

>>> hill_order('NaHCO2') == hill_order('HCOONa')
True

>>> hill_order('Fe+2') == hill_order('Fe+3')
False
pyEQL.chemical_formula.is_valid_element(formula)

Check whether a string is a valid atomic symbol

Parameters:

:formula: str

String representing an atomic symbol. First letter must be uppercase, second letter must be lowercase.
Returns:

bool

True if the string is a valid atomic symbol. False otherwise.

Examples

>>> is_valid_element('Cu')
True
>>> is_valid_element('Na+')
False
pyEQL.chemical_formula.is_valid_formula(formula)

Check that a molecular formula is formatted correctly

Parameters:

formula: str

String representing a molecular formula. e.g. ‘H2O’ or ‘FeOH+’ Valid molecular formulas must meet the following criteria:

  1. Are composed of valid atomic symbols that start with capital letters
  2. Contain no non-alphanumeric characters other than ‘(‘, ‘)’, ‘+’, or ‘-‘
  3. If a ‘+’ or ‘-‘ is present, the formula must contain ONLY ‘+’ or ‘-‘ (e.g. ‘Na+-‘ is invalid) and the formula must end with either a series of charges (e.g. ‘Fe+++’) or a numeric charge (e.g. ‘Fe+3’)
  4. Formula must contain matching numbers of ‘(‘ and ‘)’
  5. Open parentheses must precede closed parentheses
Returns:

bool

True if the formula is valid. False otherwise.

Examples

>>> is_valid_formula('Fe2(SO4)3')
True
>>> is_valid_formula('2Na+')
False
>>> is_valid_formula('HCO3-')
True
>>> is_valid_formula('Na+-')
False
>>> is_valid_formula('C10h12')
False
pyEQL.chemical_formula.print_latex(formula)

Print a LaTeX - formatted version of the formula

Examples

>>> print_latex('Fe2SO4')
Fe_2SO_4
>>> print_latex('CH3CH2CH3')
CH_3CH_2CH_3
>>> print_latex('Fe2(OH)2+2')
Fe_2(OH)_2^+^2