Creating YAML Mechanism Files from Scratch#
Virtually every Cantera simulation involves one or more phases of matter. Depending on the calculation being performed, it may be necessary to evaluate thermodynamic properties, transport properties, and/or reaction rates for the phase(s) present. Before the properties can be evaluated, each phase must be defined, meaning that the models to use to compute its properties and reaction rates must be specified, along with any parameters the models require.
Because the amount of data required can be quite large, this data is imported from a YAML file that can be read by the application, so that a given phase model can be re-used for other simulations. This guide describes how to write such files to define phases and interfaces for use in Cantera simulations.
See also
See the Introduction to YAML Input Files for an introduction to the YAML syntax used by Cantera and a description of how dimensional values are handled.
Phases#
For each phase that appears in a problem, a corresponding entry should be present in the
phases
section of the input file. The phase entry specifies the elements and species
present in that phase, and the models to be used for computing thermodynamic, kinetic,
and transport properties.
Naming the Phase#
The name
entry is a string that identifies the phase. It must be unique within the
file among all phase definitions of any type. Phases are referenced by name when
importing them. The name
is also used to identify the phase within multiphase mixtures
or at phase boundaries.
Setting the Thermodynamic Model#
The thermodynamic model used to represent a phase is specified in the thermo
field. A
complete list of supported models can be found in the
YAML Input File Reference. Some thermodynamic models use additional fields in the phase
entry, which are described in the linked documentation.
Declaring the Elements#
In most cases, it is not necessary to specify the elements present in a phase. If no
elements
field is present, elements will be added automatically using the definitions
of the standard chemical elements based on the composition of the species present in the
phase.
If non-standard elements such as isotopes need to be represented, or the ordering of
elements within the phase is important, the elements in the phase may be declared in the
optional elements
entry.
If all of the elements to be added are either standard chemical elements or defined in
the elements
section of the current input file, the
elements can be specified as a list of element symbols. For example:
phases:
- name: my-mechanism
elements: [H, C, O, Ar]
...
To add elements from other top-level sections, from a different file, or from multiple such sources, a list of single-key mappings can be used where the key of each mapping specifies the source and the value is a list of element names. The keys can be:
The name of a section within the current file.
The name of an input file and a section in that file, separated by a slash, for example
myfile.yaml/my_elements
. If a relative path is specified, the directory containing the current file is searched first, followed by the Cantera data path.The name
default
to reference the standard chemical elements.
Example:
my-isotopes:
- name: O18
atomic-weight: 17.9991603
phases:
- name: my-phase
elements:
- default: [C, H, Ar]
- my-isotopes: [O18]
- myelements.yaml/uranium: [U235, U238]
species: ...
...
The order of the elements specified in the input file determines the order of the elements in the phase when it is imported by Cantera.
Declaring the Species#
If the species present in the phase corresponds to those species defined in the
species
section of the input file, the species
field may
be omitted, and those species will be added to the phase automatically. As a more
explicit alternative, the species
field may be set to the string all
.
To include specific species from the species
section of the input file, the species
entry can be a list of species names from that section. For example:
phases:
- name: my-phase
species: [H2, O2, H2O]
...
If species are defined in multiple input file sections, the species
entry can be a
list of single-key mappings, where the key of each mapping specifies the source and the
value is either the string all
or a list of species names. Each key can be either the
name of a section within the current input file or the name of a different file and a
section in that file, separated by a slash. If a relative path is specified, the
directory containing the current file is searched first, followed by the Cantera data
path. Example:
phases:
- name: my-phase
species:
- species: [O2, N2]
- more_species: all
- subdir/myfile.yaml/species: [NO2, N2O]
...
The order of species specified in the input file determines the order of the species in the phase when it is imported by Cantera.
Species containing elements that are not declared within the phase may be skipped by
setting the skip-undeclared-elements
field to true
. For example, to add all species
from the species
section that contain only hydrogen or oxygen, the phase definition
could contain:
phases:
- name: hydrogen-and-oxygen
elements: [H, O]
species: all
skip-undeclared-elements: true
...
Setting the Kinetics Model#
The kinetics model to be used, if any, is specified in the kinetics
field. Supported
kinetics models are bulk
, surface
, and edge
, depending on the dimensionality of
the phase. If omitted, no kinetics model will be used. For additional details, see the
list of supported models in the YAML Input File Reference.
Declaring the Reactions#
If a kinetics model has been specified, reactions may be added to the phase. By default,
all reactions from the reactions
section of the input file will be added.
Equivalently, the reactions
entry may be specified as the string all
.
To disable automatic addition of reactions from the reactions
section, the reactions
entry may be set to none
. This may be useful if reactions will be added
programmatically after the phase is constructed. The reactions
field must be set to
none
if a kinetics model has been specified but there is no reactions
section in the
input file.
To include only those reactions from the reactions
section where all of the species
involved are declared as being in the phase, the reactions
entry can be set to the
string declared-species
.
To include reactions from multiple sections or other files, the reactions
entry can be
given as a list of section names, for example:
phases:
- name: my-phase
...
reactions:
- OH_submechanism
- otherfile.yaml/C1-reactions
- otherfile.yaml/C2-reactions
...
To include reactions from multiple sections or other files while only including
reactions involving declared species, a list of single-key mappings can be used, where
the key is the section name (or file and section name) and the value is either the
string all
or the string declared-species
. For example:
phases:
- name: my-phase
...
reactions:
- OH_submechanism: all
- otherfile.yaml/C1-reactions: all
- otherfile.yaml/C2-reactions: declared-species
...
To permit reactions containing third-body efficiencies for species not present in the
phase, the additional field skip-undeclared-third-bodies
may be added to the phase
entry with the value true
.
Setting the Transport Model#
To enable transport property calculation, the transport model to be used can be
specified in the transport
field. A complete list of supported models
can be found in the YAML Input File Reference. For most transport models, additional
parameters need to be specified within each species definition.
Declaring Adjacent Phases#
For interface phases (surfaces and edges), the names of phases adjacent to the interface can be specified, in which case these additional phases can be automatically constructed when creating the interface phase. This behavior is useful when the interface has reactions that include species from one of these adjacent phases, since those phases must be known when adding such reactions to the interface.
If the definitions of the adjacent phases are contained in the phases
section of the
same input file as the interface, they can be specified as a list of names:
phases:
- name: my-surface-phase
...
adjacent: [gas, bulk]
...
- name: gas
...
- name: bulk
...
Alternatively, if the adjacent phase definitions are in other sections or other input files, they can be specified as a list of single-key mappings where the key is the section name (or file and section name) and the value is the phase name:
phases:
- name: my-surface-phase
...
adjacent:
- {my-other-phases: gas}
# a phase defined in the 'phases' section of a different YAML file
- {path/to/other-file.yaml/phases: bulk}
...
my-other-phases:
- name: gas
...
Since an interface kinetics mechanism is defined for the lowest-dimensional phase involved in the mechanism, only higher-dimensional adjacent phases should be specified. For example, when defining a surface, adjacent bulk phases may be specified, but adjacent edges must not.
Setting the Initial State#
The initial state of a phase can be set using two properties to set the thermodynamic
state, plus the composition. This state is specified as a mapping in the state
field
of phase
entry.
The thermodynamic state can be set by specifying two properties, such as temperature
(T
) and pressure (P
) or internal energy (U
) and density (D
). The full list of
property names and valid combinations can be found in the YAML
Input File Reference. In addition the composition can be set by providing a mapping that
gives the mass fractions (X
), mole fractions (Y
), coverages
(for surface phases),
or molalities (M
, for certain solution models). Where necessary, the values will be
automatically normalized.
Some examples of setting the state:
phases:
- name: my-phase
...
state:
T: 300 K
P: 101325 Pa
X: {O2: 1.0, N2: 3.76}
- name: my-other-phase
...
state:
density: 100 kg/m^3
T: 298
Y:
CH4: 0.2
C3H8: 0.1
CO2: 0.7
For pure fluid phases, the temperature, pressure, and vapor fraction may all be specified if and only if they define a consistent state.
Examples#
The following input file defines two equivalent gas phases including all reactions and
species defined in the input file. The species and reaction data is not shown for
clarity. In the second case, the phase definition is simplified by having the elements
added based on the species definitions, taking the species definitions from the default
species
section, and reactions from the default reactions
section.
phases:
- name: gas1
thermo: ideal-gas
elements: [O, H, N, Ar]
species: [H2, H, O, O2, OH, H2O, HO2, H2O2, N2, AR]
kinetics: gas
reactions: all
transport: mixture-averaged
state:
T: 300.0
P: 1.01325e+05
- name: gas2
thermo: ideal-gas
kinetics: gas
transport: mixture-averaged
state: {T: 300.0, 1 atm}
species:
- H2: ...
- H: ...
...
- AR: ...
reactions:
...
An input file defining an interface and its adjacent bulk phases, with full species data not shown for clarity:
phases:
- name: graphite
thermo: lattice
species:
- graphite-species: all
state: {T: 300, P: 101325, X: {C6: 1.0, LiC6: 1e-5}}
density: 2.26 g/cm^3
- name: electrolyte
thermo: lattice
species: [{electrolyte-species: all}]
density: 1208.2 kg/m^3
state:
T: 300
P: 101325
X: {Li+(e): 0.08, PF6-(e): 0.08, EC(e): 0.28, EMC(e): 0.56}
- name: anode-surface
thermo: ideal-surface
adjacent: [graphite, electrolyte]
kinetics: surface
reactions: [graphite-anode-reactions]
species: [{anode-species: all}]
site-density: 1.0 mol/cm^2
state: {T: 300, P: 101325}
graphite-species:
- name: C6
...
- name: LiC6
...
electrolyte-species:
- name: Li+(e)
...
- name: PF6-(e)
...
- name: EC(e)
...
- name: EMC(e)
...
anode-species:
- name: (int)
...
graphite-anode-reactions:
- equation: LiC6 <=> Li+(e) + C6
rate-constant: [5.74, 0.0, 0.0]
beta: 0.4
Species#
For each species declared as part of a phase description, a species definition is required to describe the composition, thermodynamic, and transport parameters of that species.
The default location for species entries is in the species
section of the input file.
Species defined in this section will automatically be considered for addition to phases
defined in the same file. Species can be defined in other sections of the input file or
in other input files, and these species definitions can be used in phase definitions by
explicitly referencing the section name.
Species Name#
The name of a species is given in the name
field of a species
entry. Names may
include almost all printable characters, with the exception of spaces. The use of some
characters such as [
, ]
, and ,
may require that species names be enclosed in
quotes when written in YAML. Some valid species names given in a YAML list include:
[CH4, methane, argon_2+, "C[CH2]", CH2(singlet), "H2O,l"]
Elemental Composition#
The elemental composition of a species is specified as a mapping in the composition
entry.
For gaseous species, the elemental composition is well-defined, since the species represent distinct molecules. For species in solid or liquid solutions, or on surfaces, there may be several possible ways of defining the species. For example, an aqueous species might be defined with or without including the water molecules in the solvation cage surrounding it.
For surface species, it is possible for the composition
mapping to be empty, in which
case the species is composed of nothing, and represents an empty surface site. This can
also be done to represent vacancies in solids. A charged vacancy can be defined to be
composed solely of electrons.
The special pseudo-element E
is used in representing charged species, where it
specifies the net number of electrons compared to the number needed to form a neutral
species. That is, negatively charged ions will have E
> 0, while positively charged
ions will have E
< 0.
The number of atoms of an element must be non-negative, except for electrons.
Examples:
composition: {C: 1, O: 2} # carbon dioxide
composition: {Ar: 1, E: -2} # Ar++
composition: {Y: 1, Ba: 2, Cu: 3, O: 6.5} # stoichiometric YBCO
composition: {} # A surface species representing an empty site
Thermodynamic Properties#
In addition to the thermodynamic model used at the phase level for computing properties,
parameterizations are usually required for the enthalpy, entropy, and specific heat
capacities of individual species under standard conditions. These parameterizations are
provided in the thermo
field of each species
entry, with the type of
parameterization specified by the model
field. A
complete list of parameterizations and their model-specific
fields can be found in the YAML Input File Reference.
An example thermo
field using the 7-coefficient NASA polynomials in two temperature
regions:
thermo:
model: NASA7
temperature-ranges: [200.0, 1000.0, 3500.0]
data:
- [5.14987613, -0.0136709788, 4.91800599e-05, -4.84743026e-08, 1.66693956e-11,
-1.02466476e+04, -4.64130376]
- [0.074851495, 0.0133909467, -5.73285809e-06, 1.22292535e-09, -1.0181523e-13,
-9468.34459, 18.437318]
Species Equation of State#
For some phase thermodynamic models, additional equation of state parameterizations are
needed for each species. This information is provided in the equation-of-state
field
of each species
entry, with the type of parameterization used specified by the model
field of the equation-of-state
field. A
complete list of equation of state parameterizations and their
model-specific fields can be found in the YAML Input File Reference.
Species Transport Coefficients#
Transport-related parameters for each species are needed in order to calculate transport
properties of a phase. These parameters are provided in the transport
field of each
species
entry, with the type of the parameterization used specified by the model
field of the transport
field. The only model type specifically handled is gas
. The
parameters used depend on the transport model specified at the phase level. The full set
of possible parameters is described in the API documentation.
An example of a transport
entry for a gas-phase species:
transport:
model: gas
geometry: linear
well-depth: 107.4
diameter: 3.458
polarizability: 1.6
rotational-relaxation: 3.8
Reactions#
Cantera supports a number of different types of reactions, including several types of homogeneous reactions, surface reactions, and electrochemical reactions. The reaction entries for all reaction types some common features. These general fields of a reaction entry are described first, followed by fields used for specific reaction types.
The Reaction Equation#
The reaction equation, specified in the equation
field of the reaction entry,
determines the reactant and product stoichiometry. All tokens (species names,
stoichiometric coefficients, +
, and <=>
) in the reaction equation must be separated
with spaces. Some examples of correctly and incorrectly formatted reaction equations are
shown below:
- equation: 2 CH2 <=> CH + CH3 # OK
- equation: 2 CH2<=>CH + CH3 # error - spaces required around '<=>''
- equation: 2CH2 <=> CH + CH3 # error - space required between '2' and 'CH2'
- equation: CH2 + CH2 <=> CH + CH3 # OK
- equation: 2 CH2 <=> CH+CH3 # error - spaces required around '+'
Whether the reaction is reversible or not is determined by the form of the equality sign
in the reaction equation. If either <=>
or =
is found, then the reaction is regarded
as reversible, and the reverse rate will be computed based on the equilibrium constant.
If, on the other hand, =>
is found, the reaction will be treated as irreversible.
Reaction type#
The type of the rate coefficient parameterization may be specified in the type
field
of the reaction
entry. The fields for specific reaction types
and additional parameters defining the rate constant for each of these reaction types
are described in the YAML Input File Reference.
The default parameterization is elementary
. Reactions involving surface species are
automatically identified as interface
reactions,
reactions involving surface species with the type
specified as Blowers-Masel
are
treated as interface-Blowers-Masel
, and reactions
involving charge transfer are automatically identified as
electrochemical
reactions.
Arrhenius Expressions#
Most reaction types in Cantera are parameterized by one or more modified Arrhenius expressions, such as
where \(A\) is the pre-exponential factor, \(T\) is the temperature, \(b\) is the temperature exponent, \(E_a\) is the activation energy, and \(R\) is the gas constant. Rates in this form can be written as YAML mappings. For example:
{A: 1.0e13, b: 0, E: 7.3 kcal/mol}
The units of \(A\) can be specified explicitly if desired. If not specified, they will be
determined based on the quantity
, length
, and time
units specified in the
governing units
fields. Since the units of \(A\) depend on the reaction order, the units
of each reactant concentration (dependent on phase type and dimensionality), and the
units of the rate of progress (different for homogeneous and heterogeneous reactions),
it is usually best not to specify units for \(A\), in which case they will be computed
taking all of these factors into account.
Note
If \(b \ne 0\), then the term \(T^b\) should have units of \(\t{K}^b\), which would change the units of \(A\). This is not done, however, so the units associated with \(A\) are really the units for \(k_f\). One way to formally express this is to replace \(T^b\) by the non-dimensional quantity \([T/(1\;\t{K})]^b\).
The key E
is used to specify \(E_a\).
Duplicate Reactions#
When a reaction is imported into a phase, it is checked to see that it is not a duplicate of another reaction already present in the phase, and normally an error results if a duplicate is found. But in some cases, it may be appropriate to include duplicate reactions, for example if a reaction can proceed through two distinctly different pathways, each with its own rate expression. Another case where duplicate reactions can be used is if it is desired to implement a reaction rate coefficient of the form:
While Cantera does not provide such a form for reaction rates, it can be implemented by defining \(N\) duplicate reactions, and assigning one rate coefficient in the sum to each reaction. By adding the field:
duplicate: true
to a reaction entry, then the reaction not only may have a duplicate, it must. Any reaction that specifies that it is a duplicate, but cannot be paired with another reaction in the phase that qualifies as its duplicate generates an error.
Negative Pre-exponential Factors#
If some of the terms in the above sum have negative \(A_n\), this scheme fails, since Cantera normally does not allow negative pre-exponential factors. But if there are duplicate reactions such that the total rate is positive, then the fact that negative \(A\) parameters are acceptable can be indicated by adding the field:
negative-A: true
Reaction Orders#
Explicit reaction orders different from the stoichiometric coefficients are sometimes used for non-elementary reactions. For example, consider the global reaction:
the forward rate constant might be given as [Westbrook and Dryer, 1981]:
This reaction could be defined as:
- equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O
rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol}
orders: {C8H18: 0.25, O2: 1.5}
Special care is required in this case since the units of the pre-exponential factor depend on the sum of the reaction orders, which may not be an integer.
Note that you can change reaction orders only for irreversible reactions.
Negative Reaction Orders#
Normally, reaction orders are required to be positive. However, in some cases negative
reaction orders provide better fits for experimental data. In these cases, the default
behavior may be overridden by adding the negative-orders
field to the reaction entry.
For example:
- equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O
rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol}
orders: {C8H18: -0.25, O2: 1.75}
negative-orders: true
Non-reactant Orders#
Some global reactions could have reactions orders for non-reactant species. In this
case, the nonreactant-orders
field must be added to the reaction entry:
- equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O
rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol}
orders: {C8H18: -0.25, CO: 0.15}
negative-orders: true
nonreactant-orders: true
Elements#
In Cantera, an element may refer to a chemical element or an isotope. Cantera provides built-in definitions for the chemical elements, including values for their atomic weights taken from IUPAC / CIAAW. These elements can be used by specifying the corresponding atomic symbols when specifying the composition of species. Explicit element definitions are usually only needed for isotopes.
In order to give a name to a particular isotope or a virtual element representing a
surface site, a custom element
entry can be used. The default location for element
entries is the elements
section of the input file. Elements defined in this section
will automatically be considered for addition to phases defined in the same file.
Elements can be defined in other sections of the input file if those sections are named
explicitly in the elements
field of the phase definition.
An element entry has the following fields:
symbol
: The symbol to be used for the element, for example when specifying the composition of a species.atomic-weight
: The atomic weight of the element, in unified atomic mass units (dalton)atomic-number
: The atomic number of the element. Optional.entropy298
: The standard molar entropy of the element at 298.15 K. Optional.
An example elements
section:
elements:
- symbol: C13
atomic-weight: 13.003354826
atomic-number: 6
- symbol: O-18
atomic-weight: 17.9991603