Abstract

The aim of this enhancement is to improve the organization of thermo data within YAML "species" entries to allow better re-use with multiple phase thermo models and simplify serialization. Comments on the possible solutions would be greatly appreciated.

Motivation

Two problematic cases have been identified with how the species entries are currently organized. One comes from a discussion on Cantera/cantera#641 about how to store model-specific parameters for multiple models (i.e. Redlich-Kwong and Peng-Robinson coefficients) with a single species definition. The other was one I noticed while working on the implementation of #11, which is that (a) species data needed by the ThermoPhase is almost always in the equation-of-state field, with the exception of several fields used in the Debye-Huckel model and (b) we are using the equation-of-state field both for setting up ThermoPhase objects and for setting up PDSS objects.

Two species definitions for illustration:

- name: H2  # species for Redlich-Kwong phase
  composition: {H: 2}
  thermo:
    model: NASA7
    temperature-ranges: [200.0, 1000.0, 3500.0]
    data:
    - [2.34433112, 0.00798052075, -1.9478151e-05, 2.01572094e-08, -7.37611761e-12,
      -917.935173, 0.683010238]
    - [3.3372792, -4.94024731e-05, 4.99456778e-07, -1.79566394e-10, 2.00255376e-14,
      -950.158922, -3.20502331]
  equation-of-state:
    model: Redlich-Kwong
    units: {length: cm, pressure: bar, quantity: mol}
    a: [3.0e+08, -3.30e+06]
    b: 31.0
- name: NaCl(aq)  # species for Debye-Huckel phase
  composition: {Na: 1, Cl: 1}
  thermo:
    model: piecewise-Gibbs
    h0: -96.03E3 cal/mol
    dimensionless: true
    data: {298.15: -174.5057463, 333.15: -174.5057463}
  equation-of-state:
    model: constant-volume
    molar-volume: 1.3
  electrolyte-species-type: weak-acid-associated  # top-level field used only by Debye-Huckel
  weak-acid-charge: -1.0  # top-level field used only by Debye-Huckel

Possible Solutions

There are several possible solutions, with different pros and cons. In the examples below, the thermo field for each species has been elided for simplicity.

Update: Based on the discussion with @ischoegl some of the pros/cons have been updated, and a 4th option has been introduced. I think the newly-introduced Option 4 is my current preference.

Option 1: Allow equation-of-state to be a list, and put all phase-specific thermo data an entry in this list

- name: H2  # species for Redlich-Kwong phase
  composition: {H: 2}
  equation-of-state:
  - model: Redlich-Kwong
    units: {length: cm, pressure: bar, quantity: mol}
    a: [3.0e+08, -3.30e+06]
    b: 31.0
  - model: Peng-Robinson
    units: {length: cm, pressure: bar, quantity: mol}
    a: [2.1e+08, -4.50e+06]
    b: 27.0
- name: NaCl(aq)  # species for Debye-Huckel phase
  composition: {Na: 1, Cl: 1}
  equation-of-state:
  - model: constant-volume
    molar-volume: 1.3
  - model: Debye-Huckel
    electrolyte-species-type: weak-acid-associated
    weak-acid-charge: -1.0

Pros:

• No change required for species with only a single equation-of-state field
• Suggests a parallel route to enabling multiple sets of species transport data

Cons:

• Implementation complexity due to intermingling of data for setting up both ThermoPhase and PDSS models, and due to the fact that the equation-of-state field can be either a map or a list of maps.
• Introduces strange behavior for the Debye-Huckel model, where two equation-of-state entries are used simultaneously
• Mis-categorizes Debye-Huckel species thermo data, which isn't really used to define the equation of state

Option 2: Make equation-of-state a map of maps

- name: H2  # species for Redlich-Kwong phase
  composition: {H: 2}
  equation-of-state:
    Redlich-Kwong:
      units: {length: cm, pressure: bar, quantity: mol}
      a: [3.0e+08, -3.30e+06]
      b: 31.0
    Peng-Robinson:
      units: {length: cm, pressure: bar, quantity: mol}
      a: [2.1e+08, -4.50e+06]
      b: 27.0
- name: NaCl(aq)  # species for Debye-Huckel phase
  composition: {Na: 1, Cl: 1}
  equation-of-state:
    constant-volume:
      molar-volume: 1.3
    Debye-Huckel:
      electrolyte-species-type: weak-acid-associated
      weak-acid-charge: -1.0

Pros:

• Simpler implementation than option 1 due to consistent data structure

Cons:

• Introduces an extra layer of nesting required, even though for most species there will only be one item in equation-of-state map.
• Inconsistent with the current structure of the transport and thermo nodes
• Requires changes to all existing files that use the equation-of-state field
• Introduces strange behavior for the Debye-Huckel model, where two equation-of-state entries are used simultaneously
• Mis-categorizes Debye-Huckel species thermo data, which isn't really used to define the equation of state

Option 3: Use equation-of-state only for PDSS setup, and use a per-model top level field for phase-specific data

- name: H2  # species for Redlich-Kwong phase
  composition: {H: 2}
  Redlich-Kwong:
    units: {length: cm, pressure: bar, quantity: mol}
    a: [3.0e+08, -3.30e+06]
    b: 31.0
  Peng-Robinson:
    units: {length: cm, pressure: bar, quantity: mol}
    a: [2.1e+08, -4.50e+06]
    b: 27.0
- name: NaCl(aq)  # species for Debye-Huckel phase
  composition: {Na: 1, Cl: 1}
  equation-of-state:
    model: constant-volume
    molar-volume: 1.3
  Debye-Huckel:
    electrolyte-species-type: weak-acid-associated
    weak-acid-charge: -1.0

Pros:

• Separation of ThermoPhase and PDSS parameters makes implementation straightforward

Cons:

• Requires changes for some existing files (mostly those using these two phase models)
• Equation of state data ends up specified in two different ways depending on what should be considered an implementation detail (whether or not the phase uses the PDSS model)

Option 4: Allow lists in the equation-of-state section for multiple sets of equation of state parameters, of which one will be used with a particular phase. Create a new top-level key for Debye-Huckel parameters. This is a mix of options 1 and 3.

- name: H2  # species for Redlich-Kwong phase
  composition: {H: 2}
  equation-of-state:
  - model: Redlich-Kwong
    units: {length: cm, pressure: bar, quantity: mol}
    a: [3.0e+08, -3.30e+06]
    b: 31.0
  - model: Peng-Robinson
    units: {length: cm, pressure: bar, quantity: mol}
    a: [2.1e+08, -4.50e+06]
    b: 27.0
- name: NaCl(aq)  # species for Debye-Huckel phase
  composition: {Na: 1, Cl: 1}
  equation-of-state:
  - model: constant-volume
    molar-volume: 1.3
  Debye-Huckel:
    electrolyte-species-type: weak-acid-associated
    weak-acid-charge: -1.0

Pros:

• Allows equation of state parameters compatible with different thermo models, stored in a consistent location regardless of the thermo model type

Cons:

• Some implementation complexity required to allow equation-of-state to be either a map or a list of maps.
• Debye-Huckel parameters are still unique in using a top-level field of their own in the species definition