Clip species compositions to improve robustness

[jbscoggi]

General description

Species compositions such as mole/mass fractions, densities, or number densities are required throughout M++ in order to compute many different properties of a mixture. There is a growing consensus that the compositions should be clipped in order to improve the robustness of some algorithms. This should be done at a low level to ensure consistency throughout.

Detailed description

I propose to clip the species mole fractions to a lower bound, which can be changed as input from the user in the mixture file. Whenever a species composition is either given by the user, or computed from an equilibrium calculation, the species mole fractions would be clipped, and any other form of the composition should be set consistent with those mole fractions. For example, if the following mole fractions are given:

Species	Mole Fraction
N	0.0
O	0.0
NO	0.0
N2	0.8
O2	0.2

then the mole fractions saved internally would be set to

Species	Mole Fraction
N	tol
O	tol
NO	tol
N2	0.8
O2	0.2

where tol is the tolerance set by the user (default of 1.0e-16). The corresponding mass fractions or species densities would then be evaluated according to the updated mole fractions to ensure consistency throughout.

Modifications to current behavior

• Add a new function in StateModel base to apply the tolerance on mole fractions and update other quantities in a consistent way.
• Change all setState functions to make use of the tolerance.
• Can remove all other mole/mass fraction clipping that is already in place throughout the rest of the library in order to clean up the code.

Examples to use for testing

• Check both setState and equilibrate to make sure it works at a low enough level.
• Also test changing the default lower bound to make sure this is effective.

[jbscoggi]

After some offline discussion, we don't feel this is a must-have for v1.0.0, so I'm removing the milestone.

[mgoodson-cvd]

Just as a warning to others, I've encountered two places where a mass fraction of zero will produce a division by zero:

• in the Gupta-Yos viscosity algorithm, here
• in Park's correction to the Millikan-White relaxation time, here

My solution is to clip the mass fractions before passing to Mutation++, which seems preferable to clipping inside Mutation++. I would be very confused as a user if I passed in mass fractions of zero and got back non-zero mole fractions, for example.