Resolve "Check that chemical equations are balanced"

Closes #231 (closed)

changed milestone to %Atomistic and molecular modeling language advanced

added Constraints Documentation Feature Interpreter Testing labels

assigned to @ivan.kondov

added 258 commits

• 8e4e8aae...ebcef76d - 257 commits from branch master
• 2e5145c5 - add composition attribute to species, static constraints, example

Compare with previous version

added 17 commits

• 2e5145c5...4c75736d - 16 commits from branch master
• 5c72b70f - Merge branch 'master' of https://gitlab.kit.edu/kit/virtmat-tools/vre-language...

Compare with previous version

requested review from @rodrigo.mejia

After evaluating the example, the command print(H2O) gives the following output:

 Species H2O : ((energy: 0.0) [electron_volt], (entropy: 0.0021669) [electron_volt / kelvin], (zpe: 0.558) [electron_volt], (temperature: 298.15) [kelvin], (enthalpy: 0.558) [electron_volt], (free_energy: -0.08806123499999985) [electron_volt])

The composition is not provided as part of the output.

So, the only way to activate the balance check is by having the composition of all species. If the composition of one of the species is omitted, then the model runs seemingly normal. But in such cases there is no balance check, and one can get away with nonesense such as:

orr_total = Reaction 1 H2 + O2 = 9 H2O

H2O = Species H2O, composition: 'HHO' (
      ...)

H2 = Species H2 (
     ...)

orr_free = -4.916 [eV]
O2 = Species O2, composition: 'O2' (
     ...)

And the result is printed

Reaction 1 H2 + 1.0 O2 = 9 H2O : ((free_energy: -5.668300239999999) [electron_volt])

A word of caution about the requisites of the balance checker is needed in the docs.

A composition is not strictly limited to formal chemical formulas. These both work H2O and HHO. As long as all atoms are included it does not care about ordering or chemical formula formalities, which makes sense for robustness, I guess.

The ordering plays no role. Because the composition is returned by the chemparse package in a dictionary, the number of atoms of elements are accumulated independent of ordering. This is important because several different orderings are supported in ASE that can be returned though we only use the default Hill notation in structure.chemical_formula. In the mean time, I came across the ASE Formula class that might be an equivalent/compatible replacement for the chemparse package.

added 2 commits

• d5bc56a4 - composition as reference to string; fixed deferred eval, serializer and formatter
• d9ebd73f - species composition type check and two tests

Compare with previous version

added 1 commit

• 65383d7e - issue a warning in the case the reaction balance cannot be checked

Compare with previous version

added 1 commit

• 58e5eaf7 - replace raise_exception() + error_handler with issue_warning()

Compare with previous version

added 2 commits

• 96ddf46e - revert changed view module
• 0acb3fda - replaced chemparse with ase.formula

Compare with previous version

Interesting that the input for a Reaction object should be constructed using the names of the variables cotaining the Species, but the printing a Reaction returnsspecies.name:

Input > h2o = Species water, composition: 'HHO' ((energy: 0.0)[eV])
Input > H2 = Species H2, composition: 'H2' ((energy:1.0)[eV])
Input > O2 = Species O2, composition: 'O2' ((energy:2.0)[eV])
Input > orr_total = Reaction 2 H2 + O2 = 2 h2o
Input > print(orr_total)

OUTPUT > Reaction 2 H2 + 1.0 O2 = 2 water

The docs state:

The individual educts and products must be separated by a + sign and must be references to defined species.

Wouldn't it be better if the text mentioned that the reference needs to be strictly to the variable cotaining the Species?