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 |
|
---|---|---|
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)” |
Phosphate Ion | “PO4-3”, “PO₄³⁻” | “PO4[-3]” |
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]
There is one exception to the rule above. If you really want to list the charge number first , you can use unicode superscript characters (e.g., “Co²⁺”), and pyEQL
will understand these regardless of the order of the +
and the 2
. So you can write “Co²⁺” and it will be correctly standardized to Co[+2]
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 asstandardize_formula
can understand it (see manual testing).The keys (solute formulas) in
Solution.components
are standardized. So if you enteredNa+
for sodium ion, it will appear incomponents
asNa[+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 incomponents
:>>> 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. WhenpyEQL
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).