adrianusler/massaction

A python package for the numerical solution of mass-action laws with constraints for the description of chemical reactions.

massaction

A python package for the numerical solution of mass-action laws with constraints for the description of chemical reactions.

Installation

The easiest way to install massaction is from PyPi using pip.

pip install massaction

Usage

The major perk of massaction is the simple syntax in which one can set up the description of a chemical equilibrium. For instance, the mass-action law for the oxyhydrogen reaction may be set up in just a few lines of Python code:

from massaction.model import ChemModel

mymodel = ChemModel(3) # set up a model with 3 chemical species
h2o, h2, o2 = mymodel.get_all_species() # give names to the species objects

# first set up the reaction equation, then define constraints to ensure atom balance
reaction = h2 + o2 >> 2*h2o
ln_equilibrium_constant = 20. # arbitrary units
constraint_hydrogen = 2*h2 + 2*h2o == 1.0 # arbitrary units
constraint_oxygen = h2o + 2*o2 == 10.0 # arbitrary units

# now solve the system of equations to obtain an array with the natural logarithm of the concentrations
ln_concentrations = mymodel.solve( [reaction], [ln_equilibrium_constant], [constraint_hydrogen, constraint_oxygen] )

The resulting array ln_concentrations is array([ -0.69314718, -22.94443898, 1.55814462]), which contains the entries $\ln\left(c(\mathrm{H_2O})\right)$, $\ln\left(c(\mathrm{H_2})\right)$, and $\ln\left(c(\mathrm{O_2})\right)$, respectively.

massaction's Issues

Implement ConstraintList

Take for instance in an equilibrium of a solid oxide with a surrounding atmosphere:
$\mathrm{\frac12 O_2 + v_O^{\bullet\bullet} + 2 e^\prime} \rightleftharpoons \mathrm{O_O^\times}$
Typically, one would then like to vary a thermodynamic parameter (e.g., $T$ or $p\mathrm{O_2}$). This should work by defining a constraint with a list/array of values, for instance

o2==np.logspace(-10, 0, 100)

In such a case, a ConstraintList object should be instantiated, and the model.solve(...) routine should know how to handle this.

Add minimal usage example to README.md

Handle problems that arise when FactorSpecies.factor is zero

Increase test coverage

Implement "nil" as a new syntax element

Currently, one has to define "nil" as a species and then apply a constraint to it.
Example: Electron/hole pair formation
$\mathrm{nil \rightleftharpoons e^\prime + h^\bullet}$
This requires that an extra species is defined in the ChemModel instantiation and then one must apply the constraint
nil==1

Instead, there should be some kind of an object called nil that makes this unnecessary.

Increase test coverage

Implement sweep of equilibrium constants

Add demos

Create a demos folder with example scripts for

• Acid / Base chemistry
  • $\mathrm{AH\rightleftharpoons H^+ + A^-}$ (dissociation of an acid)
  • $\mathrm{nil\rightleftharpoons H^+ + OH^-}$ (autoprotolysis of water)
  • Dissociation of an acid & autoprotolysis: $\mathrm{H^+}$, $\mathrm{OH^-}$, and $\mathrm{A^-}$
  • Titration of an acid with a base (constraint sweep): $\mathrm{AH}$, $\mathrm{A^-}$, $\mathrm{B}$, $\mathrm{BH^+}$
  • Titration of an acid with a base & autoprotolysis: $\mathrm{AH}$, $\mathrm{A^-}$, $\mathrm{B}$, $\mathrm{BH^+}$, $\mathrm{H^+}$, $\mathrm{OH^-}$
• Kröger–Vink defect chemistry (solid state)
  • Schottky disorder in $\mathrm{MO_2}$
  • Oxygen incorporation in acceptor-doped oxide
  • Ox. incorp. + electron/hole pair formation in acceptor-doped oxide

Implement activity coefficients

Requires an infrastructure for defining mathematical expressions.