Improve Consistency of Thermo Property Interfaces

[ischoegl]

Abstract

Different Cantera APIs follow different philosophies regarding how thermodynamic properties are exposed and sometimes even differ in nomenclature. In terms of user experience (but also in view of #39), it would be good to come up with a unified approach to access partial/mixture thermo properties (enthalpy, entropy, gibbs, intEnergy, volume, cp), given that there are interfaces for molar, mass-based, non-dimensional, standard-state and reference-state quantities. A more streamlined API would also avoid largely redundant docstring sections.

Motivation

Describe the need for the proposed change:

• What problem is it trying to solve? ... Make APIs uniform and self-explanatory
• Who is affected by the change? ... Users and developers
• Why is this a good solution? ... Maintenance of API-specific approaches makes little sense; streamlined access would clarify different bases available, avoid redundant documentation, and thus improve user experience.

Details

To illustrate the situation, let's take a look at the interface for enthalpy / $h$. For partial quantities, we have:

• C++ - 3 different ThermoPhase methods: getPartialMolarEnthalpies, getEnthalpy_RT and getEnthalpy_RT_ref. Standard (or 'pure') methods defined for other properties are not available, and mass-based quantities that may be relevant to users are not implemented.
• Python - 2 properties: partial_molar_enthalpies and standard_enthalpies_RT
• clib (experimental) - 2 access functions: thermo_getPartialMolarEnthalpies and thermo_getEnthalpies_RT.
• MATLAB (experimental) - 1 property: partialMolarEnthalpies
• F90 (experimental) - 2 access functions: ctthermo_getPartialMolarEnthalpies and ctthermo_getEnthalpies_RT
• .NET (experimental): Not implemented

There is overall an inconsistency for singular/plural use (enhalpy vs enthalpies) with the original C++ method being the outlier, and only the Python interface clarifies that non-dimensional properties are evaluated at the Cantera standard state.

For mixture properties, we have:

• C++ - 2 methods: virtual enthalpy_mole and enthalpy_mass, with the latter calculated from the former; a C++ enumerator Cantera::Thermobasis is defined but not used outside of interfaces for equivalence ratios and stoichiometries.
• Python - 3 properties: enthalpy_mole and enthalpy_base via C++, plus a property h where mass/mole basis depends on a locally defined ThermoPhase.thermo_basis (a C-style enum representing 0 or 1) and a locally defined mole_factor() conversion factor.
• clib (experimental) - 2 access functions: thermo_enthalpy_mole and thermo_enthalpy_mass based on C++
• MATLAB (experimental) - 1 property: combines the two CLib methods into a single property getter for H, which depends on a locally defined basis (a string containing either mass or molar)
• F90 (experimental) - 2 access functions: ctthermo_enthalpy_mole and ctthermo_enthalpy_mass
• .NET (experimental) - 2 properties: MassEnthalpy and MolarEnthalpy (renamed from CLib)

There is no unified approach regarding automatic basis selection, where Python and experimental MATLAB implement custom solutions, while .NET follows C++/CLib more closely but attempts to introduce improved nomenclature. C++ uses snake_case although the default for methods is CamelCase and also doesn't follow the nomenclature for partial properties (<>_mass vs Molar<>).

Beyond, there are additional total properties that are applicable to zeroD objects, which also track mass/mole balances.

Possible Solutions

Resolving this issue involves multiple areas:

1. Ensure that the nomenclature is consistent across all APIs (i.e., singular/plural; use of standard/pure): this involves standard deprecation cycles for all non-experimental APIs
2. Ensure that access to mixture properties follows a single philosophy: decide whether basis should be consolidated with what exists in the C++ layer. The inclusion of total properties should be considered.
3. Decide whether a unified access method for each partial property should be implemented in C++ to allow for more streamlined APIs (this may involve a basis selector with more than 2 entries)

For the last item in particular, a potential extended C++ Cantera::ThermoBasis selector could be based on the following:

enum class ThermoBasis {
    TB_AUTO = -1,
    TB_MASS = 0,
    TB_MOLAR = 1,  // default behavior
    TB_TOTAL = 2,  // useful for zeroD object property access; needs amount of matter
    TB_STANDARD = 3,  // for debugging?
    TB_STANDARD_NONDIM = 4,  // for debugging?
    TB_STANDARD_NONDIM_REF = 5,  // for debugging?
};

where the last three may or may not be exposed (per discussion in Cantera/cantera#522). This extended version would directly map to what exists for partial properties (with missing versions involving trivial conversion). If exposed, the three last items would only serve for debugging purposes and should raise exceptions for mixture properties.

References

• Make Matlab species thermo properties consistent and useful cantera#522
• Reconsider composition state variables for reactors, flames, and other systems #154 ... adoption would create another use case of the TB_TOTAL basis