PyValem: a Python package for parsing chemical formulas and states


PyValem is a Python package, for parsing, representing and manipulating the formulas of simple chemical species, their states and reactions. Its source is available on GitHub under a GPL licence, and it can be installed from the Python Package Index, PyPI, using pip:

pip install pyvalem

Formula objects are instantiated using a simple string-based syntax, and can be rendered in HTML and LaTeX; they also know their mass and number of atoms:

In [x]: from pyvalem.formula import Formula
In [x]: f = Formula('H2O')
In [x]: print(f)                                                               

In [x]: print(f.html)                                                          

In [x]: print(f.latex)                                                         

In [x]: print('The RMM of {} is {} g.mol-1'.format(f, f.rmm))                  
The RMM of H2O is 18.015 g.mol-1

Isotopes and isotopologues are supported:

In [x]: f = Formula('(1H)(79Br)')
In [x]: print('The mass of {} is {:.5f} u.'.format(f, f.mass))
The mass of (1H)(79Br) is 79.92616 u.
In [x]: print(f.html)

Which results in: 1H79Br.

Even moderately complex charged species such as the (S)-Asparagine zwitterion can be represented:

In [x]: asn = Formula('H2NCOCH2CH(NH3+)CO2-')
In [x]: print('{} atoms, RMM = {} g.mol-1'.format(asn.natoms, asn.rmm))        
17 atoms, RMM = 132.119 g.mol-1

In [x]: print(asn.html)

which renders as:


The StatefulSpecies class represents a chemical species associated with one or more quantum states, of which several types are defined:

In [x]: from pyvalem.stateful_species import StatefulSpecies
In [x]: s = StatefulSpecies('Hg+ [Xe].4f14.5d10.6s1; 2S_1/2') 
In [x]: print(s.html)                                                          
Hg<sup>+</sup> [Xe]4f<sup>14</sup>5d<sup>10</sup>6s<sup>1</sup>; <sup>2</sup>S<sub>1/2</sub>

Hg+ [Xe]4f145d106s1; 2S1/2

Reactions are also supported:

In [x]: from pyvalem.reaction import Reaction
In [x]: r = Reaction('2C8H18 + 25O2 -> 16CO2 + 18H2O')
In [x]: print(r.html)
2C<sub>8</sub>H<sub>18</sub> + 25O<sub>2</sub>  16CO<sub>2</sub> + 18H<sub>2</sub>O

which produces: 2C8H18 + 25O2 → 16CO2 + 18H2O. Another example:

In [x]: r.reactants                                                            
Out[x]: [(1, Ar *), (1, e-)]

In [x]: r.products                                                             
Out[x]: [(1, Ar+), (2, e-)]

In [x]: print(r.latex)                                                         
\mathrm{Ar} \; * + $e^-$ \rightarrow \mathrm{Ar}^{+} + 2$e^-$

In [x]: print(r.html)                                                          
Ar <sup>*</sup> + e<sup>-</sup>  Ar<sup>+</sup> + 2e<sup>-</sup>

which is: Ar * + e- → Ar+ + 2e-.

Charge and stoichiometry must be conserved:

In [x]: Reaction('HCl + e- -> HCl+ + e-')
ReactionChargeError: Charge not preserved for reaction: HCl + e- -> HCl+ + e-

In [x]: Reaction('C6H6 + HNO3 -> C6H5NO2 + H2O')    # OK
In [x]: Reaction('C6H6 + HNO3 -> C6H5NO2 + H2O2')
ReactionStoichiometryError: Stoichiometry not preserved for reaction: C6H6 + HNO3 -> C6H5NO2 + H2O2
Currently unrated


Comments are pre-moderated. Please be patient and your comment will appear soon.

There are currently no comments

New Comment


required (not published)