Chemmisol library

Introduction

The purpose of the chemmisol library is to provide a performant and portable chemical equilibrium solver.

It is widely inspired from VMinteq. Chemmisol adds a strong focus on dynamic equilibrium solving, that allows to define a system, solve its equilibrium, modify concentrations of species from the current equilibrium, solve the equilibrium again and so on.

About units

Chemmisol defines a unit system inspired from GAMA units.

However, even if very useful when directly using the library, the unit system might be problematic when attempting to embed the library in other systems or languages.

In order to solve those issues, it is necessary to enforce the specification of the unit system used by chemmisol.

Any quantity specified with units is converted internally to a value that corresponds to the same value expressed in the core unit of the same category.

In consequence, it is safe to use raw values without units in chemmisol, as long as it can be ensure that it's value corresponds to a value expressed in a core unit.

Internally, core units corresponds to UNITS() with a value of 1.

For example, the core unit for volumes is the liter l. This means that the value 1.5*l is represented internally by 1.5f, while 1.2*cm3 is represented as 1.2 * 10-3 = 1.2e-3f. The interest of this system is that unit conversion is automatically performed by the library. For example, it is perfectly possible to write double distance = 1*km + 15*m without bothering about unit conversion (in this example, distance is automatically converted to the core unit m with a value of 1015.0). Considering the definition of core units, specifying directly double distance = 1015.0 is equivalent in chemmisol.

A value defined with a chemmisol unit can still be expressed in an other unit, dividing the value by the desired unit. For example:

double distance = 1*km + 15*m;
std::cout << "Distance in km: " << distance/km << std::endl;

The following table sums up all the core units used by chemmisol:

Use case	Unit
Distance	m
Surface	m2
Volume	l
Mass	g
Quantity	mol

The core unit of derived units can be obtained with the same expression as the derived unit expressed in core units. For example, the core unit for molar concentrations is mol/l.

Example

ChemicalSystem chemical_system {
  2.5 * g/l,
  24.2 * m2/g,
  0.8 * entities/nm2,
  "=SOH"
};

is equivalent to

*ChemicalSystem chemical_system {
    2.5,
    24.2,
    0.8 / 6.02214076e23 * 1e18, // Manual conversion from entities/nm2 to mol/m2
    "=SOH"
  };

Warning

Even if the unit system is inspired from GAMA units, it is not guaranteed that the same core units are used. In consequence, a GAMA raw value cannot be used directly in chemmisol, and must be converted to chemmisol core units using the unit system of GAMA.