Writing Formulas

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 property 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 interpret it. Internally, pyEQL uses a utility function pyEQL.utils.standardize_formula to process all formulas into a standard form. At present, this is done by passing the formula through the pymatgen.core.ion.Ion class. Anything that the Ion class can understand will be processed into a valid formula by pyEQL.

Here are some examples:

Substance	You enter	pyEQL understands
Sodium Chloride	“NaCl”, “NaCl(aq)”, or “ClNa”	“NaCl(aq)”
Sodium Sulfate	“Na2(SO4)” or “Na2SO4”	“Na(SO4)(aq)”
Sodium Ion	“Na+”, “Na+1”, “Na1+”, or “Na[+]”	“Na[+1]”
Magnesium Ion	“Mg+2”, “Mg++”, or “Mg[++]”	“Mg[+2]”
Methanol	“CH3OH”, “CH4O”	“‘CH3OH(aq)’”

Specifically, standardize_formula uses Ion.from_formula(<formula>).reduced_formla (shown in the right hand column of the table) to identify solutes. Notice that for charged species, the charges are always placed inside square brackets (e.g., Na[+1]) and always include the charge number (even for monovalent ions). Uncharged species are always suffixed by (aq) to disambiguate them from solids.

Important

When writing multivalent ion formulas, it is strongly recommended that you put the charge number AFTER the + or - sign (e.g., type “Mg+2” NOT “Mg2+”). The latter formula is ambiguous - it could mean \(Mg_2^+\) or \(Mg^{+2}\) and it will be processed incorrectly into Mg[+0.5]

Manually testing a formula

If you want to make sure pyEQL is understanding your formula correctly, you can manually test it as follows:

>>> from pyEQL.utils import standardize_formula
>>> standardize_formula(<your_formula>)
...

Formulas you will see when using Solution

When using the Solution class,

• When creating a Solution, you can enter chemical formulas in any format you prefer, as long as standardize_formula can understand it (see manual testing).

• The keys (solute formulas) in Solution.components are standardized. So if you entered Na+ for sodium ion, it will appear in components as Na[+1].

• However, the components attribute is a special dictionary that automatically standardizes formulas when accessed. So, you can still enter the formula however you want. For example, the following all access or modify the same element in components:

  >>> Solution.components.get('Na+')
  >>> Solution.components["Na+1"]
  >>> Solution.components.update("Na[+]": 2)
  >>> Solution.components["Na[+1]"]
  

• Arguments to Solution.get_property can be entered in any format you prefer. When pyEQL queries the database, it will automatically standardize the formula.

• Property data in the database is uniquely identified by the standardized ion formula (output of Ion.from_formula(<formula>).reduced_formla, e.g. “Na[+1]” for sodium ion).