Phase Definitions#
A phase is a mapping that contains definitions for the elements, species,
and optionally reactions that can take place in that phase. The fields of a
phase entry are:
nameString identifier used for the phase. Required.
elementsSpecification for the elements present in the phase. This can be:
Omitted, in which case the standard elements will be added as needed by the species included in the phase.
A list of element symbols, which can be either defined in the
elementssection of the file or taken from the standard elements.A list of single-key mappings of section names to lists of element symbols. These sections can be in the same file as the phase definition, or from another file if written as
file-path/sectionname. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path. Standard elements can be included by referencing the fictitious sectiondefault.
speciesSpecification for the species present in the phase. This can be:
a list of species that appear in the
speciessection of the file.The string
all, to indicate that all species in thespeciessection should be included. This is the default if nospeciesentry is present.A list of single-key mappings of section names to either the string
allor a list of species names. These sections can be in the same file as the phase definition, or from another file if written asfile-path/sectionname. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path.
Species may be skipped depending on the setting of the
skip-undeclared-elementsoption.skip-undeclared-elementsIf set to
true, do not add species that contain elements that are not explicitly included in the phase. The default isfalse, where the presence of such species is considered an error.skip-undeclared-third-bodiesIf set to
true, ignore third body efficiencies for species that are not defined in the phase. The default isfalse, where the presence of such third body specifications is considered an error.stateA mapping specifying the thermodynamic state. See Setting the state.
adjacent-phasesFor interface phases, specification of adjacent phases that participate in reactions on the interface. This can be:
a list of phase names that appear in the
phasessection of the file.A list of single-key mappings of section names to a list of phase names. These sections can be in the same file as the current phase definition, or from another file if written as
file-path/section-name. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path.
thermoString specifying the phase thermodynamic model to be used. Supported model strings are:
binary-solution-tabulated(details)compound-lattice(details)coverage-dependent-surface(details)Debye-Huckel(details)edge(details)electron-cloud(details)fixed-stoichiometry(details)HMW-electrolyte(details)ideal-gas(details)ideal-molal-solution(details)ideal-condensed(details)ideal-solution-VPSS(details)ideal-surface(details)ions-from-neutral-molecule(details)lattice(details)liquid-water-IAPWS95(details)Margules(details)Maskell-solid-solution(details)Peng-Robinson(details)plasma(details)pure-fluid(details)Redlich-Kister(details)Redlich-Kwong(details)
kineticsString specifying the kinetics model to be used. Supported model strings are:
reactionsSource of reactions to include in the phase, if a kinetics model has been specified. This can be:
The string
all, which indicates that all reactions from thereactionssection of the file should be included. This is the default if noreactionsentry is present.The string
declared-species, which indicates that all reactions from thereactionssection involving only species present in the phase should be included.The string
none, which indicates that no reactions should be added. This can be used if reactions will be added programmatically after the phase is constructed.A list of sections from which to include reactions. These sections can be in the same file as the phase definition, or from another file if written as
file-path/sectionname. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path.A list of single-key mappings of section names to rules for adding reactions, where for each section name, that rule is either
allordeclared-speciesand is applied as described above.
Motz-WiseBoolean indicating whether the Motz-Wise correction should be applied to sticking reactions. Applicable only to interface phases. The default is
false. The value set at the phase level may be overridden on individual reactions.transportString specifying the transport model to be used. Supported model strings are:
Setting the state#
The state of a phase can be set using two properties to set the
thermodynamic state, plus the composition.
The composition can be set using one of the following fields, depending on the phase type. The composition is specified as a mapping of species names to values. Where necessary, the values will be automatically normalized.
mass-fractionsorYmole-fractionsorXcoveragesmolalitiesorM
The thermodynamic state can be set using the following property pairs, with some exceptions for phases where setting that property pair is not implemented. All properties are on a per unit mass basis where relevant:
TandPTandDTandVHandPUandVSandVSandPSandTPandVUandPVandHTandHSandHDandP
The following synonyms are also implemented for use in any of the pairs:
temperature,Tpressure,Penthalpy,Hentropy,Sint-energy,internal-energy,Uspecific-volume,Vdensity,D
Phase thermodynamic models#
binary-solution-tabulated#
A phase implementing tabulated standard state thermodynamics for one species in a binary solution, as described here.
Includes the fields of ideal-condensed, plus:
tabulated-speciesThe name of the species to which the tabulated enthalpy and entropy is added.
tabulated-thermoA mapping containing three (optionally four) lists of equal lengths:
mole-fractionsA list of mole fraction values for the tabulated species.
enthalpyThe extra molar enthalpy to be added to the tabulated species at these mole fractions.
entropyThe extra molar entropy to be added to the tabulated species at these mole fractions.
molar-volumeThe molar volume of the phase at these mole fractions. This input is optional.
New in version 2.5.
compound-lattice#
A phase that is comprised of a fixed additive combination of other lattice phases, as described here.
Additional fields:
compositionA mapping of component phase names to their relative stoichiometries.
Example:
thermo: compound-lattice
composition: {Li7Si3(s): 1.0, Li7Si3-interstitial: 1.0}
coverage-dependent-surface#
A coverage-dependent surface phase. That is, a surface phase where the enthalpy, entropy, and heat capacity of each species may depend on its coverage and the coverage of other species in the phase. Full details are described here. The majority of coverage dependency parameters are provided in the species entry as described here.
Additional fields:
site-densityThe molar density of surface sites.
reference-state-coverageThe reference state coverage denoting the low-coverage limit (ideal-surface) thermodynamic properties.
Example:
- name: covdep
thermo: coverage-dependent-surface
species: [Pt, OC_Pt, CO2_Pt, C_Pt, O_Pt]
state:
T: 500.0
P: 1.01325e+05
coverages: {Pt: 0.5, OC_Pt: 0.5, CO2_Pt: 0.0, C_Pt: 0.0, O_Pt: 0.0}
site-density: 2.72e-09
reference-state-coverage: 0.22
New in version 3.0.
Debye-Huckel#
The Debye-Hückel model as described here.
Additional parameters for this model are contained in the activity-data
field:
activity-dataThe activity data field contains the following fields:
modelOne of
dilute-limit,B-dot-with-variable-a,B-dot-with-common-a,beta_ij, orPitzer-with-beta_ijA_DebyeThe value of the Debye “A” parameter, or the string
variableto use a calculation based on the water equation of state. Defaults to the constant value of 1.172576 kg^0.5/gmol^0.5, a nominal value for water at 298 K and 1 atm.B_DebyeThe Debye “B” parameter. Defaults to 3.2864e+09 kg^0.5/gmol^0.5/m, a nominal value for water.
max-ionic-strengthThe maximum ionic strength
use-Helgeson-fixed-formBoolean,
trueorfalsedefault-ionic-radiusIonic radius to use for species where the ionic radius has not been specified.
B-dotThe value of B-dot.
betaList of mappings providing values of \(\beta_{ij}\) for different species pairs. Each mapping contains a
specieskey that contains a list of two species names, and abetakey that contains the corresponding value of \(\beta_{ij}\).
Example:
thermo: Debye-Huckel
activity-data:
model: beta_ij
max-ionic-strength: 3.0
use-Helgeson-fixed-form: true
default-ionic-radius: 3.042843 angstrom
beta:
- species: [H+, Cl-]
beta: 0.27
- species: [Na+, Cl-]
beta: 0.15
- species: [Na+, OH-]
beta: 0.06
In addition, the Debye-Hückel model uses several species-specific properties
which may be defined in the Debye-Huckel field of the species entry. These
properties are:
ionic-radiusSize of the species.
electrolyte-species-typeOne of
solvent,charged-species,weak-acid-associated,strong-acid-associated,polar-neutral, ornonpolar-neutral. The typesolventis the default for the first species in the phase. The typecharged-speciesis the default for species with a net charge. Otherwise, the default is andnonpolar-neutral.weak-acid-chargeCharge to use for species that can break apart into charged species.
Example:
name: NaCl(aq)
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
Debye-Huckel:
ionic-radius: 4 angstrom
electrolyte-species-type: weak-acid-associated
weak-acid-charge: -1.0
edge#
A one-dimensional edge between two surfaces, as described here.
Additional fields:
site-densityThe molar density of sites per unit length along the edge
Example:
thermo: edge
site-density: 5.0e-17 mol/cm
electron-cloud#
A phase representing an electron cloud, such as conduction electrons in a metal, as described here.
Additional fields:
densityThe density of the bulk metal
fixed-stoichiometry#
A phase with fixed composition, as described here.
HMW-electrolyte#
A dilute or concentrated liquid electrolyte phase that obeys the Pitzer formulation for nonideality, as described here.
Additional parameters for this model are contained in the activity-data
field:
activity-dataThe activity data field contains the following fields:
temperature-modelThe form of the Pitzer temperature model. One of
constant,linearorcomplex. The default isconstant.A_DebyeThe value of the Debye “A” parameter, or the string
variableto use a calculation based on the water equation of state. The default is 1.172576 kg^0.5/gmol^0.5, a nominal value for water at 298 K and 1 atm.max-ionic-strengthThe maximum ionic strength
interactionsA list of mappings, where each mapping describes a binary or ternary interaction among species. Fields of this mapping include:
speciesA list of one to three species names
beta0The \(\beta^{(0)}\) parameters for an cation/anion interaction. 1, 2, or 5 values depending on the value of
temperature-model.beta1The \(\beta^{(1)}\) parameters for an cation/anion interaction. 1, 2, or 5 values depending on the value of
temperature-model.beta2The \(\beta^{(2)}\) parameters for an cation/anion interaction. 1, 2, or 5 values depending on the value of
temperature-model.CphiThe \(C^\phi\) parameters for an cation/anion interaction. 1, 2, or 5 values depending on the value of
temperature-model.alpha1The \(\alpha^{(1)}\) parameter for an cation/anion interaction.
alpha2The \(\alpha^{(2)}\) parameter for an cation/anion interaction.
thetaThe \(\theta\) parameters for a like-charged binary interaction. 1, 2, or 5 values depending on the value of
temperature-model.lambdaThe \(\lambda\) parameters for binary interactions involving at least one neutral species. 1, 2, or 5 values depending on the value of
temperature-model.psiThe \(\Psi\) parameters for ternary interactions involving three charged species. 1, 2, or 5 values depending on the value of
temperature-model.zetaThe \(\zeta\) parameters for ternary interactions involving one neutral species. 1, 2, or 5 values depending on the value of
temperature-model.muThe \(\mu\) parameters for a neutral species self-interaction. 1, 2, or 5 values depending on the value of
temperature-model.
cropping-coefficientsln_gamma_k_minDefault -5.0.
ln_gamma_k_maxDefault 15.0.
ln_gamma_o_minDefault -6.0.
ln_gamma_o_maxDefault 3.0.
Example:
thermo: HMW-electrolyte
activity-data:
temperature-model: complex
A_Debye: 1.175930 kg^0.5/gmol^0.5
interactions:
- species: [Na+, Cl-]
beta0: [0.0765, 0.008946, -3.3158E-6, -777.03, -4.4706]
beta1: [0.2664, 6.1608E-5, 1.0715E-6, 0.0, 0.0]
beta2: [0.0, 0.0, 0.0, 0.0, 0.0]
Cphi: [0.00127, -4.655E-5, 0.0, 33.317, 0.09421]
alpha1: 2.0
- species: [H+, Cl-]
beta0: [0.1775]
beta1: [0.2945]
beta2: [0.0]
Cphi: [0.0008]
alpha1: 2.0
- species: [Na+, OH-]
beta0: 0.0864
beta1: 0.253
beta2: 0.0
Cphi: 0.0044
alpha1: 2.0
alpha2: 0.0
- {species: [Cl-, OH-], theta: -0.05}
- {species: [Na+, Cl-, OH-], psi: -0.006}
- {species: [Na+, H+], theta: 0.036}
- {species: [Cl-, Na+, H+], psi: [-0.004]}
ideal-gas#
The ideal gas model as described here.
Example:
- name: ohmech
thermo: ideal-gas
elements: [O, H, Ar, N]
species: [H2, H, O, O2, OH, H2O, HO2, H2O2, AR, N2]
kinetics: gas
transport: mixture-averaged
state: {T: 300.0, P: 1 atm}
ideal-molal-solution#
A phase based on the mixing-rule assumption that all molality-based activity coefficients are equal to one, as described here.
Additional fields:
standard-concentration-basisA string specifying the basis for the standard concentration. One of
unity,species-molar-volume, orsolvent-molar-volume.cutoffParameters for cutoff treatments of activity coefficients
modelpolyorpolyExpgamma_ogamma_o value for the cutoff process at the zero solvent point
gamma_kgamma_k minimum for the cutoff process at the zero solvent point
X_ovalue of the solute mole fraction that centers the cutoff polynomials for the cutoff = 1 process
c_0Parameter in the polyExp cutoff treatment having to do with rate of exponential decay
slope_fParameter in the
polyExpcutoff treatmentslope_gParameter in the
polyExpcutoff treatment
Example:
thermo: ideal-molal-solution
standard-concentration-basis: solvent-molar-volume
cutoff:
model: polyexp
gamma_o: 0.0001
gamma_k: 10.0
X_o: 0.2
c_0: 0.05
slope_f: 0.6
slope_g: 0.0
ideal-condensed#
A condensed phase ideal solution as described here.
Additional fields:
standard-concentration-basisA string specifying the basis for the standard concentration. One of
unity,species-molar-volume, orsolvent-molar-volume.
ideal-solution-VPSS#
An ideal solution model using variable pressure standard state methods as described here.
Additional fields:
standard-concentration-basisA string specifying the basis for the standard concentration. One of
unity,species-molar-volume, orsolvent-molar-volume.
ideal-surface#
An ideal surface phase, as described here.
Additional fields:
site-densityThe molar density of surface sites
Example:
- name: Pt_surf
thermo: ideal-surface
adjacent-phases: [gas]
elements: [Pt, H, O, C]
species: [PT(S), H(S), H2O(S), OH(S), CO(S), CO2(S), CH3(S), CH2(S)s,
CH(S), C(S), O(S)]
kinetics: surface
reactions: all
state:
T: 900.0
coverages: {O(S): 0.0, PT(S): 0.5, H(S): 0.5}
site-density: 2.7063e-09
ions-from-neutral-molecule#
A model that handles the specification of the chemical potentials for ionic species, given a specification of the chemical potentials for the same phase expressed in terms of combinations of the ionic species that represent neutral molecules, as described here.
Deprecated since version 3.0: This phase model is deprecated and will be removed after Cantera 3.0.
Additional fields:
neutral-phaseThe
nameof the phase definition for the phase containing the neutral molecules.
Example:
- name: KCl-ions
thermo: ions-from-neutral-molecule
neutral-phase: KCl-neutral
species: [K+, Cl-]
- name: KCl-neutral
species: [KCl(l)]
thermo: Margules
lattice#
A simple thermodynamic model for a bulk phase, assuming a lattice of solid atoms, as described here.
Additional fields:
site-densityThe molar density of lattice sites
liquid-water-IAPWS95#
An equation of state for liquid water, as described here.
Margules#
A phase employing the Margules approximation for the excess Gibbs free energy, as described here.
Additional fields:
interactionsA list of mappings, where each mapping has the following fields:
speciesA list of two species names
excess-enthalpyA list of two values specifying the first and second excess enthalpy coefficients for the interaction of the specified species. Defaults to [0, 0].
excess-entropyA list of two values specifying the first and second excess entropy coefficients for the interaction of the specified species. Defaults to [0, 0].
excess-volume-enthalpyA list of two values specifying the first and second enthalpy coefficients for the excess volume interaction of the specified species. Defaults to [0, 0].
excess-volume-entropyA list of two values specifying the first and second entropy coefficients for the excess volume interaction of the specified species. Defaults to [0, 0].
Example:
thermo: Margules
interactions:
- species: [KCl(l), LiCl(l)]
excess-enthalpy: [-17570, -377]
excess-entropy: [-7.627, 4.958]
Maskell-solid-solution#
A condensed phase non-ideal solution with two species, as described here.
Deprecated since version 3.0: This phase model is deprecated and will be removed after Cantera 3.0.
Additional fields:
excess-enthalpyThe molar excess enthalpy
product-speciesString specifying the “product” species
Example:
thermo: Maskell-solid-solution
excess-enthalpy: 5 J/mol
product-species: H(s)
Peng-Robinson#
A multi-species Peng-Robinson phase as described here.
The parameters for each species are contained in the corresponding species entries. See Peng-Robinson species equation of state.
New in version 3.0.
plasma#
A phase for plasma. This phase handles plasma properties such as the electron energy distribution and electron temperature with different models as described here.
Additional fields:
electron-energy-distributionA mapping with the following fields:
typeString specifying the type of the electron energy distribution to be used. Supported model strings are:
isotropicdiscretized
shape-factorA constant in the isotropic distribution, which is shown as x in the detailed description of this class. The value needs to be a positive number. This field is only used with
isotropic. Defaults to 2.0.mean-electron-energyMean electron energy of the isotropic distribution. The default sets the electron temperature equal gas temperature and uses the corresponding electron energy as mean electron energy. This field is only used with
isotropic.energy-levelsA list of values specifying the electron energy levels. The default uses 1001 equal spaced points from 0 to 1 eV.
distributionA list of values specifying the discretized electron energy distribution. This field is only used with
discretized.normalizeA flag specifying whether normalizing the discretized electron energy distribution or not. This field is only used with
discretized. Defaults totrue.
Example:
- name: isotropic-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: isotropic
shape-factor: 2.0
mean-electron-energy: 1.0 eV
energy-levels: [0.0, 0.1, 1.0, 10.0]
- name: discretized-electron-energy-plasma
thermo: plasma
kinetics: gas
transport: ionized-gas
electron-energy-distribution:
type: discretized
energy-levels: [0.0, 0.1, 1.0, 10.0]
distribution: [0.0, 0.2, 0.7, 0.01]
normalize: False
New in version 2.6.
pure-fluid#
A phase representing a pure fluid equation of state for one of several species, as described here.
Additional fields:
pure-fluid-nameName of the pure fluid model to use: -
carbon-dioxide-heptane-HFC-134a-hydrogen-methane-nitrogen-oxygen-water
Redlich-Kister#
A phase employing the Redlich-Kister approximation for the excess Gibbs free energy, as described here.
Additional fields:
interactionsA list of mappings, where each mapping has the following fields:
speciesA list of two species names
excess-enthalpyA list of polynomial coefficients for the excess enthalpy of the specified binary interaction
excess-entropyA list of polynomial coefficients for the excess entropy of the specified binary interaction
Example:
thermo: Redlich-Kister
interactions:
- species: [Li(C6), V(C6)]
excess-enthalpy: [-3.268e+06, 3.955e+06, -4.573e+06, 6.147e+06, -3.339e+06,
1.117e+07, 2.997e+05, -4.866e+07, 1.362e+05, 1.373e+08,
-2.129e+07, -1.722e+08, 3.956e+07, 9.302e+07, -3.280e+07]
excess-entropy: [0.0]
Redlich-Kwong#
A multi-species Redlich-Kwong phase as described here.
The parameters for each species are contained in the corresponding species entries. See Redlich-Kwong species equation of state.