diff --git a/doc/doxygen/mainpage.md b/doc/doxygen/mainpage.md
index 867d0be7f3..422d9c23a4 100644
--- a/doc/doxygen/mainpage.md
+++ b/doc/doxygen/mainpage.md
@@ -1,15 +1,17 @@
-# %Cantera C++ Reference
+@mainpage %Cantera Developer API
> **Note:** This is the **%Cantera Developer API** documentation; for general
> information on %Cantera, refer to [**cantera.org**](https://cantera.org).
+> The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).
Use sidebar or menu at the top to view detailed documentation of the code, or
use the following shortcuts:
* Overview of [**Cantera C++ Modules**](modules.html)
* Index of [**Cantera C++ Classes**](classes.html)
+* @ref sec-yaml-documentation
-A topical overview is provided as follows:
+A topical overview of C++ modules is provided as follows:
* @ref solnGroup (interface to %Cantera core objects)
* @ref thermoprops (temperature, pressure, energy, ...)
@@ -22,5 +24,3 @@ A topical overview is provided as follows:
For fundamental scientific theory used for the implementation of %Cantera, refer to the
[Cantera Science Section](https://cantera.org/science/index.html) of the
[Cantera Website](https://cantera.org).
-
-The %Cantera source code is hosted on [GitHub](https://github.com/Cantera/cantera).
diff --git a/doc/doxygen/yaml.md b/doc/doxygen/yaml.md
new file mode 100644
index 0000000000..a076476b87
--- /dev/null
+++ b/doc/doxygen/yaml.md
@@ -0,0 +1,26 @@
+@page sec-yaml-documentation %Cantera YAML Documentation
+
+> **Note:** %Cantera provides @ref sec-yaml-conversion to generate YAML files
+> from Chemkin input data as well as legacy %Cantera formats.
+
+This short guide describes %Cantera YAML input files that define phases and
+interfaces for use in %Cantera simulations. Each link below represents an entry
+point to the @subpage sec-yaml-api; while you certainly can read them in order,
+you can also jump to whichever section addresses your current needs. If you need
+tips on troubleshooting the YAML file syntax rules, please look at the
+@subpage sec-yaml-format-tutorial.
+
+- @ref sec-yaml-general -
+ Structure of a %Cantera YAML input file.
+- @ref sec-yaml-phases -
+ For each phase or interface that appears in a problem, a corresponding
+ entry should be present in the input file(s). Phase entries specify lists
+ of elements, species and reactions, as well as other relevant parameters.
+- @ref sec-yaml-species -
+ For each species declared as part of a phase description, thermodynamic
+ properties and other data need to be defined.
+- @ref sec-yaml-reactions -
+ %Cantera supports a number of different types of reactions, including
+ several types of homogeneous reactions, surface reactions, and
+ electrochemical reactions. For each, there is a corresponding entry
+ type.
diff --git a/doc/doxygen/yaml/elements.md b/doc/doxygen/yaml/elements.md
new file mode 100644
index 0000000000..867d893254
--- /dev/null
+++ b/doc/doxygen/yaml/elements.md
@@ -0,0 +1,52 @@
+@page sec-yaml-elements Element Entries
+
+[TOC]
+
+# Overview
+
+%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. `element`
+entries are needed only when defining custom elements that are not standard chemical
+elements, or defining specific 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.
+
+**Example:**
+
+```yaml
+elements:
+- symbol: C13
+ atomic-weight: 13.003354826
+ atomic-number: 12
+- symbol: O-18
+ atomic-weight: 17.9991603
+```
+
+# Element API Reference
+
+The fields of an `element` entry are:
+
+`symbol`
+
+The symbol used for the element, as used when specifying the
+composition of 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.
diff --git a/doc/doxygen/yaml/general.md b/doc/doxygen/yaml/general.md
new file mode 100644
index 0000000000..b10942d500
--- /dev/null
+++ b/doc/doxygen/yaml/general.md
@@ -0,0 +1,43 @@
+@page sec-yaml-general General File Structure
+
+The top level of a %Cantera YAML input file is a mapping that defines different input
+file sections. Each section consists of a list of mappings that define objects of the
+same type, such as reactions, species, phases, or elements. The `phases` section of
+an input file contains all of the phase definitions. Multiple sections
+containing reaction, species, or element definitions can be used. The
+specific names `reactions`, `species`, and `elements` are used as defaults when looking
+for @ref sec-yaml-reactions, @ref sec-yaml-species, and @ref sec-yaml-elements to add to
+a phase. %Cantera uses SI input units by default, although input values can be
+provided using a number of different units, as described in the
+@ref sec-yaml-units-default section.
+
+A simple input file has the following structure:
+
+```yaml
+description: |-
+ Optional description of the input file.
+
+# units: optional unit settings used for input data
+
+phases:
+- name: spam
+ thermo: ideal-gas
+ # Additional fields come after this
+- name: green-eggs
+ thermo: model-name
+ # Additional fields come after this
+
+species:
+- name: A
+ # Additional fields come after this
+- name: B
+ # Additional fields come after this
+- name: C
+ # Additional fields come after this
+
+reactions:
+- equation: A + B <=> C + D
+ # Additional fields come after this
+- equation: A + C <=> 2 D
+ # Additional fields come after this
+```
diff --git a/doc/doxygen/yaml/phase.md b/doc/doxygen/yaml/phase.md
new file mode 100644
index 0000000000..ba0f7ca7b5
--- /dev/null
+++ b/doc/doxygen/yaml/phase.md
@@ -0,0 +1,583 @@
+@page sec-yaml-phases Phase Definitions
+
+[TOC]
+
+# Overview
+
+For each phase that appears in a problem, a corresponding entry should
+be present in the input file(s). 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 {#sec-yaml-phase-setting-thermo}
+
+The thermodynamic model used to represent a phase is specified in the
+`thermo` field. Supported models are:
+
+- @ref sec-yaml-binary-solution-tabulated:
+ A binary mixture where the excess enthalpy and entropy are interpolated between
+ tabulated values as a function of mole fraction
+- @ref sec-yaml-compound-lattice:
+ A phase that is comprised of a fixed additive combination of other lattice phases
+- @ref sec-yaml-coverage-dependent-surface:
+ A coverage-dependent surface phase
+- @ref sec-yaml-Debye-Huckel:
+ A dilute liquid electrolyte which obeys the Debye-Hückel formulation for nonideality
+- @ref sec-yaml-edge:
+ A one-dimensional edge between two surfaces
+- @ref sec-yaml-electron-cloud:
+ A phase representing free electrons in a metal
+- @ref sec-yaml-fixed-stoichiometry:
+ An incompressible, single-species phase
+- @ref sec-yaml-HMW-electrolyte:
+ A dilute or concentrated liquid electrolyte which obeys the Pitzer formulation
+ for nonideality
+- @ref sec-yaml-ideal-condensed:
+ An ideal liquid or solid solution
+- @ref sec-yaml-ideal-gas:
+ A mixture which obeys the ideal gas law
+- @ref sec-yaml-ideal-molal-solution:
+ An ideal solution based on the mixing-rule assumption that all molality-based
+ activity coefficients are equal to one
+- @ref sec-yaml-ideal-solution-VPSS:
+ An ideal solution; Uses "variable pressure standard state" methods for
+ calculating thermodynamic properties
+- @ref sec-yaml-ideal-surface:
+ A surface between two bulk phases
+- @ref sec-yaml-ions-from-neutral-molecule:
+ A phase for representing ionic species based on another phase where those ions
+ are components of neutral molecules
+- @ref sec-yaml-lattice:
+ A simple model for an incompressible lattice of solid atoms
+- @ref sec-yaml-liquid-water-IAPWS95:
+ An implementation of the IAPWS95 equation of state for water, for the
+ liquid region only
+- @ref sec-yaml-Margules:
+ A model that employs the Margules approximation for the excess Gibbs free energy
+- @ref sec-yaml-Maskell-solid-solution:
+ A condensed, binary, non-ideal solution
+- @ref sec-yaml-Peng-Robinson:
+ A multi-species mixture obeying the Peng-Robinson equation of state
+- @ref sec-yaml-plasma:
+ A phase defined by a distinct electron temperature or
+ detailed electron energy distribution function
+- @ref sec-yaml-pure-fluid:
+ A phase representing one of several pure substances including liquid, vapor,
+ two-phase, and supercritical regions
+- @ref sec-yaml-Redlich-Kister:
+ A model that employs the Redlich-Kister approximation for the excess Gibbs
+ free energy
+- @ref sec-yaml-Redlich-Kwong:
+ A multi-species mixture obeying the Redlich-Kwong equation of state.
+
+Some thermodynamic models use additional fields in the `phase` entry,
+which are described in the documentation linked above
+(see also @subpage sec-yaml-phase-thermo-models).
+
+## Declaring the Elements {#sec-yaml-phase-declaring-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](@ref sec-yaml-elements) section of the current input file, the
+elements can be specified as a list of element symbols. For example:
+
+```yaml
+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:**
+
+```yaml
+elements:
+- default: [C, H, Ar]
+- isotopes: [O18]
+- myelements.yaml/uranium: [U235, U238]
+```
+
+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 {#sec-yaml-phase-declaring-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:
+
+```yaml
+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:
+
+```yaml
+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:
+
+```yaml
+phases:
+- name: hydrogen-and-oxygen
+ elements: [H, O]
+ species: all
+ skip-undeclared-elements: true
+```
+
+## Setting the Kinetics Model {#sec-yaml-phase-setting-kinetics}
+
+The kinetics model to be used, if any, is specified in the `kinetics`
+field. Supported model strings are:
+
+- `none`
+- [gas](@ref Cantera.GasKinetics)
+- [surface](@ref Cantera.InterfaceKinetics)
+- [edge](@ref Cantera.EdgeKinetics)
+
+If omitted, no kinetics model will be used.
+
+## Declaring the Reactions {#sec-yaml-phase-declaring-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:
+
+```yaml
+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:
+
+```yaml
+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 {#sec-yaml-phase-setting-transport}
+
+To enable transport property calculation, the transport model to be used
+can be specified in the `transport` field. Supported models are:
+
+- `none`:
+ No transport model
+- [high-pressure](@ref Cantera.HighPressureGasTransport):
+ A model for high-pressure gas transport properties based on a method
+ of corresponding states
+- [ionized-gas](@ref Cantera.IonGasTransport):
+ A model implementing the Stockmayer-(n,6,4) model for transport of
+ ions in a gas
+- [mixture-averaged](@ref Cantera.MixTransport):
+ The mixture-averaged transport model for ideal gases
+- [mixture-averaged-CK](@ref Cantera.MixTransport):
+ The mixture-averaged transport model for ideal gases, using
+ polynomial fits corresponding to Chemkin-II
+- [multicomponent](@ref Cantera.MultiTransport):
+ The multicomponent transport model for ideal gases
+- [multicomponent-CK](@ref Cantera.MultiTransport):
+ The multicomponent transport model for ideal gases, using polynomial
+ fits corresponding to Chemkin-II
+- [unity-Lewis-number](@ref Cantera.UnityLewisTransport):
+ A transport model for ideal gases, where diffusion coefficients for
+ all species are set so that the Lewis number is 1
+- [water](@ref Cantera.WaterTransport):
+ A transport model for pure water applicable in both liquid and vapor phases
+
+## Declaring Adjacent Phases {#sec-yaml-phase-declaring-adjacent}
+
+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:
+
+```yaml
+adjacent: [gas, 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:
+
+```yaml
+adjacent:
+- {sectionname: gas} # a phase defined in a different section of the same YAML file
+- {path/to/other-file.yaml/phases: bulk} # a phase defined in the 'phases' section
+ # of a different YAML file
+```
+
+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 {#sec-yaml-phase-setting-state}
+
+The 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 the `phase` entry.
+
+The thermodynamic state can be set in terms of two of the following
+properties, with the valid property pairs depending on the phase model:
+
+- `temperature` or `T`
+- `pressure` or `P`
+- `enthalpy` or `H`
+- `entropy` or `S`
+- `int-energy`, `internal-energy` or `U`
+- `specific-volume` or `V`
+- `density` or `D`
+- `vapor-fraction` or `Q`
+
+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:
+
+- `T` and `P`
+- `T` and `D`
+- `T` and `V`
+- `H` and `P`
+- `U` and `V`
+- `S` and `V`
+- `S` and `P`
+- `S` and `T`
+- `P` and `V`
+- `U` and `P`
+- `V` and `H`
+- `T` and `H`
+- `S` and `H`
+- `D` and `P`
+
+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-fractions` or `Y`
+- `mole-fractions` or `X`
+- `coverages`
+- `molalities` or `M`
+
+**Examples:**
+
+```yaml
+state:
+ T: 300 K
+ P: 101325 Pa
+ X: {O2: 1.0, N2: 3.76}
+
+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.
+
+```yaml
+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:
+
+```yaml
+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
+```
+
+# Phase API Reference
+
+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:
+
+`name`
+
+String identifier used for the phase. Required.
+
+`elements`
+
+Specification 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
+ `elements` section 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 section `default`.
+
+See also @ref sec-yaml-phase-declaring-elements.
+
+`species`
+
+Specification for the species present in the phase. This can be:
+
+- a list of species that appear in the `species` section of the
+ file.
+- The string `all`, to indicate that all species in the `species`
+ section should be included. This is the default if no `species`
+ entry is present.
+- A list of single-key mappings of section names to either the
+ string `all` or a list of species names. 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.
+
+See also @ref sec-yaml-phase-declaring-species. Species may be skipped
+depending on the setting of the `skip-undeclared-elements` option.
+
+`skip-undeclared-elements`
+
+If set to `true`, do not add species that contain elements that are
+not explicitly included in the phase. The default is `false`, where
+the presence of such species is considered an error.
+
+`skip-undeclared-third-bodies`
+
+If set to `true`, ignore third body efficiencies for species that
+are not defined in the phase. The default is `false`, where the
+presence of such third body specifications is considered an error.
+
+`state`
+
+A mapping specifying the thermodynamic state. See @ref sec-yaml-phase-setting-state.
+
+`adjacent-phases`
+
+For 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 `phases` section 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.
+
+See also @ref sec-yaml-phase-declaring-adjacent.
+
+`thermo`
+
+String specifying the phase thermodynamic model to be used.
+For a list of supported model strings, see @ref sec-yaml-phase-setting-thermo.
+
+`kinetics`
+
+String specifying the kinetics model to be used. For supported model
+strings, see sec-yaml-phase-setting-kinetics.
+
+`reactions`
+
+Source 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 the
+ `reactions` section of the file should be included. This is the
+ default if no `reactions` entry is present.
+- The string `declared-species`, which indicates that all
+ reactions from the `reactions` section 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 `all` or `declared-species` and is applied as described
+ above.
+
+See also @ref sec-yaml-phase-declaring-reactions.
+
+`Motz-Wise`
+
+Boolean 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.
+
+`transport`
+
+String specifying the transport model to be used. For a list of supported
+model strings, see @ref sec-yaml-phase-setting-transport.
diff --git a/doc/doxygen/yaml/phasethermo.md b/doc/doxygen/yaml/phasethermo.md
new file mode 100644
index 0000000000..f914767eb6
--- /dev/null
+++ b/doc/doxygen/yaml/phasethermo.md
@@ -0,0 +1,618 @@
+@page sec-yaml-phase-thermo-models Phase Thermodynamic Models
+
+Thermodynamic models are specified using the `thermo` field of @ref sec-yaml-phases.
+
+[TOC]
+
+# binary-solution-tabulated {#sec-yaml-binary-solution-tabulated}
+
+A phase implementing tabulated standard state thermodynamics for one
+species in a binary solution, see @ref Cantera.BinarySolutionTabulatedThermo.
+
+@since New in %Cantera 2.5
+
+Includes the fields of @ref sec-yaml-ideal-condensed, plus:
+
+`tabulated-species`
+
+The name of the species to which the tabulated enthalpy and entropy
+is added.
+
+`tabulated-thermo`
+
+A mapping containing three (optionally four) lists of equal lengths:
+
+- `mole-fractions`: A list of mole fraction values for the tabulated species.
+- `enthalpy`: The extra molar enthalpy to be added to the tabulated species at
+ these mole fractions.
+- `entropy`: The extra molar entropy to be added to the tabulated species at
+ these mole fractions.
+- `molar-volume`: The molar volume of the phase at these mole fractions. This
+ input is optional.
+
+# compound-lattice {#sec-yaml-compound-lattice}
+
+A phase that is comprised of a fixed additive combination of other
+lattice phases, see @ref Cantera.LatticeSolidPhase.
+
+Additional fields:
+
+`composition`
+
+A mapping of component phase names to their relative stoichiometries.
+
+**Example:**
+
+```yaml
+thermo: compound-lattice
+composition: {Li7Si3(s): 1.0, Li7Si3-interstitial: 1.0}
+```
+
+# coverage-dependent-surface {#sec-yaml-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. For full details,
+see @ref Cantera.CoverageDependentSurfPhase.
+The majority of coverage dependency parameters are provided in the species
+entry, see @ref sec-yaml-coverage-dependent-surface.
+
+@since New in %Cantera 3.0
+
+Additional fields:
+
+`site-density`
+
+The molar density of surface sites.
+
+`reference-state-coverage`
+
+The reference state coverage denoting the low-coverage limit
+(ideal-surface) thermodynamic properties.
+
+**Example:**
+
+```yaml
+- 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
+```
+
+# Debye-Huckel {#sec-yaml-Debye-Huckel}
+
+The Debye-Hückel model, see @ref Cantera.DebyeHuckel.
+
+Additional parameters for this model are contained in the `activity-data` field:
+
+`activity-data`
+
+The activity data field contains the following fields:
+
+- `model`: One of `dilute-limit`, `B-dot-with-variable-a`,
+ `B-dot-with-common-a`, `beta_ij`, or `Pitzer-with-beta_ij`
+- `A_Debye`: The value of the Debye "A" parameter, or the string `variable`
+ to 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_Debye`: The Debye "B" parameter. Defaults to 3.2864e+09
+ kg^0.5/gmol^0.5/m, a nominal value for water.
+- `max-ionic-strength`: The maximum ionic strength
+- `use-Helgeson-fixed-form`: Boolean, `true` or `false`
+- `default-ionic-radius`: Ionic radius to use for species where the ionic radius has
+ not been specified.
+- `B-dot`: The value of B-dot.
+- `beta`: List of mappings providing values of @f$\beta_{ij}@f$ for different
+ species pairs. Each mapping contains a `species` key that
+ contains a list of two species names, and a `beta` key that
+ contains the corresponding value of @f$\beta_{ij}@f$.
+
+**Example:**
+
+```yaml
+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-radius`
+
+Size of the species.
+
+`electrolyte-species-type`
+
+One of `solvent`, `charged-species`, `weak-acid-associated`,
+`strong-acid-associated`, `polar-neutral`, or `nonpolar-neutral`.
+The type `solvent` is the default for the first species in the
+phase. The type `charged-species` is the default for species with a
+net charge. Otherwise, the default is and `nonpolar-neutral`.
+
+`weak-acid-charge`
+
+Charge to use for species that can break apart into charged species.
+
+**Example:**
+
+```yaml
+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 {#sec-yaml-edge}
+
+A one-dimensional edge between two surfaces, see @ref Cantera.EdgePhase
+
+Additional fields:
+
+`site-density`
+
+The molar density of sites per unit length along the edge
+
+**Example:**
+
+```yaml
+thermo: edge
+site-density: 5.0e-17 mol/cm
+```
+
+# electron-cloud {#sec-yaml-electron-cloud}
+
+A phase representing an electron cloud, such as conduction electrons in
+a metal, see @ref Cantera.MetalPhase.
+
+Additional fields:
+
+`density`
+
+The density of the bulk metal
+
+# fixed-stoichiometry {#sec-yaml-fixed-stoichiometry}
+
+A phase with fixed composition, see @ref Cantera.StoichSubstance.
+
+# HMW-electrolyte {#sec-yaml-HMW-electrolyte}
+
+A dilute or concentrated liquid electrolyte phase that obeys the Pitzer
+formulation for nonideality, see @ref Cantera.HMWSoln.
+
+Additional parameters for this model are contained in the `activity-data` field:
+
+`activity-data`
+
+The activity data field contains the following fields:
+
+- `temperature-model`: The form of the Pitzer temperature model. One of `constant`,
+ `linear` or `complex`. The default is `constant`.
+
+- `A_Debye`: The value of the Debye "A" parameter, or the string `variable`
+ to 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-strength`: The maximum ionic strength
+- `interactions`: A list of mappings, where each mapping describes a binary or
+ ternary interaction among species. Fields of this mapping
+ include:
+
+ - `species`: A list of one to three species names
+ - `beta0`: The @f$\beta^{(0)}@f$ parameters for an cation/anion
+ interaction. 1, 2, or 5 values depending on the value of
+ `temperature-model`.
+ - `beta1`: The @f$\beta^{(1)}@f$ parameters for an cation/anion
+ interaction. 1, 2, or 5 values depending on the value of
+ `temperature-model`.
+ - `beta2`: The @f$\beta^{(2)}@f$ parameters for an cation/anion
+ interaction. 1, 2, or 5 values depending on the value of
+ `temperature-model`.
+ - `Cphi`: The @f$C^\phi@f$ parameters for an cation/anion interaction. 1,
+ 2, or 5 values depending on the value of
+ `temperature-model`.
+ - `alpha1`: The @f$\alpha^{(1)}@f$ parameter for an cation/anion interaction.
+ - `alpha2`: The @f$\alpha^{(2)}@f$ parameter for an cation/anion interaction.
+ - `theta`: The @f$\theta@f$ parameters for a like-charged binary
+ interaction. 1, 2, or 5 values depending on the value of
+ `temperature-model`.
+ - `lambda`: The @f$\lambda@f$ parameters for binary interactions involving
+ at least one neutral species. 1, 2, or 5 values depending on
+ the value of `temperature-model`.
+ - `psi`: The @f$\Psi@f$ parameters for ternary interactions involving
+ three charged species. 1, 2, or 5 values depending on the
+ value of `temperature-model`.
+ - `zeta`: The @f$\zeta@f$ parameters for ternary interactions involving
+ one neutral species. 1, 2, or 5 values depending on the
+ value of `temperature-model`.
+ - `mu`: The @f$\mu@f$ parameters for a neutral species self-interaction.
+ 1, 2, or 5 values depending on the value of
+ `temperature-model`.
+- `cropping-coefficients`:
+ - `ln_gamma_k_min`: Default -5.0.
+ - `ln_gamma_k_max`: Default 15.0.
+ - `ln_gamma_o_min`: Default -6.0.
+ - `ln_gamma_o_max`: Default 3.0.
+
+**Example:**
+
+```yaml
+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-condensed {#sec-yaml-ideal-condensed}
+
+A condensed phase ideal solution, see @ref Cantera.IdealSolidSolnPhase.
+
+Additional fields:
+
+`standard-concentration-basis`
+
+A string specifying the basis for the standard concentration. One of
+`unity`, `species-molar-volume`, or `solvent-molar-volume`.
+
+# ideal-gas {#sec-yaml-ideal-gas}
+
+The ideal gas model, see @ref Cantera.IdealGasPhase.
+
+**Example:**
+
+```yaml
+- 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 {#sec-yaml-ideal-molal-solution}
+
+A phase based on the mixing-rule assumption that all molality-based
+activity coefficients are equal to one, see @ref Cantera.IdealMolalSoln.
+
+Additional fields:
+
+`standard-concentration-basis`
+
+A string specifying the basis for the standard concentration. One of
+`unity`, `species-molar-volume`, or `solvent-molar-volume`.
+
+`cutoff`
+
+Parameters for cutoff treatments of activity coefficients
+
+- `model`: `poly` or `polyExp`
+- `gamma_o`: gamma_o value for the cutoff process at the zero solvent point
+- `gamma_k`: gamma_k minimum for the cutoff process at the zero solvent point
+- `X_o`: value of the solute mole fraction that centers the cutoff
+ polynomials for the cutoff = 1 process
+- `c_0`: Parameter in the polyExp cutoff treatment having to do with rate
+ of exponential decay
+- `slope_f`: Parameter in the `polyExp` cutoff treatment
+- `slope_g`: Parameter in the `polyExp` cutoff treatment
+
+**Example:**
+
+```yaml
+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-solution-VPSS {#sec-yaml-ideal-solution-VPSS}
+
+An ideal solution model using variable pressure standard state methods, see
+@ref Cantera.IdealSolnGasVPSS.
+
+Additional fields:
+
+`standard-concentration-basis`
+
+A string specifying the basis for the standard concentration. One of
+`unity`, `species-molar-volume`, or `solvent-molar-volume`.
+
+# ideal-surface {#sec-yaml-ideal-surface}
+
+An ideal surface phase, see @ref Cantera.SurfPhase.
+
+Additional fields:
+
+`site-density`
+
+The molar density of surface sites
+
+**Example:**
+
+```yaml
+- 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 {#sec-yaml-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, see @ref Cantera.IonsFromNeutralVPSSTP.
+
+@deprecated This phase model is deprecated and will be removed after %Cantera 3.0.
+
+Additional fields:
+
+`neutral-phase`
+
+The `name` of the phase definition for the phase containing the
+neutral molecules.
+
+**Example:**
+
+```yaml
+- name: KCl-ions
+ thermo: ions-from-neutral-molecule
+ neutral-phase: KCl-neutral
+ species: [K+, Cl-]
+- name: KCl-neutral
+ species: [KCl(l)]
+ thermo: Margules
+```
+
+# lattice {#sec-yaml-lattice}
+
+A simple thermodynamic model for a bulk phase, assuming a lattice of
+solid atoms, see @ref Cantera.LatticePhase.
+
+Additional fields:
+
+`site-density`
+
+The molar density of lattice sites
+
+# liquid-water-IAPWS95 {#sec-yaml-liquid-water-IAPWS95}
+
+An equation of state for liquid water, see @ref Cantera.WaterSSTP.
+
+# Margules {#sec-yaml-Margules}
+
+A phase employing the Margules approximation for the excess Gibbs free
+energy, see @ref Cantera.MargulesVPSSTP.
+
+Additional fields:
+
+`interactions`
+
+A list of mappings, where each mapping has the following fields:
+
+- `species`: A list of two species names
+- `excess-enthalpy`: A list of two values specifying the first and second excess
+ enthalpy coefficients for the interaction of the specified
+ species. Defaults to \[0, 0\].
+- `excess-entropy`: A 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-enthalpy`: A 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-entropy`: A 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:**
+
+```yaml
+thermo: Margules
+interactions:
+- species: [KCl(l), LiCl(l)]
+ excess-enthalpy: [-17570, -377]
+ excess-entropy: [-7.627, 4.958]
+```
+
+# Maskell-solid-solution {#sec-yaml-Maskell-solid-solution}
+
+A condensed phase non-ideal solution with two species, see
+@ref Cantera.MaskellSolidSolnPhase.
+
+@deprecated This phase model is deprecated and will be removed after %Cantera 3.0.
+
+Additional fields:
+
+`excess-enthalpy`
+
+The molar excess enthalpy
+
+`product-species`
+
+String specifying the "product" species
+
+**Example:**
+
+```yaml
+thermo: Maskell-solid-solution
+excess-enthalpy: 5 J/mol
+product-species: H(s)
+```
+
+# Peng-Robinson {#sec-yaml-Peng-Robinson}
+
+A multi-species Peng-Robinson phase, see @ref Cantera.PengRobinson.
+
+@since New in %Cantera 3.0
+
+The parameters for each species are contained in the corresponding
+species entries. See @ref sec-yaml-eos-peng-robinson.
+
+# plasma {#sec-yaml-plasma}
+
+A phase for plasma. This phase handles plasma properties such as the
+electron energy distribution and electron temperature with different
+models, see @ref Cantera.PlasmaPhase.
+
+@since New in %Cantera 2.6
+
+Additional fields:
+
+`electron-energy-distribution`
+
+A mapping with the following fields:
+
+- `type`: String specifying the type of the electron energy distribution
+ to be used. Supported model strings are:
+ - `isotropic`
+ - `discretized`
+- `shape-factor`: A 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-energy`: Mean 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-levels`: A list of values specifying the electron energy levels. The
+ default uses 1001 equal spaced points from 0 to 1 eV.
+- `distribution`: A list of values specifying the discretized electron energy
+ distribution. This field is only used with `discretized`.
+- `normalize`: A flag specifying whether normalizing the discretized electron energy
+ distribution or not. This field is only used with `discretized`. Defaults to `true`.
+
+**Example:**
+
+```yaml
+- 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
+```
+
+# pure-fluid {#sec-yaml-pure-fluid}
+
+A phase representing a pure fluid equation of state for one of several
+species, see @ref Cantera.PureFluidPhase.
+
+Additional fields:
+
+`pure-fluid-name`
+
+Name of the pure fluid model to use: - `carbon-dioxide` -
+`heptane` - `HFC-134a` - `hydrogen` - `methane` - `nitrogen` -
+`oxygen` - `water`
+
+# Redlich-Kister {#sec-yaml-Redlich-Kister}
+
+A phase employing the Redlich-Kister approximation for the excess Gibbs
+free energy, see @ref Cantera.RedlichKisterVPSSTP.
+
+Additional fields:
+
+`interactions`
+
+A list of mappings, where each mapping has the following fields:
+
+- `species`: A list of two species names
+- `excess-enthalpy`: A list of polynomial coefficients for the excess enthalpy of the
+ specified binary interaction
+- `excess-entropy`: A list of polynomial coefficients for the excess entropy of the
+ specified binary interaction
+
+**Example:**
+
+```yaml
+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 {#sec-yaml-Redlich-Kwong}
+
+A multi-species Redlich-Kwong phase, see @ref Cantera.RedlichKwongMFTP.
+
+The parameters for each species are contained in the corresponding
+species entries. See @ref sec-yaml-eos-redlich-kwong.
diff --git a/doc/doxygen/yaml/reaction.md b/doc/doxygen/yaml/reaction.md
new file mode 100644
index 0000000000..073e76989d
--- /dev/null
+++ b/doc/doxygen/yaml/reaction.md
@@ -0,0 +1,290 @@
+@page sec-yaml-reactions Reaction Entries
+
+[TOC]
+
+# Overview
+
+%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.
+
+## Reaction Equation {#sec-yaml-reactions-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:
+
+```yaml
+- 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 {#sec-yaml-reactions-type}
+
+The type of the rate coefficient parameterization may be specified in
+the `type` field of the `reaction` entry. Available reaction types are:
+
+- @ref sec-yaml-elementary:
+ A reaction with a rate constant parameterized by a modified Arrhenius expression
+- @ref sec-yaml-three-body:
+ A reaction involving a third-body collision
+- @ref sec-yaml-Blowers-Masel:
+ A reaction rate constant parameterized as a modified Arrhenius
+ reaction with one additional bond energy parameter to scale the
+ activation energy according to the enthalpy of the reaction
+- @ref sec-yaml-two-temperature-plasma
+- @ref sec-yaml-falloff:
+ A pressure-dependent reaction where the rate depends on the third-body
+ concentration at low pressure but not at high pressure
+- @ref sec-yaml-chemically-activated:
+ A pressure-dependent reaction where the rate depends on the third-body
+ concentration at high pressure but not at low pressure
+- @ref sec-yaml-pressure-dependent-Arrhenius:
+ A reaction rate parameterized by logarithmically interpolating between
+ modified Arrhenius expressions at different pressures
+- @ref sec-yaml-Chebyshev:
+ A reaction rate parameterized by a bivariate Chebyshev polynomial in
+ pressure and temperature
+
+Additional parameters defining the rate model for each of these
+reaction types are described in the documentation linked above
+(see also @subpage sec-yaml-reaction-models).
+
+The default parameterization is `elementary`. Reactions without a specified
+`type` on surfaces or edges are automatically treated as
+@ref sec-yaml-interface-Arrhenius reactions, unless a `sticking-coefficient`
+entry implies a @ref sec-yaml-sticking-Arrhenius reaction. Interface reactions
+that involve charge transfer between phases are automatically treated as
+@ref sec-yaml-electrochemical-reaction reactions.
+
+Reactions on surfaces or edges specifying `type` as `Blowers-Masel`
+are treated as @ref sec-yaml-interface-Blowers-Masel or
+@ref sec-yaml-sticking-Blowers-Masel.
+
+## Rate Parameterization
+
+The following reaction rate building blocks are supported:
+
+- @ref sec-yaml-Arrhenius-rate
+- @ref sec-yaml-Blowers-Masel-rate
+- @ref sec-yaml-two-temperature-plasma-rate
+
+Additional parameters defining these building blocks are described in the
+documentation linked above (see also @subpage sec-yaml-reaction-rate-blocks).
+
+Most reaction types in %Cantera are parameterized by one or more modified
+@ref sec-yaml-Arrhenius-rate expressions, such as
+
+@f[
+ A T^b e^{-E_a / RT}
+@f]
+
+where @f$A@f$ is the pre-exponential factor, @f$T@f$ is the temperature, @f$b@f$ is
+the temperature exponent, @f$E_a@f$ is the activation energy, and @f$R@f$ is the
+gas constant. Rates in this form can be written as YAML mappings, where the key `E`
+is used to specify @f$E_a@f$. For example:
+
+```yaml
+{A: 1.0e13, b: 0, E: 7.3 kcal/mol}
+```
+
+The units of @f$A@f$ 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 @f$A@f$ 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
+@f$A@f$, in which case they will be computed taking all of these factors
+into account.
+
+*Note:* if @f$b \ne 0@f$, then the term @f$T^b@f$ should have units of
+@f$\mathrm{K}^b@f$, which would change the units of @f$A@f$. This is not done,
+however, so the units associated with @f$A@f$ are really the units for
+@f$k_f@f$. One way to formally express this is to replace @f$T^b@f$ by the
+non-dimensional quantity @f$[T/(1\;\mathrm{K})]^b@f$.
+
+## Third-Body Colliders {#sec-yaml-reactions-efficiencies}
+
+Some reaction types include parameters for the "efficiency" of
+different species as third-body colliders `M`.
+
+**Example:**
+
+```yaml
+- equation: O + H + M <=> OH + M
+ type: three-body
+ rate-constant: {A: 5.0e+5, b: -1.0, Ea: 0.0}
+ default-efficiency: 0.
+ efficiencies: {H2: 2.0, H2O: 6.0, AR: 0.7}
+```
+
+## Duplicate Reactions {#sec-yaml-reaction-duplicates}
+
+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:
+
+@f[
+ k_f(T) = \sum_{n=1}^{N} A_n T^{b_n} \exp(-E_n/RT)
+@f]
+
+While %Cantera does not provide such a form for reaction rates, it can be
+implemented by defining @f$N@f$ duplicate reactions, and assigning one rate
+coefficient in the sum to each reaction. By adding the field:
+
+```yaml
+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 @f$A_n@f$, 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 @f$A@f$ parameters are acceptable
+can be indicated by adding the field:
+
+```yaml
+negative-A: true
+```
+
+## Reaction Orders {#sec-yaml-reaction-orders}
+
+Explicit reaction orders different from the stoichiometric coefficients
+are sometimes used for non-elementary reactions. For example, consider
+the global reaction:
+
+@f[
+ \mathrm{C_8H_{18} + 12.5 O_2 \rightarrow 8 CO_2 + 9 H_2O}
+@f]
+
+the forward rate constant might be given as[^1]:
+
+@f[
+ k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5}
+ \exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right)
+@f]
+
+This reaction could be defined as:
+
+```yaml
+- 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:
+
+```yaml
+- 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:
+
+```yaml
+- 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
+```
+
+# Reaction API Reference
+
+The fields common to most `reaction` entries are:
+
+`equation`
+
+The stoichiometric equation for the reaction. Each term (that is,
+stoichiometric coefficient, species name, `+` or `<=>`) in the
+equation must be separated by a space.
+
+Reversible reactions may be written using `<=>` or `=` to separate
+reactants and products. Irreversible reactions are written using `=>`.
+See also @ref sec-yaml-reactions-equation.
+
+`type`
+
+A string specifying the type of reaction or rate coefficient
+parameterization, see @ref sec-yaml-reactions-type.
+
+`duplicate`
+
+Boolean indicating whether the reaction is a known duplicate of
+another reaction. The default is `false`.
+See @ref sec-yaml-reaction-duplicates.
+
+`orders`
+
+An optional mapping of species to explicit reaction orders to use.
+Reaction orders for reactant species not explicitly mentioned are
+taken to be their respective stoichiometric coefficients. See
+@ref sec-yaml-reaction-orders for additional information.
+
+`negative-orders`
+
+Boolean indicating whether negative reaction orders are allowed. The
+default is `false`.
+
+`nonreactant-orders`
+
+Boolean indicating whether orders for non-reactant species are
+allowed. The default is `false`.
+
+`efficiencies`
+
+Some reaction types include parameters for the "efficiency" of
+different species as third-body colliders. The `efficiencies` field
+holds a mapping of species names to efficiency values. See
+@ref sec-yaml-reactions-efficiencies.
+
+`default-efficiency`
+
+The efficiency of third-body collider species not included in the
+`efficiencies` mapping. Defaults to 1.0.
+
+Depending on the reaction `type`, other fields may be necessary to
+specify the rate of the reaction.
diff --git a/doc/doxygen/yaml/reactionblocks.md b/doc/doxygen/yaml/reactionblocks.md
new file mode 100644
index 0000000000..8c74b1d461
--- /dev/null
+++ b/doc/doxygen/yaml/reactionblocks.md
@@ -0,0 +1,91 @@
+@page sec-yaml-reaction-rate-blocks Reaction Rate Blocks
+
+[TOC]
+
+The following reaction rate expressions are used as building blocks for most
+@ref sec-yaml-reaction-models.
+
+# Arrhenius {#sec-yaml-Arrhenius-rate}
+
+Arrhenius rate expressions are specified as a mapping with fields:
+
+`A`
+
+The pre-exponential factor @f$ A @f$
+
+`b`
+
+The temperature exponent @f$ b @f$
+
+`Ea`
+
+The activation energy @f$ E_a @f$
+
+or a corresponding three-element list. The following are equivalent:
+
+```yaml
+{A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
+[-2.70000E+13 cm^3/mol/s, 0, 355 cal/mol]
+```
+
+# Blowers-Masel {#sec-yaml-Blowers-Masel-rate}
+
+Blowers-Masel rate expressions calculate the rate constant based on the
+Blowers Masel approximation as [described
+here](https://cantera.org/science/kinetics.html#sec-blowers-masel). The
+rate parameters are specified as a mapping with fields:
+
+`A`
+
+The pre-exponential factor @f$ A@f$
+
+`b`
+
+The temperature exponent @f$ b@f$
+
+`Ea0`
+
+The intrinsic activation energy @f$ E_{a0}@f$
+
+`w`
+
+The average of the bond dissociation energy of the bond breaking and
+that being formed in the reaction @f$ w@f$
+
+or a corresponding four-element list. The following are equivalent:
+
+```yaml
+{A: 3.87e+04 cm^3/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
+[3.87e+04 cm^3/mol/s, 2.7, 6260.0 cal/mol, 1e9 cal/mol]
+```
+
+# Two-Temperature Plasma {#sec-yaml-two-temperature-plasma-rate}
+
+Two-temperature plasma reactions involve an electron as one of the
+reactants, where the electron temperature may differ from the gas
+temperature as [described
+here](https://cantera.org/science/kinetics.html#two-temperature-plasma-reactions).
+The rate parameters are specified as a mapping with fields:
+
+`A`
+
+The pre-exponential factor
+
+`b`
+
+The temperature exponent, which is applied to the electron temperature
+
+`Ea-gas`
+
+The activation energy term @f$ E_{a,g}@f$ that is related to the gas temperature
+
+`Ea-electron`
+
+The activation energy term @f$ E_{a,e}@f$ that is related to the electron temperature
+
+or a corresponding four-element list. The following are equivalent:
+
+```yaml
+{A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
+[17283, -3.1, -5820 J/mol, 1081 J/mol]
+```
diff --git a/doc/doxygen/yaml/reactiontypes.md b/doc/doxygen/yaml/reactiontypes.md
new file mode 100644
index 0000000000..e25ea6f527
--- /dev/null
+++ b/doc/doxygen/yaml/reactiontypes.md
@@ -0,0 +1,348 @@
+
+@page sec-yaml-reaction-models Reaction Models
+
+[TOC]
+
+# elementary {#sec-yaml-elementary}
+
+A homogeneous reaction with a pressure-independent rate coefficient and
+mass action kinetics, as [described
+here](https://cantera.org/science/kinetics.html#reactions-with-a-pressure-independent-rate).
+
+Additional fields are:
+
+`rate-constant`
+
+An @ref sec-yaml-Arrhenius-rate list or mapping.
+
+`negative-A`
+
+A boolean indicating whether a negative value for the
+pre-exponential factor is allowed. The default is `false`.
+
+**Example:**
+
+```yaml
+equation: N + NO <=> N2 + O
+rate-constant: {A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
+negative-A: true
+```
+
+# three-body {#sec-yaml-three-body}
+
+A three body reaction as [described
+here](https://cantera.org/science/kinetics.html#three-body-reactions).
+
+@since Changed in %Cantera 3.0: three body reactions are detected based on the
+reaction equation; the rate parameterization is independent. For three body reactions
+with Arrhenius rate parameterizations, specifying the `type` is optional.
+
+The reaction equation should include the third body collision partner `M`.
+
+Includes the fields of an @ref sec-yaml-elementary reaction, plus the fields
+for specifying @ref sec-yaml-reactions-efficiencies.
+
+**Example:**
+
+```yaml
+equation: 2 O + M = O2 + M
+type: three-body
+rate-constant: [1.20000E+17 cm^6/mol^2/s, -1, 0]
+efficiencies: {AR: 0.83, H2O: 5}
+```
+
+# Blowers-Masel {#sec-yaml-Blowers-Masel}
+
+Includes the fields of an @ref sec-yaml-elementary reaction, except that the
+`rate-constant` field is a @ref sec-yaml-Blowers-Masel-rate list or mapping.
+
+**Example:**
+
+```yaml
+equation: O + H2 <=> H + OH
+type: Blowers-Masel
+rate-constant: {A: 3.87e+04 cm^2/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
+```
+
+@since New in %Cantera 2.6
+
+# two-temperature-plasma {#sec-yaml-two-temperature-plasma}
+
+Includes the fields of an @ref sec-yaml-elementary reaction, except that the
+`rate-constant` field is a @ref sec-yaml-two-temperature-plasma-rate list or mapping.
+
+@since New in %Cantera 2.6
+
+**Example:**
+
+```yaml
+equation: O + H => O + H
+type: two-temperature-plasma
+rate-constant: {A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
+```
+
+# falloff {#sec-yaml-falloff}
+
+A falloff reaction as [described
+here](https://cantera.org/science/kinetics.html#falloff-reactions).
+
+The reaction equation should include the pressure-dependent third body
+collision partner `(+M)` or `(+name)` where `name` is the name of a
+species. The latter case is equivalent to setting the efficiency for
+`name` to 1 and the efficiency for all other species to 0.
+
+Includes field for specifying @ref sec-yaml-reactions-efficiencies as well as:
+
+`high-P-rate-constant`
+
+An @ref sec-yaml-Arrhenius-rate expression for the high-pressure limit
+
+`low-P-rate-constant`
+
+An @ref sec-yaml-Arrhenius-rate expression for the low-pressure limit
+
+`Troe`
+
+Parameters for the
+[Troe](https://cantera.org/science/kinetics.html#the-troe-falloff-function)
+falloff function. A mapping containing the keys `A`, `T3`, `T1` and
+optionally `T2`. The default value for `T2` is 0.
+
+`SRI`
+
+Parameters for the
+[SRI](https://cantera.org/science/kinetics.html#the-sri-falloff-function)
+falloff function. A mapping containing the keys `A`, `B`, `C`, and
+optionally `D` and `E`. The default values for `D` and `E` are 1.0
+and 0.0, respectively.
+
+`Tsang`
+
+Parameters for the
+[Tsang](https://cantera.org/science/kinetics.html#tsang-s-approximation-to-f-cent)
+falloff function. A mapping containing the keys `A` and `B`. The
+default value for `B` is 0.0.
+
+**Example:**
+
+```yaml
+equation: H + CH2 (+ N2) <=> CH3 (+N2)
+type: falloff
+high-P-rate-constant: [6.00000E+14 cm^3/mol/s, 0, 0]
+low-P-rate-constant: {A: 1.04000E+26 cm^6/mol^2/s, b: -2.76, Ea: 1600}
+Troe: {A: 0.562, T3: 91, T1: 5836}
+```
+
+# chemically-activated {#sec-yaml-chemically-activated}
+
+A chemically activated reaction as [described
+here](https://cantera.org/science/kinetics.html#chemically-activated-reactions).
+
+The parameters are the same as for @ref sec-yaml-falloff reactions.
+
+**Example:**
+
+```yaml
+equation: CH3 + OH (+M) <=> CH2O + H2 (+M)
+type: chemically-activated
+high-P-rate-constant: [5.88E-14, 6.721, -3022.227]
+low-P-rate-constant: [282320.078, 1.46878, -3270.56495]
+```
+
+# pressure-dependent-Arrhenius {#sec-yaml-pressure-dependent-Arrhenius}
+
+A pressure-dependent reaction using multiple Arrhenius expressions as
+[described
+here](https://cantera.org/science/kinetics.html#pressure-dependent-arrhenius-rate-expressions-p-log).
+
+The only additional field in this reaction type is:
+
+`rate-constants`
+
+A list of mappings, where each mapping is the mapping form of an
+@ref sec-yaml-Arrhenius-rate expression with the addition of a pressure `P`.
+
+**Example:**
+
+```yaml
+equation: H + CH4 <=> H2 + CH3
+type: pressure-dependent-Arrhenius
+rate-constants:
+- {P: 0.039474 atm, A: 2.720000e+09 cm^3/mol/s, b: 1.2, Ea: 6834.0}
+- {P: 1.0 atm, A: 1.260000e+20, b: -1.83, Ea: 15003.0}
+- {P: 1.0 atm, A: 1.230000e+04, b: 2.68, Ea: 6335.0}
+- {P: 1.01325 MPa, A: 1.680000e+16, b: -0.6, Ea: 14754.0}
+```
+
+# Chebyshev {#sec-yaml-Chebyshev}
+
+A reaction parameterized as a bivariate Chebyshev polynomial as
+[described
+here](https://cantera.org/science/kinetics.html#chebyshev-reaction-rate-expressions).
+
+Additional fields are:
+
+`temperature-range`
+
+A list of two values specifying the minimum and maximum temperatures
+at which the rate constant is valid
+
+`pressure-range`
+
+A list of two values specifying the minimum and maximum pressures at
+which the rate constant is valid
+
+`data`
+
+A list of lists containing the Chebyshev coefficients
+
+**Example:**
+
+```yaml
+equation: CH4 <=> CH3 + H
+type: Chebyshev
+temperature-range: [290, 3000]
+pressure-range: [0.0098692326671601278 atm, 98.692326671601279 atm]
+data: [[-1.44280e+01, 2.59970e-01, -2.24320e-02, -2.78700e-03],
+ [ 2.20630e+01, 4.88090e-01, -3.96430e-02, -5.48110e-03],
+ [-2.32940e-01, 4.01900e-01, -2.60730e-02, -5.04860e-03],
+ [-2.93660e-01, 2.85680e-01, -9.33730e-03, -4.01020e-03],
+ [-2.26210e-01, 1.69190e-01, 4.85810e-03, -2.38030e-03],
+ [-1.43220e-01, 7.71110e-02, 1.27080e-02, -6.41540e-04]]
+```
+
+# interface-Arrhenius {#sec-yaml-interface-Arrhenius}
+
+A reaction occurring on a surface between two bulk phases, or along an
+edge at the intersection of two surfaces, as [described
+here](https://cantera.org/science/kinetics.html#sec-surface).
+
+Includes the fields of an @ref sec-yaml-elementary reaction plus:
+
+`coverage-dependencies`
+
+A mapping of species names to coverage dependence parameters, where
+these parameters are contained in either a mapping with the fields:
+
+- `a`: Coefficient for exponential dependence on the coverage
+- `m`: Power-law exponent of coverage dependence
+- `E`: Activation energy dependence on coverage, which uses the same
+ sign convention as the leading-order activation energy term.
+ This can be a scalar value for the linear dependency or a list
+ of four values for the polynomial dependency given in the order
+ of 1st, 2nd, 3rd, and 4th-order coefficients
+
+or a list containing the three elements above, in the given order.
+
+Note that parameters `a`, `m` and `E` correspond to parameters
+@f$ \eta_{ki}@f$ , @f$ \mu_{ki}@f$ and @f$ \epsilon_{ki}@f$ in Eq 11.113 of
+\[Kee, R. J., Coltrin, M. E., & Glarborg, P.(2003). Chemically
+reacting flow: theory and practice. John Wiley & Sons\],
+respectively.
+
+**Examples:**
+
+```yaml
+- equation: 2 H(s) => H2 + 2 Pt(s)
+ rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea: 67400 J/mol}
+ coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
+
+- equation: 2 O(S) => O2 + 2 Pt(S)
+ rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
+ coverage-dependencies: {O(S): {a: 0.0, m: 0.0,
+ E: [1.0e3 J/mol, 3.0e3 J/mol , -7.0e4 J/mol , 5.0e3 J/mol]}
+
+- equation: CH4 + PT(S) + O(S) => CH3(S) + OH(S)
+ rate-constant: {A: 5.0e+18, b: 0.7, Ea: 4.2e+04}
+ coverage-dependencies:
+ O(S): [0, 0, 8000]
+ PT(S): [0, -1.0, 0]
+
+- equation: 2 O(S) => O2 + 2 Pt(S)
+ rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
+ coverage-dependencies:
+ O(S): [0, 0, [1.0e6, 3.0e6, -7.0e7, 5.0e6]]
+```
+
+# interface-Blowers-Masel {#sec-yaml-interface-Blowers-Masel}
+
+Includes the same fields as @ref sec-yaml-interface-Arrhenius, while using the
+@ref sec-yaml-Blowers-Masel-rate parameterization for the rate constant.
+
+@since New in %Cantera 2.6
+
+**Example:**
+
+```yaml
+equation: 2 H(s) => H2 + 2 Pt(s)
+type: Blowers-Masel
+rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea0: 67400 J/mol, w: 1000000 J/mol}
+coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
+```
+
+# sticking-Arrhenius {#sec-yaml-sticking-Arrhenius}
+
+A sticking reaction occurring on a surface adjacent to a bulk phase, as
+[described here](https://cantera.org/science/kinetics.html#sec-sticking).
+
+Includes the fields of an @ref sec-yaml-interface-Arrhenius reaction plus:
+
+`sticking-coefficient`
+
+An @ref sec-yaml-Arrhenius-rate expression for the sticking coefficient
+
+`Motz-Wise`
+
+A boolean indicating whether to use the Motz-Wise correction factor
+for sticking coefficients near unity. Defaults to `false`.
+
+`sticking-species`
+
+The name of the sticking species. Required if the reaction includes
+multiple non-surface species.
+
+**Example:**
+
+```yaml
+equation: OH + PT(S) => OH(S)
+sticking-coefficient: {A: 1.0, b: 0, Ea: 0}
+```
+
+# sticking-Blowers-Masel {#sec-yaml-sticking-Blowers-Masel}
+
+Includes the same fields as @ref sec-yaml-sticking-Arrhenius, while using the
+@ref sec-yaml-Blowers-Masel-rate parameterization for the sticking coefficient.
+
+@since New in %Cantera 2.6
+
+**Example:**
+
+```yaml
+equation: OH + PT(S) => OH(S)
+type: Blowers-Masel
+sticking-coefficient: {A: 1.0, b: 0, Ea0: 0, w: 100000}
+Motz-Wise: true
+```
+
+# electrochemical {#sec-yaml-electrochemical-reaction}
+
+Interface reactions involving charge transfer between phases.
+
+Includes the fields of an @ref sec-yaml-interface-Arrhenius reaction, plus:
+
+`beta`
+
+The symmetry factor for the reaction. Default is 0.5.
+
+`exchange-current-density-formulation`
+
+Set to `true` if the rate constant parameterizes the exchange
+current density. Default is `false`.
+
+**Example:**
+
+```yaml
+equation: LiC6 <=> Li+(e) + C6
+rate-constant: [5.74, 0.0, 0.0]
+beta: 0.4
+```
diff --git a/doc/doxygen/yaml/species.md b/doc/doxygen/yaml/species.md
new file mode 100644
index 0000000000..2928ae7351
--- /dev/null
+++ b/doc/doxygen/yaml/species.md
@@ -0,0 +1,226 @@
+@page sec-yaml-species Species Entries
+
+[TOC]
+
+# Overview
+
+A species entry in %Cantera is used to specify the name, composition,
+thermodynamic, and transport properties of an individual 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:
+
+```yaml
+[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 number of atoms of an element must be non-negative, except for the
+special "element" `E` that represents an electron.
+
+**Examples:**
+
+```yaml
+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 {#sec-yaml-species-thermo-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.
+
+The parameterization used to provide this information is specified by
+the `model` field of the `thermo` field. The models available are:
+
+- @ref sec-yaml-constant-cp: Constant heat capacity
+- @ref sec-yaml-nasa7: 7-coefficient NASA polynomials in one or two
+ temperature regions
+- @ref sec-yaml-nasa9: 9-coefficient NASA polynomials in one or more
+ temperature regions
+- @ref sec-yaml-piecewise-gibbs: Interpolation between tabulated Gibbs free
+ energies using a constant heat capacity in each temperature interval
+- @ref sec-yaml-shomate: Shomate polynomials in one or two temperature
+ regions
+
+For descriptions of fields used by each model as well as examples,
+see @subpage sec-yaml-species-thermo-models.
+
+## Equation of State {#sec-yaml-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. The models available are:
+
+- @ref sec-yaml-eos-constant-volume: A fixed value of mass density, molar
+ density, or molar volume
+- @ref sec-yaml-eos-density-temperature-polynomial: Mass density
+ parameterized using a cubic polynomial in temperature
+- @ref sec-yaml-eos-hkft: The Helgeson-Kirkham-Flowers-Tanger model for
+ aqueous species
+- @ref sec-yaml-eos-ideal-gas: A species following the ideal gas law
+- @ref sec-yaml-eos-ions-from-neutral: Used with the
+ ions-from-neutral-molecule phase model
+- @ref sec-yaml-eos-liquid-water-iapws95: The IAPWS95 equation of state for
+ water, applied only in the liquid region
+- @ref sec-yaml-eos-molar-volume-temperature-polynomial: Molar volume
+ parameterized using a cubic polynomial in temperature
+- @ref sec-yaml-eos-peng-robinson: A species which follows the Peng-Robinson
+ equation of state
+- @ref sec-yaml-eos-redlich-kwong: A species which follows the Redlich-Kwong
+ equation of state
+
+For descriptions of fields used by each model as well as examples,
+see @subpage sec-yaml-species-eos-models.
+
+## Transport Coefficients {#sec-yaml-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 parameters used depend on the transport model specified at the phase level.
+
+Currently, there is a single model type that is specifically handled:
+
+- @ref sec-yaml-species-transport-gas: Gas phase transport
+
+For descriptions of fields used by the model as well as an example,
+see @subpage sec-yaml-species-transport-models.
+
+## Coverage Dependencies {#sec-yaml-species-coverage}
+
+The coverage-dependent surface species formulation calculates coverage-dependent
+correction factors to the ideal surface phase properties. Used in conjunction with the
+[coverage-dependent surface phase model](@ref sec-yaml-coverage-dependent-surface).
+Supported algebraic models are:
+
+- @ref sec-yaml-species-coverage-linear: Linear dependency model
+- @ref sec-yaml-species-coverage-polynomial: Polynomial dependency model
+- @ref sec-yaml-species-coverage-piecewise-linear:
+ Piecewise-linear dependency model
+- @ref sec-yaml-species-coverage-interpolative:
+ Interpolative dependency model
+
+@since New in %Cantera 3.0
+
+For descriptions of fields used by each model as well as examples,
+see @subpage sec-yaml-species-coverage-models.
+
+# Species API Reference
+
+The fields of a `species` entry are:
+
+`name`
+
+String identifier used for the species. Required.
+
+`composition`
+
+Mapping that specifies the elemental composition of the species, for
+example, `{C: 1, H: 4}`. Required.
+
+`thermo`
+
+Mapping containing the reference state thermodynamic model
+specification and parameters.
+
+- `model`: String specifying the model to be used. Required.
+ See @ref sec-yaml-species-thermo-properties for supported models.
+
+- `reference-pressure`: The reference pressure at which the given
+ thermodynamic properties apply. Defaults to 1 atm.
+
+- Additional fields are specific to the species thermodynamics model.
+ (see @ref sec-yaml-species-thermo-models).
+
+`equation-of-state`
+
+A mapping or list of mappings. Each mapping contains an equation of
+state model specification for the species, any parameters for that
+model, and any parameters for interactions with other species. See
+@ref sec-yaml-species-eos-models. If this field
+is absent and a model is required, the `ideal-gas` model is assumed.
+
+- `model`: String specifying the model to be used. Required.
+ See @ref sec-yaml-species-equation-of-state for supported models.
+
+- Additional fields are specific to the species equation of state model
+ (see @ref sec-yaml-species-eos-models).
+
+`critical-parameters`
+
+Mapping containing parameters related to the critical state of a
+species. Used in models that incorporate "real gas" effects, such
+as @ref sec-yaml-eos-redlich-kwong.
+
+- `critical-temperature`: The critical temperature of the species \[K\]
+
+- `critical-pressure`: The critical pressure of the species \[Pa\]
+
+- `acentric-factor`: Pitzer's acentric factor @f$\omega@f$ \[-\]
+
+`transport`
+
+Mapping containing the species transport model specification and
+parameters.
+
+- `model`: String specifying the model type. See
+ @ref sec-yaml-species-transport-coefficients and
+ @ref sec-yaml-species-transport-models.
+
+`sites`
+
+The number of sites occupied by a surface or edge species. Default is 1.
+
+`Debye-Huckel`
+
+Additional model parameters used in the Debye-Hückel model. See
+@ref sec-yaml-Debye-Huckel for more information.
+
+`coverage-dependencies`
+
+Mappings where keys are the name of species whose coverage affects thermodynamic
+properties of the node-owner species, see @ref Cantera.CoverageDependentSurfPhase.
+
+- `model`: String specifying the model to be used. Required.
+ See @ref sec-yaml-species-coverage for supported models.
+
+- Additional map entries that correspond to an individual dependency between the
+ node-owner species and keyed species (see @ref sec-yaml-species-coverage-models).
diff --git a/doc/doxygen/yaml/speciescoverages.md b/doc/doxygen/yaml/speciescoverages.md
new file mode 100644
index 0000000000..cbd060c161
--- /dev/null
+++ b/doc/doxygen/yaml/speciescoverages.md
@@ -0,0 +1,114 @@
+@page sec-yaml-species-coverage-models Species Coverage Models
+
+[TOC]
+
+Species coverage models are specified using the `coverage-dependencies` field of
+@ref sec-yaml-species.
+
+# linear {#sec-yaml-species-coverage-linear}
+
+@since New in %Cantera 3.0
+
+`enthalpy` and `entropy`
+
+Slope of the coverage-dependent enthalpy or entropy.
+
+**Example:**
+
+```yaml
+coverage-dependencies:
+ O_Pt:
+ model: linear
+ units: {energy: eV, quantity: molec}
+ enthalpy: 0.48
+ entropy: -0.031
+ # + other entries (optional)
+```
+
+# polynomial {#sec-yaml-species-coverage-polynomial}
+
+@since New in %Cantera 3.0
+
+`enthalpy-coefficients` and `entropy-coefficients`
+
+Array of polynomial coefficients in order of 1st, 2nd, 3rd, and
+4th-order used in coverage-dependent enthalpy or entropy calculation.
+
+**Example:**
+
+```yaml
+coverage-dependencies:
+ OC_Pt:
+ model: polynomial
+ units: {energy: J, quantity: mol}
+ enthalpy-coefficients: [0.0, -3.86e4, 0.0, 4.2e5]
+ entropy-coefficients: [0.8e3, 0.0, -1.26e4, 0.0]
+ # + other entries (optional)
+```
+
+# piecewise-linear {#sec-yaml-species-coverage-piecewise-linear}
+
+@since New in %Cantera 3.0
+
+`enthalpy-low` and `entropy-low`
+
+Slope of the coverage-dependent enthalpy or entropy for the lower coverage region.
+
+`enthalpy-high` and `entropy-high`
+
+Slope of the coverage-dependent enthalpy or entropy for the higher coverage region.
+
+`enthalpy-change` and `entropy-change`
+
+Coverage that separates the lower and higher coverage regions of the
+coverage-dependent enthalpy or entropy.
+
+`heat-capacity-a` and `heat-capacity-b`
+
+Coefficient @f$c^{(a)}@f$ or @f$c^{(b)}@f$ used in the coverage-dependent
+`heat capacity` model.
+
+**Example:**
+
+```yaml
+coverage-dependencies:
+ CO2_Pt:
+ model: piecewise-linear
+ units: {energy: kJ, quantity: mol}
+ enthalpy-low: 0.5e2
+ enthalpy-high: 1.0e2
+ enthalpy-change: 0.4
+ entropy-low: 0.1e2
+ entropy-high: -0.2e2
+ entropy-change: 0.4
+ heat-capacity-a: 0.02e-1
+ heat-capacity-b: -0.156e-1
+ # + other entries (optional)
+```
+
+# interpolative {#sec-yaml-species-coverage-interpolative}
+
+@since New in %Cantera 3.0
+
+`enthalpy-coverages` and `entropy-coverages`
+
+Array of discrete coverage values used in coverage-dependent enthalpy or entropy.
+
+`enthalpies` and `entropies`
+
+Array of discrete enthalpy or entropy values corresponding to the
+coverages in `enthalpy-coverages` and `entropy-coverages`, respectively.
+
+**Example:**
+
+```yaml
+coverage-dependencies:
+ C_Pt:
+ model: interpolative
+ units: {energy: kcal, quantity: mol}
+ enthalpy-coverages: [0.0, 0.2, 0.4, 0.7, 0.9, 1.0]
+ entropy-coverages: [0.0, 0.5, 1.0]
+ enthalpies: [0.0, 0.5, 1.0, 2.7, 3.5, 4.0]
+ entropies: [0.0, -0.7, -2.0]
+ # + other entries (optional)
+```
diff --git a/doc/doxygen/yaml/specieseos.md b/doc/doxygen/yaml/specieseos.md
new file mode 100644
index 0000000000..511fbc35ca
--- /dev/null
+++ b/doc/doxygen/yaml/specieseos.md
@@ -0,0 +1,198 @@
+@page sec-yaml-species-eos-models Species Equation of State Models
+
+[TOC]
+
+Species equation of state models are specified using the `equation-of-state` field of
+@ref sec-yaml-species.
+
+# constant-volume {#sec-yaml-eos-constant-volume}
+
+A constant volume model, see @ref Cantera.PDSS_ConstVol.
+
+Any one of the following may be specified:
+
+`molar-volume`
+
+The molar volume of the species.
+
+`molar-density`
+
+The molar density of the species.
+
+`density`
+
+The mass density of the species.
+
+**Example:**
+
+```yaml
+equation-of-state:
+ model: constant-volume
+ molar-volume: 1.3 cm^3/mol
+```
+
+# density-temperature-polynomial {#sec-yaml-eos-density-temperature-polynomial}
+
+A model in which the density varies with temperature, see @ref Cantera.PDSS_SSVol.
+
+Additional fields:
+
+`data`
+
+Vector of 4 coefficients for a cubic polynomial in temperature
+
+**Example:**
+
+```yaml
+equation-of-state:
+ model: density-temperature-polynomial
+ units: {mass: g, length: cm}
+ data: [0.536504, -1.04279e-4, 3.84825e-9, -5.2853e-12]
+```
+
+# HKFT {#sec-yaml-eos-hkft}
+
+The Helgeson-Kirkham-Flowers-Tanger model, see @ref Cantera.PDSS_HKFT.
+
+Additional fields:
+
+`h0`
+
+Enthalpy of formation at the reference temperature and pressure
+
+`s0`
+
+Entropy of formation at the reference temperature and pressure
+
+`a`
+
+4-element vector containing the coefficients @f$a_1, \ldots , a_4@f$
+
+`c`
+
+2-element vector containing the coefficients @f$c_1@f$ and @f$c_2@f$
+
+`omega`
+
+The @f$\omega@f$ parameter at the reference temperature and pressure
+
+**Example:**
+
+```yaml
+equation-of-state:
+ model: HKFT
+ h0: -57433. cal/gmol
+ s0: 13.96 cal/gmol/K
+ a: [0.1839 cal/gmol/bar, -228.5 cal/gmol,
+ 3.256 cal*K/gmol/bar, -27260. cal*K/gmol]
+ c: [18.18 cal/gmol/K, -29810. cal*K/gmol]
+ omega: 33060 cal/gmol
+```
+
+# ideal-gas {#sec-yaml-eos-ideal-gas}
+
+A species using the ideal gas equation of state, see @ref Cantera.PDSS_IdealGas.
+
+@deprecated Deprecated in %Cantera 3.0; handled at the phase level for all species
+in an ideal gas.
+
+# ions-from-neutral-molecule {#sec-yaml-eos-ions-from-neutral}
+
+A species equation of state model used with the `ions-from-neutral-molecule` phase
+model, see @ref Cantera.PDSS_IonsFromNeutral.
+
+@deprecated This species thermo model is deprecated and will be removed after %Cantera 3.0.
+
+Additional fields:
+
+`special-species`
+
+Boolean indicating whether the species is the "special species" in
+the phase. Default is `false`.
+
+`multipliers`
+
+A dictionary mapping species to neutral species multiplier values.
+
+**Example:**
+
+```yaml
+equation-of-state:
+ model: ions-from-neutral-molecule
+ multipliers: {KCl(l): 1.2}
+```
+
+# liquid-water-IAPWS95 {#sec-yaml-eos-liquid-water-iapws95}
+
+A detailed equation of state for liquid water, see @ref Cantera.PDSS_Water.
+
+# molar-volume-temperature-polynomial {#sec-yaml-eos-molar-volume-temperature-polynomial}
+
+A model in which the molar volume varies with temperature, see @ref Cantera.PDSS_SSVol.
+
+Additional fields:
+
+`data`
+
+Vector of 4 coefficients for a cubic polynomial in temperature
+
+# Peng-Robinson {#sec-yaml-eos-peng-robinson}
+
+A model where species follow the Peng-Robinson equation of state, see
+@ref Cantera.PengRobinson.
+
+@since New in %Cantera 3.0
+
+Additional fields:
+
+`a`
+
+Pure-species `a` coefficient \[Pa\*m\^6/kmol\^2\]
+
+`b`
+
+Pure-species `b` coefficient \[m\^3/kmol\]
+
+`acentric-factor`
+
+Pitzer's acentric factor \[-\]
+
+`binary-a`
+
+Optional mapping where the keys are species names and the values are
+the `a` coefficients for binary interactions between the two species.
+
+**Example:**
+
+```yaml
+equation-of-state:
+ model: Peng-Robinson
+ units: {length: cm, quantity: mol}
+ a: 5.998873E+11
+ b: 18.9714
+ acentric-factor: 0.344
+ binary-a:
+ H2: 4 bar*cm^6/mol^2
+ CO2: 7.897e7 bar*cm^6/mol^2
+```
+
+# Redlich-Kwong {#sec-yaml-eos-redlich-kwong}
+
+A model where species follow the Redlich-Kwong equation of state, see
+@ref Cantera.RedlichKwongMFTP.
+
+Additional fields:
+
+`a`
+
+Pure-species `a` coefficient. Scalar or list of two values for a
+temperature-dependent expression.
+
+`b`
+
+Pure-species `b` coefficient.
+
+`binary-a`
+
+Mapping where the keys are species and the values are the `a`
+coefficients for binary interactions between the two species.
diff --git a/doc/doxygen/yaml/speciesthermo.md b/doc/doxygen/yaml/speciesthermo.md
new file mode 100644
index 0000000000..1bda32e14c
--- /dev/null
+++ b/doc/doxygen/yaml/speciesthermo.md
@@ -0,0 +1,209 @@
+@page sec-yaml-species-thermo-models Species Thermodynamic Models
+
+[TOC]
+
+Species thermodynamic models are specified using the `thermo` field of
+@ref sec-yaml-species.
+
+# constant-cp {#sec-yaml-constant-cp}
+
+The constant heat capacity model, see @ref Cantera.ConstCpPoly or [described
+here](https://cantera.org/science/species-thermo.html#constant-heat-capacity).
+
+Additional fields of a `constant-cp` thermo entry are:
+
+`T0`
+
+The reference temperature. Defaults to 298.15 K.
+
+`h0`
+
+The molar enthalpy at the reference temperature. Defaults to 0.0.
+
+`s0`
+
+The molar entropy at the reference temperature. Defaults to 0.0.
+
+`cp0`
+
+The heat capacity at constant pressure. Defaults to 0.0.
+
+`T-min`
+
+The minimum temperature at which this thermo data should be used.
+Defaults to 0.0.
+
+`T-max`
+
+The maximum temperature at which this thermo data should be used.
+Defaults to infinity.
+
+**Example:**
+
+```yaml
+thermo:
+ model: constant-cp
+ T0: 1000 K
+ h0: 9.22 kcal/mol
+ s0: -3.02 cal/mol/K
+ cp0: 5.95 cal/mol/K
+```
+
+# NASA7 {#sec-yaml-nasa7}
+
+The NASA 7-coefficient polynomial form given for one (@ref Cantera.NasaPoly1) or two
+temperature regions (@ref Cantera.NasaPoly2); also [described
+here](https://cantera.org/science/species-thermo.html#the-nasa-7-coefficient-polynomial-parameterization).
+
+Additional fields of a `NASA7` thermo entry are:
+
+`temperature-ranges`
+
+A list giving the temperature intervals on which the polynomials are
+valid. For one temperature region, this list contains the minimum
+and maximum temperatures for the polynomial. For two temperature
+regions, this list contains the minimum, intermediate, and maximum
+temperatures.
+
+`data`
+
+A list with one item per temperature region, where that item is a 7
+item list of polynomial coefficients. The temperature regions are
+arranged in ascending order. Note that this is different from the
+standard CHEMKIN formulation that uses two temperature regions
+listed in descending order.
+
+**Example:**
+
+```yaml
+thermo:
+ model: NASA7
+ temperature-ranges: [300.0, 1000.0, 5000.0]
+ data:
+ - [3.298677, 0.0014082404, -3.963222e-06, 5.641515e-09,
+ -2.444854e-12, -1020.8999, 3.950372]
+ - [2.92664, 0.0014879768, -5.68476e-07, 1.0097038e-10,
+ -6.753351e-15, -922.7977, 5.980528]
+```
+
+# NASA9 {#sec-yaml-nasa9}
+
+The NASA 9-coefficient polynomial form given for a single (@ref Cantera.Nasa9Poly1) or
+multiple temperature regions (@ref Cantera.Nasa9PolyMultiTempRegion); also [described
+here](https://cantera.org/science/species-thermo.html#the-nasa-9-coefficient-polynomial-parameterization).
+
+Additional fields of a `NASA9` thermo entry are:
+
+`temperature-ranges`
+
+A list giving the temperature intervals on which the polynomials are
+valid. This list contains the minimum temperature, the intermediate
+temperatures between each set pair of regions, and the maximum
+temperature.
+
+`data`
+
+A list with one item per temperature region, where that item is a 9
+item list of polynomial coefficients. The temperature regions are
+arranged in ascending order.
+
+**Example:**
+
+```yaml
+thermo:
+ model: NASA9
+ temperature-ranges: [200.00, 1000.00, 6000.0, 20000]
+ reference-pressure: 1 bar
+ data:
+ - [2.210371497E+04, -3.818461820E+02, 6.082738360E+00, -8.530914410E-03,
+ 1.384646189E-05, -9.625793620E-09, 2.519705809E-12, 7.108460860E+02,
+ -1.076003744E+01]
+ - [5.877124060E+05, -2.239249073E+03, 6.066949220E+00, -6.139685500E-04,
+ 1.491806679E-07, -1.923105485E-11, 1.061954386E-15, 1.283210415E+04,
+ -1.586640027E+01]
+ - [8.310139160E+08, -6.420733540E+05, 2.020264635E+02, -3.065092046E-02,
+ 2.486903333E-06, -9.705954110E-11, 1.437538881E-15, 4.938707040E+06,
+ -1.672099740E+03]
+```
+
+# piecewise-Gibbs {#sec-yaml-piecewise-gibbs}
+
+A model based on piecewise interpolation of the Gibbs free energy, see
+@ref Cantera.Mu0Poly.
+
+Additional fields of a `piecewise-Gibbs` entry are:
+
+`h0`
+
+The molar enthalpy at the reference temperature of 298.15 K.
+Defaults to 0.0.
+
+`dimensionless`
+
+A boolean flag indicating whether the values of the Gibbs free
+energy are given in a dimensionless form, that is, divided by @f$RT@f$.
+Defaults to `false`.
+
+`data`
+
+A mapping of temperatures to values of the Gibbs free energy. The
+Gibbs free energy can be either in molar units (if `dimensionless`
+is `false`) or nondimensionalized by the corresponding temperature
+(if `dimensionless` is `true`). A value must be provided at
+@f$T^\circ = 298.15@f$ K.
+
+`T-min`
+
+The minimum temperature at which this thermo data should be used.
+Defaults to 0.0.
+
+`T-max`
+
+The maximum temperature at which this thermo data should be used.
+Defaults to infinity.
+
+**Example:**
+
+```yaml
+thermo:
+ model: piecewise-Gibbs
+ h0: -230.015 kJ/mol
+ dimensionless: true
+ data: {298.15: -91.50963, 333.15: -85.0}
+```
+
+# Shomate {#sec-yaml-shomate}
+
+The Shomate polynomial form given for one (@ref Cantera.ShomatePoly) or two temperature
+regions (@ref Cantera.ShomatePoly2); also [described
+here](https://cantera.org/science/species-thermo.html#the-shomate-parameterization).
+
+Additional fields of a `Shomate` thermo entry are:
+
+`temperature-ranges`
+
+A list giving the temperature intervals on which the polynomials are
+valid. For one temperature region, this list contains the minimum
+and maximum temperatures for the polynomial. For two temperature
+regions, this list contains the minimum, intermediate, and maximum
+temperatures.
+
+`data`
+
+A list with one item per temperature region, where that item is a 7
+item list of polynomial coefficients. The temperature regions are
+arranged in ascending order.
+
+**Example:**
+
+```yaml
+thermo:
+ model: Shomate
+ temperature-ranges: [298, 1300, 6000]
+ reference-pressure: 1 bar
+ data:
+ - [25.56759, 6.096130, 4.054656, -2.671301, 0.131021,
+ -118.0089, 227.3665]
+ - [35.15070, 1.300095, -0.205921, 0.013550, -3.282780,
+ -127.8375, 231.7120]
+```
diff --git a/doc/doxygen/yaml/speciestransport.md b/doc/doxygen/yaml/speciestransport.md
new file mode 100644
index 0000000000..0bf85b2b92
--- /dev/null
+++ b/doc/doxygen/yaml/speciestransport.md
@@ -0,0 +1,63 @@
+@page sec-yaml-species-transport-models Species Transport Models
+
+Species transport models are specified using the `transport` field of
+@ref sec-yaml-species.
+
+Species transport properties are a rare exception to %Cantera's use of
+SI units, and use the units in which these properties are customarily
+reported. No conversions are supported.
+
+# gas {#sec-yaml-species-transport-gas}
+
+The fields of a `gas` transport entry are:
+
+`geometry`
+
+A string specifying the geometry of the molecule. One of `atom`,
+`linear`, or `nonlinear`.
+
+`diameter`
+
+The Lennard-Jones collision diameter \[Å\]
+
+`well-depth`
+
+The Lennard-Jones well depth \[K\]
+
+`dipole`
+
+The permanent dipole moment \[Debye\]. Default 0.0.
+
+`polarizability`
+
+The dipole polarizability \[Å\^3\]. Default 0.0.
+
+`rotational-relaxation`
+
+The rotational relaxation collision number at 298 K \[-\]. Default 0.0.
+
+`acentric-factor`
+
+Pitzer's acentric factor \[-\]. Default 0.0. This value may also be
+specified as part of the `critical-parameters` field,
+in which case the value provided there supersedes this one.
+
+`dispersion-coefficient`
+
+The dispersion coefficient, normalized by @f$e^2@f$ \[Å\^5\]. Default 0.0.
+
+`quadrupole-polarizability`
+
+The quadrupole polarizability \[Å\^5\]. Default 0.0.
+
+**Example:**
+
+```yaml
+transport:
+ model: gas
+ geometry: linear
+ well-depth: 107.4
+ diameter: 3.458
+ polarizability: 1.6
+ rotational-relaxation: 3.8
+```
diff --git a/doc/doxygen/yaml/units.md b/doc/doxygen/yaml/units.md
new file mode 100644
index 0000000000..6d2d520a33
--- /dev/null
+++ b/doc/doxygen/yaml/units.md
@@ -0,0 +1,94 @@
+
+@page sec-yaml-units Input Units
+
+[TOC]
+
+While %Cantera generally works internally in SI units, input values can
+be provided using a number of different units.
+
+# Overview
+
+Compound units are written using the asterisk (`*`) to indicate
+multiplication, the forward slash (`/`) to indicate division, and the
+caret (`^`) to indicate exponentiation. Exponents can include negative
+and decimal values. Standard one-letter metric prefixes can be applied
+to any unit. Supported base units are:
+
+- Mass: `g`
+- Length: `m`, `micron`, `angstrom`, `Å`
+- Time: `s`, `min`, `hr`
+- Temperature: `K`, `C`
+- Current: `A`
+- Quantity: `mol` (gram mole), `gmol`, `mole`, `kmol`, `kgmol`, `molec`
+
+Supported compound units are:
+
+- Energy: `J`, `cal`, `erg`, `eV`
+- Activation Energy: `K`, any unit of energy per quantity (`J/kmol`,
+ `cal/mol`, etc.), or any unit of energy (such as [eV])
+- Force: `N`, `dyn`
+- Pressure: `Pa`, `atm`, `bar`, `dyn/cm^2`
+- Volume: `m^3`, `liter`, `L`, `l`, `cc`
+- Other electrical units: `ohm`, `V`, `coulomb`
+
+Units can be specified on individual input values by placing them after
+the value, separated by a space:
+
+```yaml
+{A: 1.45e9 cm^3/kmol, b: 0.4, Ea: 21033 kJ/kmol}
+```
+
+or by using a `units` mapping:
+
+```yaml
+units: {mass: g, quantity: mol, pressure: atm, activation-energy: cal/mol}
+```
+
+A `units` mapping will set the default units for all values within the
+same YAML list or mapping, including any nested lists and mappings.
+Units not specified by a mapping use the values from higher level
+mappings, or the %Cantera defaults if no `units` mapping specifies
+applicable units. If a `units` mapping appears in a list, it must be the
+first item in that list.
+
+Default units may be set for `mass`, `length`, `time`, `temperature`,
+`current`, `quantity`, `pressure`, `energy`, and `activation-energy`.
+The units `pressure` and `energy` are used when these units appear
+explicitly in the units that a value is being converted to within
+%Cantera. For example, a conversion to `N/m^2` will use the default units
+for mass, length, and time, while a conversion to `Pa` will use the
+default units for pressure.
+
+Activation energies given in temperature units will be implicitly
+converted to energy per quantity by dividing by the gas constant.
+Activation energies given in pure energy units such as eV will be
+converted to energy per quantity by multiplying by the Avogadro
+constant. Setting default units for `energy` and `quantity` will
+determine the default units of `activation-energy`, which can be
+overridden by explicitly giving the desired units of
+`activation-energy`.
+
+# Default Units {#sec-yaml-units-default}
+
+Default units that apply to a whole input file or some portion thereof
+can be set using `units` mapping. A `units` mapping placed at the top
+level of an input file applies to the entire file. A `units` mapping
+placed as a member of another mapping applies to that mapping and any
+nested mappings or sequences, and overrides higher-level `units`
+mappings:
+
+```yaml
+units: {length: cm, mass: kg}
+section1:
+ units: {length: m}
+ density: 4000 # interpreted as 4000 kg/m^3
+section2:
+ density: 0.1 # interpreted as 0.1 kg/cm^3
+section3:
+- units: {mass: mg} # must be the first item in the list
+- name: species1
+ density: 5e4 # interpreted as 5e4 mg/cm^3
+```
+
+Default units may be set for `mass`, `length`, `time`, `quantity`,
+`pressure`, `energy`, and `activation-energy`.
diff --git a/doc/doxygen/yaml/yamlreference.md b/doc/doxygen/yaml/yamlreference.md
new file mode 100644
index 0000000000..82b26a65cd
--- /dev/null
+++ b/doc/doxygen/yaml/yamlreference.md
@@ -0,0 +1,35 @@
+@page sec-yaml-api YAML Format Reference
+
+All calculations in %Cantera require an input file to describe the properties of the
+relevant phase(s) of matter. %Cantera uses the
+[YAML data language](https://yaml.org/spec/1.2/spec.html#Introduction) to specify
+information on thermodynamics, kinetics, and transport in a single file.
+
+- @subpage sec-yaml-general
+- @subpage sec-yaml-units
+- @subpage sec-yaml-phases
+ - @ref sec-yaml-phase-thermo-models
+- @subpage sec-yaml-elements
+- @subpage sec-yaml-species
+ - @ref sec-yaml-species-thermo-models
+ - @ref sec-yaml-species-eos-models
+ - @ref sec-yaml-species-transport-models
+ - @ref sec-yaml-species-coverage-models
+- @subpage sec-yaml-reactions
+ - @ref sec-yaml-reaction-rate-blocks
+ - @ref sec-yaml-reaction-models
+
+For an introductory tutorial of the YAML data language, refer to the
+@ref sec-yaml-format-tutorial.
+
+# Conversion Utilities {#sec-yaml-conversion}
+
+%Cantera provides the following conversion utilities to obtain YAML input from other
+input file formats:
+
+- [ck2yaml](https://cantera.org/tutorials/ck2yaml-tutorial.html) Conversion
+ from Chemkin-format files to YAML
+- [cti2yaml](https://cantera.org/tutorials/legacy2yaml.html#cti2yaml)
+ Conversion of legacy %Cantera CTI files to YAML
+- [ctml2yaml](https://cantera.org/tutorials/legacy2yaml.html#cti2yaml)
+ Conversion of legacy %Cantera XML (CTML) files to YAML
diff --git a/doc/doxygen/yaml/yamltutorial.md b/doc/doxygen/yaml/yamltutorial.md
new file mode 100644
index 0000000000..fa59929e55
--- /dev/null
+++ b/doc/doxygen/yaml/yamltutorial.md
@@ -0,0 +1,298 @@
+@page sec-yaml-format-tutorial YAML Format Tutorial
+
+[TOC]
+
+Here we describe the syntax and structure of %Cantera YAML files, how
+dimensional values in %Cantera YAML files are handled, and how to
+understand some of the error messages that may be encountered when
+reading these input files.
+
+# Syntax
+
+%Cantera YAML files use a subset of the [YAML 1.2](https://yaml.org/spec/1.2/spec.html)
+specification. %Cantera YAML files consist of individual values, which may be strings,
+numbers or booleans, that are then composed as elements of nested mappings and
+sequences.
+
+# Strings
+
+Strings may be generally written without quotes, but may be enclosed in
+single quotes or double quotes if needed in order to avoid certain
+parsing ambiguities.
+
+```yaml
+A string
+Another 'string'
+"A string: that requires quotes"
+```
+
+# Numbers
+
+Numbers can be written as integers, decimal values, or using E-notation
+
+```yaml
+3
+3.14
+6.022e23
+```
+
+# Booleans
+
+Boolean values in YAML are written as the words `true` or `false`.
+
+# Sequences
+
+A sequence of multiple items is specified by separating the items by
+commas and enclosing them in square brackets. The individual items can
+have any type \--strings, integers, floating-point numbers, mappings, or
+sequences.
+
+```yaml
+elements: [O, H, C, N, Ar]
+temperature-ranges: [200.0, 1000.0, 3500.0]
+```
+
+The syntax above, using square brackets to define a list, is called
+**flow style** in YAML. Sequences can also be written in **block style**,
+using one line for each item in the sequence, with each line starting with a dash:
+
+```yaml
+elements:
+- O
+- H
+- C
+- N
+- Ar
+```
+
+Sequences can also be nested. The following examples are all equivalent:
+
+```yaml
+data: [[1, 2], [3, 4]]
+
+data:
+-
+ - 1
+ - 2
+-
+ - 3
+ - 4
+
+data:
+- - 1
+ - 2
+- - 3
+ - 4
+```
+
+# Mappings
+
+A mapping is a container consisting of key\--value pairs. The keys in a
+mapping must be unique. Like sequences, there are two ways to write a
+mapping. In the **flow style**, the mapping is enclosed in curly
+brackets, colons (followed by spaces) are used to separate keys and
+values, and key\--value pairs are separated by commas:
+
+```yaml
+composition: {H: 2, C: 1, O: 1}
+```
+
+In the **block style**, each key is written on a new line, followed by a
+colon. The value can be placed either on the same line, or on the
+following line, indented one level:
+
+```yaml
+composition:
+ H: 2
+ C:
+ 1
+ O: 1
+```
+
+All keys in %Cantera YAML files are treated as strings. A %Cantera YAML
+file is itself a mapping, usually in the **block style**. We refer to
+the keys in this top-level mapping as the **sections** of the input
+file.
+
+# Sequences of Mappings
+
+A common structure in %Cantera input files is a nested sequence of
+mappings. This can be written in the **block style** as:
+
+```yaml
+- equation: O2 + CO <=> O + CO2
+ rate-constant: {A: 2.5e+12, b: 0, Ea: 47800}
+- equation: O2 + CH2O <=> HO2 + HCO
+ rate-constant: {A: 1.0e+14, b: 0, Ea: 40000}
+- equation: H + O2 + M <=> HO2 + M
+ type: three-body
+ rate-constant: {A: 2.8e+18, b: -0.86, Ea: 0}
+ efficiencies: {AR: 0, C2H6: 1.5, CO: 0.75, CO2: 1.5, H2O: 0, N2: 0, O2: 0}
+```
+
+The keys in each mapping need not be the same. In this example, each of
+the three mappings in the sequence has `equation` and `rate-constant`
+keys, while only the third entry has `type` and `efficiencies` keys.
+
+# Comments
+
+The character `#` is the comment character. Everything to the right of
+this character on a line is ignored:
+
+```yaml
+# set the default units
+units:
+ length: cm # use centimeters for length
+ quantity: mol # use moles for quantity
+```
+
+# Dimensional Values
+
+Many fields have numerical values that represent dimensional
+quantities\-\--a pressure, or a density, for example. If these are
+entered without specifying the units, the default units (set by the
+`units` directive) will be used. However, it is also possible to specify
+the units for each individual dimensional quantity, unless stated
+otherwise. All that is required is to write the units after the value,
+separated by a space:
+
+```yaml
+pressure: 1.0e5 # default is Pascals
+pressure: 1.0 bar # this is equivalent
+density: 4.0 g/cm^3
+density: 4000.0 # kg/m^3
+```
+
+Compound unit strings may be used, as long as a few rules are followed:
+
+1. Units in the denominator follow `/`.
+2. Units in the numerator follow `*`, except for the first one.
+3. Numerical exponents follow the unit string with a `^` character.
+
+Examples of compound units:
+
+```yaml
+A: 1.0e20 cm^6/mol^2/s # OK
+h: 6.626e-34 J*s # OK
+density: 3.0 g*cm^-3 # OK
+A: 1.0e20 cm6/mol/s # error (missing '^')
+A: 1.0e20 cm^6/mol^2-s # error ('s' should be in denominator)
+density: 3.0g/cm^3 # error (missing space between value and units)
+```
+
+See the @ref sec-yaml-units documentation for additional details,
+including the full set of supported units.
+
+# Error Handling
+
+During processing of an input file, errors may be encountered. These
+could be syntax errors, or could be ones that are flagged as errors by
+%Cantera due to some apparent inconsistency in the data\-\--an unphysical
+value, a species that contains an undeclared element, a reaction that
+contains an undeclared species, missing species or element definitions,
+multiple definitions of elements, species, or reactions, and so on.
+
+# Syntax Errors
+
+Syntax errors are caught by the YAML parser, and must be corrected
+before proceeding further. If a syntax error is encountered, %Cantera
+will raise an exception which includes the location of the error.
+Additional information such as a traceback showing where in the code the
+input file was being read may be printed as well.
+
+For example, consider the following input file, which is intended to
+create a gas with the species and reactions of GRI-Mech 3.0, but is
+missing the colon which is needed after the `thermo` key:
+
+```yaml
+phases:
+- name: gas
+ thermo ideal-gas
+ kinetics: gas
+ elements: [H, O]
+ species: [{gri30.yaml/species: all}]
+ reactions: [gri30.yaml/reactions]
+```
+
+When this definition is imported into an application, an error message
+like the following would be printed to the screen, and execution of the
+program or script would terminate:
+
+``` python
+Traceback (most recent call last):
+ File "", line 1, in
+ File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__
+ self._init_yaml(infile, phaseid, phases, yaml)
+ File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml
+ root = AnyMapFromYamlFile(stringify(infile))
+cantera._cantera.CanteraError:
+***********************************************************************
+InputFileError thrown by AnyMap::fromYamlFile:
+Error on line 4 of ./gas.yaml:
+illegal map value
+| Line |
+| 1 | phases:
+| 2 | - name: gas
+| 3 | thermo ideal-gas
+> 4 > kinetics: gas
+ ^
+| 5 | elements: [H, O]
+| 6 | species: [{gri30.yaml/species: all}]
+| 7 | reactions: [gri30.yaml/reactions]
+***********************************************************************
+```
+
+The top part of the error message shows the chain of functions that were
+called before the error was encountered. For the most part, these are
+internal %Cantera functions not of direct concern here. The relevant part
+of this error message is the part between the lines of asterisks. This
+message says that the YAML parser ran into a problem on line 4 of
+`gas.yaml`. In many cases, including this one, the parser will fail
+somewhere *after* the actual problem with the input file, since it must
+continue parsing until it finds something that cannot possibly be valid
+YAML syntax. In this case, the problem from the parser's perspective is
+that the key which started on line 3 continues across a new line before
+it finds a colon that can be considered as the separator. Since a key
+can't be broken across lines like this, the parser indicates the error
+at the point where it found the colon. By looking back from the
+indicated point of the error, we can see that the problem is the missing
+colon in the previous line.
+
+# Cantera Errors
+
+Now let's consider the other class of errors, ones that %Cantera itself
+detects. Continuing the example above, suppose that the missing colon is
+corrected, and the input file processed again. Again an error message
+results, but this time it is from %Cantera:
+
+``` python
+Traceback (most recent call last):
+ File "", line 1, in
+ File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__
+ self._init_yaml(infile, phaseid, phases, yaml)
+ File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml
+ root = AnyMapFromYamlFile(stringify(infile))
+cantera._cantera.CanteraError:
+***********************************************************************
+CanteraError thrown by Phase::addSpecies:
+Species 'C' contains an undefined element 'C'.
+***********************************************************************
+```
+
+The problem is that the phase definition specifies that all species are
+to be imported from the `gri30` mechanism, but only the elements H and O
+are declared. The `gri30` mechanism contains species composed of the
+elements H, O, C, N, and Ar. If the definition is modified to declare
+these additional elements:
+
+```yaml
+phases:
+- name: gas
+ thermo: ideal-gas
+ kinetics: gas
+ elements: [H, O, C, N, Ar]
+ species: [{gri30.yaml/species: all}]
+ reactions: [gri30.yaml/reactions]
+```
+
+it may be imported successfully.
diff --git a/doc/sphinx/yaml/elements.rst b/doc/sphinx/yaml/elements.rst
deleted file mode 100644
index 5866b9141f..0000000000
--- a/doc/sphinx/yaml/elements.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-.. highlight:: yaml
-
-.. _sec-yaml-elements:
-
-********
-Elements
-********
-
-``element`` entries are needed only when defining custom elements that are not
-standard chemical elements, or defining specific isotopes.
-
-The fields of an ``element`` entry are:
-
-``symbol``
- The symbol used for the element, as used when specifying the composition of
- 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.
diff --git a/doc/sphinx/yaml/general.rst b/doc/sphinx/yaml/general.rst
deleted file mode 100644
index 123a8a4e0b..0000000000
--- a/doc/sphinx/yaml/general.rst
+++ /dev/null
@@ -1,101 +0,0 @@
-.. highlight:: yaml
-
-*****************
-General Structure
-*****************
-
-Sections
---------
-
-The top level of a Cantera `YAML `__
-input file is a mapping that defines different input file sections. Each
-section consists of a list of mappings that define objects of the same type,
-such as reactions, species, phases, or elements. The ``phases`` section of an input
-file contains all of the phase definitions. Multiple sections containing
-reaction, species, or element definitions can be used. The specific names
-``reactions``, ``species``, and ``elements`` are used as defaults when looking
-for :ref:`sec-yaml-reactions`, :ref:`sec-yaml-species`, and
-:ref:`sec-yaml-elements` to add to a phase. A simple input file has the
-following structure::
-
- phases:
- - name: spam
- thermo: ideal-gas
- # Additional fields come after this
- - name: green-eggs
- thermo: model-name
- # Additional fields come after this
-
- species:
- - name: A
- # Additional fields come after this
- - name: B
- # Additional fields come after this
- - name: C
- # Additional fields come after this
-
- reactions:
- - equation: A + B <=> C + D
- # Additional fields come after this
- - equation: A + C <=> 2 D
- # Additional fields come after this
-
-.. _sec-yaml-units:
-
-Units
------
-
-While Cantera generally works internally in SI units, input values can be
-provided using a number of different units.
-
-Compound units are written using the asterisk (``*``) to indicate
-multiplication, the forward slash (``/``) to indicate division, and the caret
-(``^``) to indicate exponentiation. Exponents can include negative and decimal
-values. Standard one-letter metric prefixes can be applied to any unit.
-Supported base units are:
-
-- Mass: ``g``
-- Length: ``m``, ``micron``, ``angstrom``, ``Å``
-- Time: ``s``, ``min``, ``hr``
-- Temperature: ``K``, ``C``
-- Current: ``A``
-- Quantity: ``mol`` (gram mole), ``gmol``, ``mole``, ``kmol``, ``kgmol``, ``molec``
-
-Supported compound units are:
-
-- Energy: ``J``, ``cal``, ``erg``, ``eV``
-- Activation Energy: ``K``, any unit of energy per quantity (``J/kmol``,
- ``cal/mol``, etc.), or any unit of energy (such as `eV`)
-- Force: ``N``, ``dyn``
-- Pressure: ``Pa``, ``atm``, ``bar``, ``dyn/cm^2``
-- Volume: ``m^3``, ``liter``, ``L``, ``l``, ``cc``
-- Other electrical units: ``ohm``, ``V``, ``coulomb``
-
-Units can be specified on individual input values by placing them after the
-value, separated by a space::
-
- {A: 1.45e9 cm^3/kmol, b: 0.4, Ea: 21033 kJ/kmol}
-
-or by using a ``units`` mapping::
-
- units: {mass: g, quantity: mol, pressure: atm, activation-energy: cal/mol}
-
-A ``units`` mapping will set the default units for all values within the same
-YAML list or mapping, including any nested lists and mappings. Units not
-specified by a mapping use the values from higher level mappings, or the Cantera
-defaults if no ``units`` mapping specifies applicable units. If a ``units``
-mapping appears in a list, it must be the first item in that list.
-
-Default units may be set for ``mass``, ``length``, ``time``, ``temperature``,
-``current``, ``quantity``, ``pressure``, ``energy``, and ``activation-energy``.
-The units ``pressure`` and ``energy`` are used when these units appear
-explicitly in the units that a value is being converted to within Cantera. For
-example, a conversion to ``N/m^2`` will use the default units for mass, length,
-and time, while a conversion to ``Pa`` will use the default units for pressure.
-
-Activation energies given in temperature units will be implicitly converted to energy per
-quantity by dividing by the gas constant. Activation energies given in pure energy units
-such as eV will be converted to energy per quantity by multiplying by the Avogadro
-constant. Setting default units for ``energy`` and ``quantity`` will determine the
-default units of ``activation-energy``, which can be overridden by explicitly giving
-the desired units of ``activation-energy``.
diff --git a/doc/sphinx/yaml/index.rst b/doc/sphinx/yaml/index.rst
index bf46fdabaf..2d4d2b048d 100644
--- a/doc/sphinx/yaml/index.rst
+++ b/doc/sphinx/yaml/index.rst
@@ -1,16 +1,12 @@
-*************************
-YAML Input File Reference
-*************************
+**************************
+YAML Input File Converters
+**************************
.. toctree::
:maxdepth: 2
- general
- phases
- elements
- species
- reactions
cti_conversion
ctml_conversion
ck_conversion
+ yaml_format
diff --git a/doc/sphinx/yaml/phases.rst b/doc/sphinx/yaml/phases.rst
deleted file mode 100644
index ee28cc840d..0000000000
--- a/doc/sphinx/yaml/phases.rst
+++ /dev/null
@@ -1,962 +0,0 @@
-.. highlight:: yaml
-
-.. _sec-yaml-phases:
-
-*****************
-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:
-
-``name``
- String identifier used for the phase. Required.
-
-``elements``
- Specification 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 ``elements``
- section 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 section ``default``.
-
-``species``
- Specification for the species present in the phase. This can be:
-
- - a list of species that appear in the ``species`` section of the file.
- - The string ``all``, to indicate that all species in the ``species``
- section should be included. This is the default if no ``species`` entry
- is present.
- - A list of single-key mappings of section names to either the string
- ``all`` or a list of species names. 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.
-
- Species may be skipped depending on the setting of the
- ``skip-undeclared-elements`` option.
-
-``skip-undeclared-elements``
- If set to ``true``, do not add species that contain elements that are not
- explicitly included in the phase. The default is ``false``, where the
- presence of such species is considered an error.
-
-``skip-undeclared-third-bodies``
- If set to ``true``, ignore third body efficiencies for species that are not
- defined in the phase. The default is ``false``, where the presence of
- such third body specifications is considered an error.
-
-``state``
- A mapping specifying the thermodynamic state. See
- :ref:`sec-yaml-setting-state`.
-
-``adjacent-phases``
- For 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 ``phases`` section 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.
-
-``thermo``
- String specifying the phase thermodynamic model to be used. Supported model
- strings are:
-
- - :ref:`binary-solution-tabulated `
- - :ref:`compound-lattice `
- - :ref:`Debye-Huckel `
- - :ref:`edge `
- - :ref:`electron-cloud `
- - :ref:`fixed-stoichiometry `
- - :ref:`HMW-electrolyte `
- - :ref:`ideal-gas `
- - :ref:`ideal-molal-solution `
- - :ref:`ideal-condensed `
- - :ref:`ideal-solution-VPSS `
- - :ref:`ideal-surface `
- - :ref:`coverage-dependent-surface `
- - :ref:`ions-from-neutral-molecule `
- - :ref:`lattice `
- - :ref:`liquid-water-IAPWS95 `
- - :ref:`Margules `
- - :ref:`Maskell-solid-solution `
- - :ref:`Peng-Robinson `
- - :ref:`plasma `
- - :ref:`pure-fluid `
- - :ref:`Redlich-Kister `
- - :ref:`Redlich-Kwong `
-
-``kinetics``
- String specifying the kinetics model to be used. Supported model strings
- are:
-
- - none
- - `gas `__
- - `surface `__
- - `edge `__
-
-``reactions``
- Source 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 the
- ``reactions`` section of the file should be included. This is the default
- if no ``reactions`` entry is present.
- - The string ``declared-species``, which indicates that all reactions from
- the ``reactions`` section 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 ``all`` or
- ``declared-species`` and is applied as described above.
-
-``Motz-Wise``
- Boolean 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.
-
-``transport``
- String specifying the transport model to be used. Supported model strings
- are:
-
- - none
- - `high-pressure `__
- - `ionized-gas `__
- - `mixture-averaged `__
- - `mixture-averaged-CK `__
- - `multicomponent `__
- - `multicomponent-CK `__
- - `unity-Lewis-number `__
- - `water `__
-
-
-
-.. _sec-yaml-setting-state:
-
-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-fractions`` or ``Y``
-- ``mole-fractions`` or ``X``
-- ``coverages``
-- ``molalities`` or ``M``
-
-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:
-
-- ``T`` and ``P``
-- ``T`` and ``D``
-- ``T`` and ``V``
-- ``H`` and ``P``
-- ``U`` and ``V``
-- ``S`` and ``V``
-- ``S`` and ``P``
-- ``S`` and ``T``
-- ``P`` and ``V``
-- ``U`` and ``P``
-- ``V`` and ``H``
-- ``T`` and ``H``
-- ``S`` and ``H``
-- ``D`` and ``P``
-
-The following synonyms are also implemented for use in any of the pairs:
-
-- ``temperature``, ``T``
-- ``pressure``, ``P``
-- ``enthalpy``, ``H``
-- ``entropy``, ``S``
-- ``int-energy``, ``internal-energy``, ``U``
-- ``specific-volume``, ``V``
-- ``density``, ``D``
-
-
-.. _sec-yaml-phase-thermo-models:
-
-Phase thermodynamic models
-==========================
-
-.. _sec-yaml-binary-solution-tabulated:
-
-``binary-solution-tabulated``
------------------------------
-
-A phase implementing tabulated standard state thermodynamics for one species in
-a binary solution, as `described here `__.
-
-Includes the fields of :ref:`sec-yaml-ideal-condensed`, plus:
-
-``tabulated-species``
- The name of the species to which the tabulated enthalpy and entropy is
- added.
-
-``tabulated-thermo``
- A mapping containing three (optionally four) lists of equal lengths:
-
- ``mole-fractions``
- A list of mole fraction values for the tabulated species.
-
- ``enthalpy``
- The extra molar enthalpy to be added to the tabulated species at these
- mole fractions.
-
- ``entropy``
- The extra molar entropy to be added to the tabulated species at these
- mole fractions.
-
- ``molar-volume``
- The molar volume of the phase at these mole fractions. This input is
- optional.
-
-
-.. _sec-yaml-compound-lattice:
-
-``compound-lattice``
---------------------
-
-A phase that is comprised of a fixed additive combination of other lattice
-phases, as `described here `__.
-
-Additional fields:
-
-``composition``
- A mapping of component phase names to their relative stoichiometries.
-
-Example::
-
- thermo: compound-lattice
- composition: {Li7Si3(s): 1.0, Li7Si3-interstitial: 1.0}
-
-
-.. _sec-yaml-Debye-Huckel:
-
-``Debye-Huckel``
-----------------
-
-The Debye-Hückel model as
-`described here `__.
-
-Additional parameters for this model are contained in the ``activity-data``
-field:
-
-``activity-data``
- The activity data field contains the following fields:
-
- ``model``
- One of ``dilute-limit``, ``B-dot-with-variable-a``,
- ``B-dot-with-common-a``, ``beta_ij``, or ``Pitzer-with-beta_ij``
-
- ``A_Debye``
- The value of the Debye "A" parameter, or the string ``variable`` to 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_Debye``
- The Debye "B" parameter. Defaults to 3.2864e+09 kg^0.5/gmol^0.5/m, a nominal
- value for water.
-
- ``max-ionic-strength``
- The maximum ionic strength
-
- ``use-Helgeson-fixed-form``
- Boolean, ``true`` or ``false``
-
- ``default-ionic-radius``
- Ionic radius to use for species where the ionic radius has not been
- specified.
-
- ``B-dot``
- The value of B-dot.
-
- ``beta``
- List of mappings providing values of :math:`\beta_{ij}` for different
- species pairs. Each mapping contains a ``species`` key that contains a
- list of two species names, and a ``beta`` key that contains the
- corresponding value of :math:`\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-radius``
- Size of the species.
-
-``electrolyte-species-type``
- One of ``solvent``, ``charged-species``, ``weak-acid-associated``,
- ``strong-acid-associated``, ``polar-neutral``, or ``nonpolar-neutral``.
- The type ``solvent`` is the default for the first species in the phase. The
- type ``charged-species`` is the default for species with a net charge.
- Otherwise, the default is and ``nonpolar-neutral``.
-
-``weak-acid-charge``
- Charge 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
-
-
-.. _sec-yaml-edge:
-
-``edge``
---------
-
-A one-dimensional edge between two surfaces, as
-`described here `__.
-
-Additional fields:
-
-``site-density``
- The molar density of sites per unit length along the edge
-
-Example::
-
- thermo: edge
- site-density: 5.0e-17 mol/cm
-
-
-.. _sec-yaml-fixed-stoichiometry:
-
-``fixed-stoichiometry``
------------------------
-
-A phase with fixed composition, as
-`described here `__.
-
-
-.. _sec-yaml-HMW-electrolyte:
-
-``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-data``
- The activity data field contains the following fields:
-
- ``temperature-model``
- The form of the Pitzer temperature model. One of ``constant``,
- ``linear`` or ``complex``. The default is ``constant``.
-
- ``A_Debye``
- The value of the Debye "A" parameter, or the string ``variable`` to 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-strength``
- The maximum ionic strength
-
- ``interactions``
- A list of mappings, where each mapping describes a binary or ternary
- interaction among species. Fields of this mapping include:
-
- ``species``
- A list of one to three species names
-
- ``beta0``
- The :math:`\beta^{(0)}` parameters for an cation/anion interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``beta1``
- The :math:`\beta^{(1)}` parameters for an cation/anion interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``beta2``
- The :math:`\beta^{(2)}` parameters for an cation/anion interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``Cphi``
- The :math:`C^\phi` parameters for an cation/anion interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``alpha1``
- The :math:`\alpha^{(1)}` parameter for an cation/anion interaction.
-
- ``alpha2``
- The :math:`\alpha^{(2)}` parameter for an cation/anion interaction.
-
- ``theta``
- The :math:`\theta` parameters for a like-charged binary interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``lambda``
- The :math:`\lambda` parameters for binary interactions involving at
- least one neutral species. 1, 2, or 5 values depending on the value
- of ``temperature-model``.
-
- ``psi``
- The :math:`\Psi` parameters for ternary interactions involving three
- charged species. 1, 2, or 5 values depending on the value of
- ``temperature-model``.
-
- ``zeta``
- The :math:`\zeta` parameters for ternary interactions involving one
- neutral species. 1, 2, or 5 values depending on the value of
- ``temperature-model``.
-
- ``mu``
- The :math:`\mu` parameters for a neutral species self-interaction.
- 1, 2, or 5 values depending on the value of ``temperature-model``.
-
- ``cropping-coefficients``
-
- ``ln_gamma_k_min``
- Default -5.0.
-
- ``ln_gamma_k_max``
- Default 15.0.
-
- ``ln_gamma_o_min``
- Default -6.0.
-
- ``ln_gamma_o_max``
- Default 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]}
-
-
-.. _sec-yaml-ideal-gas:
-
-``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}
-
-
-.. _sec-yaml-ideal-molal-solution:
-
-``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-basis``
- A string specifying the basis for the standard concentration. One of
- ``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
-
-``cutoff``
- Parameters for cutoff treatments of activity coefficients
-
- ``model``
- ``poly`` or ``polyExp``
-
- ``gamma_o``
- gamma_o value for the cutoff process at the zero solvent point
-
- ``gamma_k``
- gamma_k minimum for the cutoff process at the zero solvent point
-
- ``X_o``
- value of the solute mole fraction that centers the cutoff polynomials
- for the cutoff = 1 process
-
- ``c_0``
- Parameter in the polyExp cutoff treatment having to do with rate of
- exponential decay
-
- ``slope_f``
- Parameter in the ``polyExp`` cutoff treatment
-
- ``slope_g``
- Parameter in the ``polyExp`` cutoff 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
-
-
-.. _sec-yaml-ideal-condensed:
-
-``ideal-condensed``
--------------------
-
-A condensed phase ideal solution as
-`described here `__.
-
-Additional fields:
-
-``standard-concentration-basis``
- A string specifying the basis for the standard concentration. One of
- ``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
-
-
-.. _sec-yaml-ideal-solution-VPSS:
-
-``ideal-solution-VPSS``
------------------------
-
-An ideal solution model using variable pressure standard state methods as
-`described here `__.
-
-Additional fields:
-
-``standard-concentration-basis``
- A string specifying the basis for the standard concentration. One of
- ``unity``, ``species-molar-volume``, or ``solvent-molar-volume``.
-
-
-.. _sec-yaml-ideal-surface:
-
-``ideal-surface``
------------------
-
-An ideal surface phase, as
-`described here `__.
-
-Additional fields:
-
-``site-density``
- The 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
-
-
-.. _sec-yaml-coverage-dependent-surface:
-
-``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 `__.
-Majority of coverage dependency parameters are provided in the species entry as
-`described here `__.
-
-Additional fields:
-
-``site-density``
- The molar density of surface sites.
-
-``reference-state-coverage``
- The 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
-
-
-.. _sec-yaml-ions-from-neutral-molecule:
-
-``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:: 3.0
-
- This phase model is deprecated and will be removed after Cantera 3.0.
-
-Additional fields:
-
-``neutral-phase``
- The ``name`` of 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
-
-
-.. _sec-yaml-lattice:
-
-``lattice``
------------
-
-A simple thermodynamic model for a bulk phase, assuming a lattice of solid
-atoms, as
-`described here `__.
-
-Additional fields:
-
-``site-density``
- The molar density of lattice sites
-
-
-.. _sec-yaml-liquid-water-IAPWS95:
-
-``liquid-water-IAPWS95``
-------------------------
-
-An equation of state for liquid water, as
-`described here `__.
-
-
-.. _sec-yaml-Margules:
-
-``Margules``
-------------
-
-A phase employing the Margules approximation for the excess Gibbs free energy, as
-`described here `__.
-
-Additional fields:
-
-``interactions``
- A list of mappings, where each mapping has the following fields:
-
- ``species``
- A list of two species names
-
- ``excess-enthalpy``
- A list of two values specifying the first and second excess enthalpy
- coefficients for the interaction of the specified species. Defaults to
- [0, 0].
-
- ``excess-entropy``
- A 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-enthalpy``
- A 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-entropy``
- A 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]
-
-
-.. _sec-yaml-Maskell-solid-solution:
-
-``Maskell-solid-solution``
---------------------------
-
-A condensed phase non-ideal solution with two species, as
-`described here `__.
-
-.. deprecated:: 3.0
-
- This phase model is deprecated and will be removed after Cantera 3.0.
-
-Additional fields:
-
-``excess-enthalpy``
- The molar excess enthalpy
-
-``product-species``
- String specifying the "product" species
-
-Example::
-
- thermo: Maskell-solid-solution
- excess-enthalpy: 5 J/mol
- product-species: H(s)
-
-
-.. _sec-yaml-electron-cloud:
-
-``electron-cloud``
-------------------
-
-A phase representing an electron cloud, such as conduction electrons in a metal,
-as `described here `__.
-
-Additional fields:
-
-``density``
- The density of the bulk metal
-
-
-.. _sec-yaml-pure-fluid:
-
-``pure-fluid``
---------------
-
-A phase representing a pure fluid equation of state for one of several species,
-as `described here `__.
-
-Additional fields:
-
-``pure-fluid-name``
- Name of the pure fluid model to use:
- - ``carbon-dioxide``
- - ``heptane``
- - ``HFC-134a``
- - ``hydrogen``
- - ``methane``
- - ``nitrogen``
- - ``oxygen``
- - ``water``
-
-
-.. _sec-yaml-Redlich-Kister:
-
-``Redlich-Kister``
-------------------
-
-A phase employing the Redlich-Kister approximation for the excess Gibbs free
-energy, as
-`described here `__.
-
-Additional fields:
-
-``interactions``
- A list of mappings, where each mapping has the following fields:
-
- ``species``
- A list of two species names
-
- ``excess-enthalpy``
- A list of polynomial coefficients for the excess enthalpy of the
- specified binary interaction
-
- ``excess-entropy``
- A 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]
-
-
-.. _sec-yaml-Redlich-Kwong:
-
-``Redlich-Kwong``
------------------
-
-A multi-species Redlich-Kwong phase as
-`described here `__.
-
-The parameters for each species are contained in the corresponding species
-entries. See :ref:`Redlich-Kwong species equation of state `.
-
-.. _sec-yaml-Peng-Robinson:
-
-``Peng-Robinson``
------------------
-
-A multi-species Peng-Robinson phase as
-`described here `__.
-
-The parameters for each species are contained in the corresponding species
-entries. See :ref:`Peng-Robinson species equation of state `.
-
-.. _sec-yaml-plasma:
-
-``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-distribution``
- A mapping with the following fields:
-
- ``type``
- String specifying the type of the electron energy distribution to be used.
- Supported model strings are:
-
- - `isotropic`
- - `discretized`
-
- ``shape-factor``
- A 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-energy``
- Mean 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-levels``
- A list of values specifying the electron energy levels. The default
- uses 1001 equal spaced points from 0 to 1 eV.
-
- ``distribution``
- A list of values specifying the discretized electron energy distribution.
- This field is only used with `discretized`.
-
- ``normalize``
- A flag specifying whether normalizing the discretized electron energy
- distribution or not. This field is only used with `discretized`.
- Defaults to ``true``.
-
-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
diff --git a/doc/sphinx/yaml/reactions.rst b/doc/sphinx/yaml/reactions.rst
deleted file mode 100644
index e7aee0d3d2..0000000000
--- a/doc/sphinx/yaml/reactions.rst
+++ /dev/null
@@ -1,507 +0,0 @@
-.. highlight:: yaml
-
-.. _sec-yaml-reactions:
-
-*********
-Reactions
-*********
-
-The fields common to all ``reaction`` entries are:
-
-``equation``
- The stoichiometric equation for the reaction. Each term (that is,
- stoichiometric coefficient, species name, ``+`` or ``<=>``) in the equation
- must be separated by a space.
-
- Reversible reactions may be written using ``<=>`` or ``=`` to separate
- reactants and products. Irreversible reactions are written using ``=>``.
-
-``type``
- A string specifying the type of reaction or rate coefficient
- parameterization. The default is ``elementary``. Reaction types are:
-
- - :ref:`elementary `
- - :ref:`three-body `
- - :ref:`Blowers-Masel `
- - :ref:`two-temperature-plasma `
- - :ref:`falloff `
- - :ref:`chemically-activated `
- - :ref:`pressure-dependent-Arrhenius `
- - :ref:`Chebyshev `
-
- Reactions without a specified ``type`` on surfaces or edges are
- automatically treated as :ref:`interface-Arrhenius `
- reactions, unless a ``sticking-coefficient`` implies a
- :ref:`sticking-Arrhenius ` reaction. Interface
- reactions that involve charge transfer between phases are automatically treated as
- :ref:`electrochemical ` reactions.
-
- Reactions on surfaces or edges specifying ``type`` as ``Blowers-Masel`` are treated
- as :ref:`interface-Blowers-Masel ` or
- :ref:`sticking-Blowers-Masel `.
-
-``duplicate``
- Boolean indicating whether the reaction is a known duplicate of another
- reaction. The default is ``false``.
-
-``orders``
- An optional mapping of species to explicit reaction orders to use. Reaction
- orders for reactant species not explicitly mentioned are taken to be their
- respective stoichiometric coefficients. See
- `Reaction orders `__
- for additional information.
-
-``negative-orders``
- Boolean indicating whether negative reaction orders are allowed. The
- default is ``false``.
-
-``nonreactant-orders``
- Boolean indicating whether orders for non-reactant species are allowed.
- The default is ``false``.
-
-Depending on the reaction ``type``, other fields may be necessary to specify
-the rate of the reaction.
-
-
-Reaction rate expressions
-=========================
-
-.. _sec-yaml-Arrhenius-rate:
-
-Arrhenius
----------
-
-Arrhenius rate expressions are specified as a mapping with fields:
-
-``A``
- The pre-exponential factor :math:`A`
-``b``
- The temperature exponent :math:`b`
-``Ea``
- The activation energy :math:`E_a`
-
-or a corresponding three-element list. The following are equivalent::
-
- {A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
- [-2.70000E+13 cm^3/mol/s, 0, 355 cal/mol]
-
-
-.. _sec-yaml-Blowers-Masel-rate:
-
-Blowers-Masel
--------------
-
-Blowers-Masel rate expressions calculate the rate constant based on the Blowers Masel
-approximation as
-`described here `__.
-The rate parameters are specified as a mapping with fields:
-
-``A``
- The pre-exponential factor :math:`A`
-``b``
- The temperature exponent :math:`b`
-``Ea0``
- The intrinsic activation energy :math:`E_{a0}`
-``w``
- The average of the bond dissociation energy of the bond breaking and that being
- formed in the reaction :math:`w`
-
-or a corresponding four-element list. The following are equivalent::
-
- {A: 3.87e+04 cm^3/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
- [3.87e+04 cm^3/mol/s, 2.7, 6260.0 cal/mol, 1e9 cal/mol]
-
-
-.. _sec-yaml-two-temperature-plasma-rate:
-
-Two-Temperature Plasma
-----------------------
-
-Two-temperature plasma reactions involve an electron as one of the reactants, where the
-electron temperature may differ from the gas temperature as
-`described here `__.
-The rate parameters are specified as a mapping with fields:
-
-``A``
- The pre-exponential factor
-``b``
- The temperature exponent, which is applied to the electron temperature
-``Ea-gas``
- The activation energy term :math:`E_{a,g}` that is related to the gas temperature
-``Ea-electron``
- The activation energy term :math:`E_{a,e}` that is related to the electron
- temperature
-
-or a corresponding four-element list. The following are equivalent::
-
- {A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
- [17283, -3.1, -5820 J/mol, 1081 J/mol]
-
-
-.. _sec-yaml-efficiencies:
-
-Efficiencies
-============
-
-Some reaction types include parameters for the "efficiency" of different species
-as third-body colliders. For these reactions, the following additional fields
-are supported:
-
-``efficiencies``
- A mapping of species names to efficiency values
-
-``default-efficiency``
- The efficiency for use for species not included in the ``efficiencies``
- mapping. Defaults to 1.0.
-
-
-Reaction types
-==============
-
-.. _sec-yaml-elementary:
-
-``elementary``
---------------
-
-A homogeneous reaction with a pressure-independent rate coefficient and mass
-action kinetics, as
-`described here `__.
-
-Additional fields are:
-
-``rate-constant``
- An :ref:`Arrhenius-type ` list or mapping.
-
-``negative-A``
- A boolean indicating whether a negative value for the pre-exponential factor
- is allowed. The default is ``false``.
-
-Example::
-
- equation: N + NO <=> N2 + O
- rate-constant: {A: -2.70000E+13 cm^3/mol/s, b: 0, Ea: 355 cal/mol}
- negative-A: true
-
-
-.. _sec-yaml-three-body:
-
-``three-body``
---------------
-
-A three body reaction as
-`described here `__.
-
-The reaction equation should include the third body collision partner ``M``.
-
-Includes the fields of an ``elementary`` reaction, plus the fields for
-specifying :ref:`efficiencies `.
-
-Example::
-
- equation: 2 O + M = O2 + M
- type: three-body
- rate-constant: [1.20000E+17 cm^6/mol^2/s, -1, 0]
- efficiencies: {AR: 0.83, H2O: 5}
-
-
-.. _sec-yaml-Blowers-Masel:
-
-``Blowers-Masel``
------------------
-
-Includes the fields of an :ref:`elemntary ` reaction, except that
-the ``rate-constant`` field is a
-:ref:`Blowers-Masel-type ` list or mapping.
-
-Example::
-
- equation: O + H2 <=> H + OH
- type: Blowers-Masel
- rate-constant: {A: 3.87e+04 cm^2/mol/s, b: 2.7, Ea0: 6260.0 cal/mol, w: 1e9 cal/mol}
-
-
-.. _sec-yaml-two-temperature-plasma:
-
-``two-temperature-plasma``
---------------------------
-
-Includes the fields of an :ref:`elementary ` reaction, except that
-the ``rate-constant`` field is a
-:ref:`Two-temperature-plasma-type ` list or
-mapping.
-
-Example::
-
- equation: O + H => O + H
- type: two-temperature-plasma
- rate-constant: {A: 17283, b: -3.1, Ea-gas: -5820 J/mol, Ea-electron: 1081 J/mol}
-
-
-.. _sec-yaml-falloff:
-
-``falloff``
------------
-
-A falloff reaction as
-`described here `__.
-
-The reaction equation should include the pressure-dependent third body collision
-partner ``(+M)`` or ``(+name)`` where ``name`` is the name of a species. The
-latter case is equivalent to setting the efficiency for ``name`` to 1 and the
-efficiency for all other species to 0.
-
-Includes field for specifying :ref:`efficiencies ` as well
-as:
-
-``high-P-rate-constant``
- An :ref:`sec-yaml-Arrhenius-rate` expression for the high-pressure limit
-
-``low-P-rate-constant``
- An :ref:`sec-yaml-Arrhenius-rate` expression for the low-pressure limit
-
-``Troe``
- Parameters for the
- `Troe `__
- falloff function. A mapping containing the keys ``A``, ``T3``, ``T1`` and
- optionally ``T2``. The default value for ``T2`` is 0.
-
-``SRI``
- Parameters for the
- `SRI `__
- falloff function. A mapping containing the keys ``A``, ``B``, ``C``, and
- optionally ``D`` and ``E``. The default values for ``D`` and ``E`` are 1.0
- and 0.0, respectively.
-
-``Tsang``
- Parameters for the
- `Tsang `__
- falloff function. A mapping containing the keys ``A`` and ``B``. The default value
- for ``B`` is 0.0.
-
-Example::
-
- equation: H + CH2 (+ N2) <=> CH3 (+N2)
- type: falloff
- high-P-rate-constant: [6.00000E+14 cm^3/mol/s, 0, 0]
- low-P-rate-constant: {A: 1.04000E+26 cm^6/mol^2/s, b: -2.76, Ea: 1600}
- Troe: {A: 0.562, T3: 91, T1: 5836}
-
-
-.. _sec-yaml-chemically-activated:
-
-``chemically-activated``
-------------------------
-
-A chemically activated reaction as
-`described here `__.
-
-The parameters are the same as for :ref:`sec-yaml-falloff` reactions.
-
-Example::
-
- equation: CH3 + OH (+M) <=> CH2O + H2 (+M)
- type: chemically-activated
- high-P-rate-constant: [5.88E-14, 6.721, -3022.227]
- low-P-rate-constant: [282320.078, 1.46878, -3270.56495]
-
-
-.. _sec-yaml-pressure-dependent-Arrhenius:
-
-``pressure-dependent-Arrhenius``
---------------------------------
-
-A pressure-dependent reaction using multiple Arrhenius expressions as
-`described here `__.
-
-The only additional field in this reaction type is:
-
-``rate-constants``
- A list of mappings, where each mapping is the mapping form of an
- :ref:`sec-yaml-Arrhenius-rate` expression with the addition of a pressure ``P``.
-
-Example::
-
- equation: H + CH4 <=> H2 + CH3
- type: pressure-dependent-Arrhenius
- rate-constants:
- - {P: 0.039474 atm, A: 2.720000e+09 cm^3/mol/s, b: 1.2, Ea: 6834.0}
- - {P: 1.0 atm, A: 1.260000e+20, b: -1.83, Ea: 15003.0}
- - {P: 1.0 atm, A: 1.230000e+04, b: 2.68, Ea: 6335.0}
- - {P: 1.01325 MPa, A: 1.680000e+16, b: -0.6, Ea: 14754.0}
-
-
-.. _sec-yaml-Chebyshev:
-
-``Chebyshev``
--------------
-
-A reaction parameterized as a bivariate Chebyshev polynomial as
-`described here `__.
-
-Additional fields are:
-
-``temperature-range``
- A list of two values specifying the minimum and maximum temperatures at
- which the rate constant is valid
-
-``pressure-range``
- A list of two values specifying the minimum and maximum pressures at
- which the rate constant is valid
-
-``data``
- A list of lists containing the Chebyshev coefficients
-
-Example::
-
- equation: CH4 <=> CH3 + H
- type: Chebyshev
- temperature-range: [290, 3000]
- pressure-range: [0.0098692326671601278 atm, 98.692326671601279 atm]
- data: [[-1.44280e+01, 2.59970e-01, -2.24320e-02, -2.78700e-03],
- [ 2.20630e+01, 4.88090e-01, -3.96430e-02, -5.48110e-03],
- [-2.32940e-01, 4.01900e-01, -2.60730e-02, -5.04860e-03],
- [-2.93660e-01, 2.85680e-01, -9.33730e-03, -4.01020e-03],
- [-2.26210e-01, 1.69190e-01, 4.85810e-03, -2.38030e-03],
- [-1.43220e-01, 7.71110e-02, 1.27080e-02, -6.41540e-04]]
-
-
-.. _sec-yaml-interface-Arrhenius:
-
-``interface-Arrhenius``
------------------------
-
-A reaction occurring on a surface between two bulk phases, or along an edge
-at the intersection of two surfaces, as
-`described here `__.
-
-Includes the fields of an :ref:`sec-yaml-elementary` reaction plus:
-
-``coverage-dependencies``
- A mapping of species names to coverage dependence parameters, where these
- parameters are contained in either a mapping with the fields:
-
- ``a``
- Coefficient for exponential dependence on the coverage
-
- ``m``
- Power-law exponent of coverage dependence
-
- ``E``
- Activation energy dependence on coverage, which uses the same sign convention
- as the leading-order activation energy term. This can be a scalar value for
- the linear dependency or a list of four values for the polynomial dependency
- given in the order of 1st, 2nd, 3rd, and 4th-order coefficients
-
- or a list containing the three elements above, in the given order.
-
- Note that parameters ``a``, ``m`` and ``E`` correspond to parameters
- :math:`\eta_{ki}`, :math:`\mu_{ki}` and :math:`\epsilon_{ki}` in Eq 11.113 of
- [Kee, R. J., Coltrin, M. E., & Glarborg, P.(2003). Chemically reacting flow:
- theory and practice. John Wiley & Sons], respectively.
-
-Examples::
-
- - equation: 2 H(s) => H2 + 2 Pt(s)
- rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea: 67400 J/mol}
- coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
-
- - equation: 2 O(S) => O2 + 2 Pt(S)
- rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
- coverage-dependencies: {O(S): {a: 0.0, m: 0.0,
- E: [1.0e3 J/mol, 3.0e3 J/mol , -7.0e4 J/mol , 5.0e3 J/mol]}
-
- - equation: CH4 + PT(S) + O(S) => CH3(S) + OH(S)
- rate-constant: {A: 5.0e+18, b: 0.7, Ea: 4.2e+04}
- coverage-dependencies:
- O(S): [0, 0, 8000]
- PT(S): [0, -1.0, 0]
-
- - equation: 2 O(S) => O2 + 2 Pt(S)
- rate-constant: {A: 3.7e+21, b: 0, Ea: 213200 J/mol}
- coverage-dependencies:
- O(S): [0, 0, [1.0e6, 3.0e6, -7.0e7, 5.0e6]]
-
-.. _sec-yaml-interface-Blowers-Masel:
-
-``interface-Blowers-Masel``
----------------------------
-
-Includes the same fields as :ref:`interface-Arrhenius `,
-while using the :ref:`Blowers-Masel ` parameterization
-for the rate constant.
-
-Example::
-
- equation: 2 H(s) => H2 + 2 Pt(s)
- type: Blowers-Masel
- rate-constant: {A: 3.7e21 cm^2/mol/s, b: 0, Ea0: 67400 J/mol, w: 1000000 J/mol}
- coverage-dependencies: {H(s): {a: 0, m: 0, E: -6000 J/mol}}
-
-
-.. _sec-yaml-sticking-Arrhenius:
-
-``sticking-Arrhenius``
-----------------------
-
-A sticking reaction occurring on a surface adjacent to a bulk phase, as
-`described here `__.
-
-Includes the fields of an :ref:`sec-yaml-interface-Arrhenius` reaction plus:
-
-``sticking-coefficient``
- An :ref:`Arrhenius-type ` expression for the sticking
- coefficient
-
-``Motz-Wise``
- A boolean indicating whether to use the Motz-Wise correction factor for sticking
- coefficients near unity. Defaults to ``false``.
-
-``sticking-species``
- The name of the sticking species. Required if the reaction includes multiple
- non-surface species.
-
-Example::
-
- equation: OH + PT(S) => OH(S)
- sticking-coefficient: {A: 1.0, b: 0, Ea: 0}
-
-
-.. _sec-yaml-sticking-Blowers-Masel:
-
-``sticking-Blowers-Masel``
---------------------------
-
-Includes the same fields as :ref:`sticking-Arrhenius `,
-while using the :ref:`Blowers-Masel ` parameterization
-for the sticking coefficient.
-
-Example::
-
- equation: OH + PT(S) => OH(S)
- type: Blowers-Masel
- sticking-coefficient: {A: 1.0, b: 0, Ea0: 0, w: 100000}
- Motz-Wise: true
-
-
-.. _sec-yaml-electrochemical-reaction:
-
-``electrochemical``
--------------------
-
-Interface reactions involving charge transfer between phases,
-as `described here `__.
-
-Includes the fields of an :ref:`sec-yaml-interface-Arrhenius` reaction, plus:
-
-``beta``
- The symmetry factor for the reaction. Default is 0.5.
-
-``exchange-current-density-formulation``
- Set to ``true`` if the rate constant parameterizes the exchange current
- density. Default is ``false``.
-
-Example::
-
- equation: LiC6 <=> Li+(e) + C6
- rate-constant: [5.74, 0.0, 0.0]
- beta: 0.4
diff --git a/doc/sphinx/yaml/species.rst b/doc/sphinx/yaml/species.rst
deleted file mode 100644
index 5d638b83b0..0000000000
--- a/doc/sphinx/yaml/species.rst
+++ /dev/null
@@ -1,638 +0,0 @@
-.. highlight:: yaml
-
-.. _sec-yaml-species:
-
-*******
-Species
-*******
-
-The fields of a ``species`` entry are:
-
-``name``
- String identifier used for the species. Required.
-
-``composition``
- Mapping that specifies the elemental composition of the species,
- for example, ``{C: 1, H: 4}``. Required.
-
-``thermo``
- Mapping containing the reference state thermodynamic model specification
- and parameters. See :ref:`sec-yaml-species-thermo`.
-
-``equation-of-state``
- A mapping or list of mappings. Each mapping contains an equation of state
- model specification for the species, any parameters for that model, and any
- parameters for interactions with other species. See
- :ref:`sec-yaml-species-eos`. If this field is absent and a model is
- required, the ``ideal-gas`` model is assumed.
-
-``critical-parameters``
- Mapping containing parameters related to the critical state of a species. Used in
- models that incorporate "real gas" effects, such as
- :ref:`sec-yaml-eos-redlich-kwong`.
- See :ref:`sec-yaml-species-crit-props`.
-
-``transport``
- Mapping containing the species transport model specification and
- parameters. See :ref:`sec-yaml-species-transport`.
-
-``sites``
- The number of sites occupied by a surface or edge species. Default is 1.
-
-``Debye-Huckel``
- Additional model parameters used in the Debye-Hückel model. See
- :ref:`sec-yaml-Debye-Huckel` for more information.
-
-
-.. _sec-yaml-species-thermo:
-
-Species thermo models
-=====================
-
-Fields of a species ``thermo`` entry used by all models are:
-
-``model``
- String specifying the model to be used. Required. Supported model strings
- are:
-
- - :ref:`NASA7 `
- - :ref:`NASA9 `
- - :ref:`Shomate `
- - :ref:`constant-cp `
- - :ref:`piecewise-Gibbs `
-
-``reference-pressure``
- The reference pressure at which the given thermodynamic properties apply.
- Defaults to 1 atm.
-
-
-.. _sec-yaml-nasa7:
-
-NASA 7-coefficient polynomials
-------------------------------
-
-The polynomial form `described here `__,
-given for one or two temperature regions. Additional fields of a ``NASA7``
-thermo entry are:
-
-``temperature-ranges``
- A list giving the temperature intervals on which the polynomials are valid.
- For one temperature region, this list contains the minimum and maximum
- temperatures for the polynomial. For two temperature regions, this list
- contains the minimum, intermediate, and maximum temperatures.
-
-``data``
- A list with one item per temperature region, where that item is a 7 item
- list of polynomial coefficients. The temperature regions are arranged in
- ascending order. Note that this is different from the standard CHEMKIN
- formulation that uses two temperature regions listed in descending order.
-
-Example::
-
- thermo:
- model: NASA7
- temperature-ranges: [300.0, 1000.0, 5000.0]
- data:
- - [3.298677, 0.0014082404, -3.963222e-06, 5.641515e-09,
- -2.444854e-12, -1020.8999, 3.950372]
- - [2.92664, 0.0014879768, -5.68476e-07, 1.0097038e-10,
- -6.753351e-15, -922.7977, 5.980528]
-
-
-.. _sec-yaml-nasa9:
-
-NASA 9-coefficient polynomials
-------------------------------
-
-The polynomial form `described here `__,
-given for any number of temperature regions. Additional fields of a ``NASA9``
-thermo entry are:
-
-``temperature-ranges``
- A list giving the temperature intervals on which the polynomials are valid.
- This list contains the minimum temperature, the intermediate temperatures
- between each set pair of regions, and the maximum temperature.
-
-``data``
- A list with one item per temperature region, where that item is a 9 item
- list of polynomial coefficients. The temperature regions are arranged in
- ascending order.
-
-Example::
-
- thermo:
- model: NASA9
- temperature-ranges: [200.00, 1000.00, 6000.0, 20000]
- reference-pressure: 1 bar
- data:
- - [2.210371497E+04, -3.818461820E+02, 6.082738360E+00, -8.530914410E-03,
- 1.384646189E-05, -9.625793620E-09, 2.519705809E-12, 7.108460860E+02,
- -1.076003744E+01]
- - [5.877124060E+05, -2.239249073E+03, 6.066949220E+00, -6.139685500E-04,
- 1.491806679E-07, -1.923105485E-11, 1.061954386E-15, 1.283210415E+04,
- -1.586640027E+01]
- - [8.310139160E+08, -6.420733540E+05, 2.020264635E+02, -3.065092046E-02,
- 2.486903333E-06, -9.705954110E-11, 1.437538881E-15, 4.938707040E+06,
- -1.672099740E+03]
-
-.. _sec-yaml-shomate:
-
-Shomate polynomials
--------------------
-
-The polynomial form `described here `__,
-given for one or two temperature regions. Additional fields of a ``Shomate``
-thermo entry are:
-
-``temperature-ranges``
- A list giving the temperature intervals on which the polynomials are valid.
- For one temperature region, this list contains the minimum and maximum
- temperatures for the polynomial. For two temperature regions, this list
- contains the minimum, intermediate, and maximum temperatures.
-
-``data``
- A list with one item per temperature region, where that item is a 7 item
- list of polynomial coefficients. The temperature regions are arranged in
- ascending order.
-
-Example::
-
- thermo:
- model: Shomate
- temperature-ranges: [298, 1300, 6000]
- reference-pressure: 1 bar
- data:
- - [25.56759, 6.096130, 4.054656, -2.671301, 0.131021,
- -118.0089, 227.3665]
- - [35.15070, 1.300095, -0.205921, 0.013550, -3.282780,
- -127.8375, 231.7120]
-
-
-.. _sec-yaml-constcp:
-
-Constant heat capacity
-----------------------
-
-The constant heat capacity model `described here `__.
-Additional fields of a ``constant-cp`` thermo entry are:
-
-``T0``
- The reference temperature. Defaults to 298.15 K.
-
-``h0``
- The molar enthalpy at the reference temperature. Defaults to 0.0.
-
-``s0``
- The molar entropy at the reference temperature. Defaults to 0.0.
-
-``cp0``
- The heat capacity at constant pressure. Defaults to 0.0.
-
-``T-min``
- The minimum temperature at which this thermo data should be used.
- Defaults to 0.0.
-
-``T-max``
- The maximum temperature at which this thermo data should be used.
- Defaults to infinity.
-
-Example::
-
- thermo:
- model: constant-cp
- T0: 1000 K
- h0: 9.22 kcal/mol
- s0: -3.02 cal/mol/K
- cp0: 5.95 cal/mol/K
-
-.. _sec-yaml-piecewise-gibbs:
-
-Piecewise Gibbs
----------------
-
-A model based on piecewise interpolation of the Gibbs free energy as
-`described here `__
-Additional fields of a ``piecewise-Gibbs`` entry are:
-
-``h0``
- The molar enthalpy at the reference temperature of 298.15 K. Defaults to
- 0.0.
-
-``dimensionless``
- A boolean flag indicating whether the values of the Gibbs free energy are
- given in a dimensionless form, that is, divided by :math:`RT`. Defaults to
- ``false``.
-
-``data``
- A mapping of temperatures to values of the Gibbs free energy. The Gibbs free
- energy can be either in molar units (if ``dimensionless`` is ``false``) or
- nondimensionalized by the corresponding temperature (if ``dimensionless`` is
- ``true``). A value must be provided at :math:`T^\circ = 298.15` K.
-
-``T-min``
- The minimum temperature at which this thermo data should be used.
- Defaults to 0.0.
-
-``T-max``
- The maximum temperature at which this thermo data should be used.
- Defaults to infinity.
-
-Example::
-
- thermo:
- model: piecewise-Gibbs
- h0: -230.015 kJ/mol
- dimensionless: true
- data: {298.15: -91.50963, 333.15: -85.0}
-
-
-.. _sec-yaml-species-crit-props:
-
-Species critical state parameters
-=================================
-
-``critical-temperature``
- The critical temperature of the species [K]
-
-``critical-pressure``
- The critical pressure of the species [Pa]
-
-``acentric-factor``
- Pitzer's acentric factor :math:`omega` [-]
-
-
-.. _sec-yaml-species-eos:
-
-Species equation of state models
-================================
-
-``model``
- String specifying the model to be used. Required. Supported model strings
- are:
-
- - :ref:`constant-volume `
- - :ref:`density-temperature-polynomial `
- - :ref:`HKFT `
- - :ref:`ideal-gas `
- - :ref:`ions-from-neutral-molecule `
- - :ref:`liquid-water-IAPWS95 `
- - :ref:`molar-volume-temperature-polynomial `
- - :ref:`Peng-Robinson `
- - :ref:`Redlich-Kwong `
-
-
-.. _sec-yaml-eos-constant-volume:
-
-Constant volume
----------------
-
-A constant volume model as
-`described here `__.
-
-Any one of the following may be specified:
-
-``molar-volume``
- The molar volume of the species.
-
-``molar-density``
- The molar density of the species.
-
-``density``
- The mass density of the species.
-
-Example::
-
- equation-of-state:
- model: constant-volume
- molar-volume: 1.3 cm^3/mol
-
-
-.. _sec-yaml-eos-density-temperature-polynomial:
-
-Density temperature polynomial
-------------------------------
-
-A model in which the density varies with temperature as
-`described here `__.
-
-Additional fields:
-
-``data``
- Vector of 4 coefficients for a cubic polynomial in temperature
-
-Example::
-
- equation-of-state:
- model: density-temperature-polynomial
- units: {mass: g, length: cm}
- data: [0.536504, -1.04279e-4, 3.84825e-9, -5.2853e-12]
-
-
-.. _sec-yaml-eos-hkft:
-
-HKFT
-----
-
-The Helgeson-Kirkham-Flowers-Tanger model as
-`described here `__.
-
-Additional fields:
-
-``h0``
- Enthalpy of formation at the reference temperature and pressure
-
-``s0``
- Entropy of formation at the reference temperature and pressure
-
-``a``
- 4-element vector containing the coefficients :math:`a_1, \ldots , a_4`
-
-``c``
- 2-element vector containing the coefficients :math:`c_1` and :math:`c_2`
-
-``omega``
- The :math:`\omega` parameter at the reference temperature and pressure
-
-Example::
-
- equation-of-state:
- model: HKFT
- h0: -57433. cal/gmol
- s0: 13.96 cal/gmol/K
- a: [0.1839 cal/gmol/bar, -228.5 cal/gmol,
- 3.256 cal*K/gmol/bar, -27260. cal*K/gmol]
- c: [18.18 cal/gmol/K, -29810. cal*K/gmol]
- omega: 33060 cal/gmol
-
-
-.. _sec-yaml-eos-ideal-gas:
-
-Ideal gas
----------
-
-A species using the ideal gas equation of state, as
-`described here `__.
-
-.. deprecated:: 3.0
-
- This species thermo model is deprecated and will be removed after Cantera 3.0.
-
-.. _sec-yaml-eos-ions-from-neutral:
-
-Ions from neutral molecule
---------------------------
-
-A species equation of state model used with the ``ions-from-neutral-molecule``
-phase model, as
-`described here `__.
-
-.. deprecated:: 3.0
-
- This species thermo model is deprecated and will be removed after Cantera 3.0.
-
-Additional fields:
-
-``special-species``
- Boolean indicating whether the species is the "special species" in the
- phase. Default is ``false``.
-
-``multipliers``
- A dictionary mapping species to neutral species multiplier values.
-
-Example::
-
- equation-of-state:
- model: ions-from-neutral-molecule
- multipliers: {KCl(l): 1.2}
-
-
-.. _sec-yaml-eos-liquid-water-iapws95:
-
-Liquid Water IAPWS95
---------------------
-
-A detailed equation of state for liquid water as
-`described here `__.
-
-
-.. _sec-yaml-eos-molar-volume-temperature-polynomial:
-
-Molar volume temperature polynomial
------------------------------------
-
-A model in which the molar volume varies with temperature as
-`described here `__.
-
-Additional fields:
-
-``data``
- Vector of 4 coefficients for a cubic polynomial in temperature
-
-.. _sec-yaml-eos-peng-robinson:
-
-Peng-Robinson
--------------
-
-A model where species follow the Peng-Robinson equation of state as
-`described here `__.
-
-Additional fields:
-
-``a``
- Pure-species ``a`` coefficient [Pa*m^6/kmol^2]
-
-``b``
- Pure-species ``b`` coefficient [m^3/kmol]
-
-``acentric-factor``
- Pitzer's acentric factor [-]
-
-``binary-a``
- Optional mapping where the keys are species names and the values are the ``a``
- coefficients for binary interactions between the two species.
-
-Example::
-
- equation-of-state:
- model: Peng-Robinson
- units: {length: cm, quantity: mol}
- a: 5.998873E+11
- b: 18.9714
- acentric-factor: 0.344
- binary-a:
- H2: 4 bar*cm^6/mol^2
- CO2: 7.897e7 bar*cm^6/mol^2
-
-
-.. _sec-yaml-eos-redlich-kwong:
-
-Redlich-Kwong
--------------
-
-A model where species follow the Redlich-Kwong equation of state as
-`described here `__.
-
-Additional fields:
-
-``a``
- Pure-species ``a`` coefficient. Scalar or list of two values for a
- temperature-dependent expression.
-
-``b``
- Pure-species ``b`` coefficient.
-
-``binary-a``
- Mapping where the keys are species and the values are the ``a``
- coefficients for binary interactions between the two species.
-
-
-.. _sec-yaml-coverage-dependent-surface-species:
-
-Coverage-dependent Surface
---------------------------
-
-A model where species thermodynamic properties are calculated as a function
-coverage as
-`described here `__.
-
-Additional fields:
-
-``coverage-dependencies``
- Mapping where keys are the name of species whose coverage affects
- thermodynamic properties of the node-owner species. The map values are
- the dependency entries including ``model``, model-specific parameters,
- ``heat-capacity-a``, and ``heat-capacity-b`` that correspond
- to an individual dependency between the node-owner species and keyed species.
-
-``model``
- Dependency model for coverage-dependent enthalpy or entropy. It should be
- one of the four: ``linear``, ``polynomial``, ``piecewise-linear``
- or ``interpolative``. The ``model`` and model-specific parameters are grouped
- as follow.
-
- ``linear``: ``enthalpy``, ``entropy``
-
- ``polynomial``: ``enthalpy-coefficients``, ``entropy-coefficients``
-
- ``piecewise-linear``: ``enthalpy-low``, ``enthalpy-high``, ``enthalpy-change``,
- ``entropy-low``, ``entropy-high``, ``entropy-change``
-
- ``interpolative``: ``enthalpy-coverages``, ``enthalpies``, ``entropy-coverages``,
- ``entropies``
-
-``enthalpy`` or ``entropy``
- Slope of the coverage-dependent enthalpy or entropy used in the ``linear``
- model.
-
-``enthalpy-coefficients`` or ``entropy-coefficients``
- Array of polynomial coefficients in order of 1st, 2nd, 3rd, and 4th-order
- used in coverage-dependent enthalpy or entropy calculation with the ``polynomial``
- model.
-
-``enthalpy-low`` or ``entropy-low``
- Slope of the coverage-dependent enthalpy or entropy for the lower coverage
- region used in the ``piecewise-linear`` model.
-
-``enthalpy-high`` or ``entropy-high``
- Slope of the coverage-dependent enthalpy or entropy for the higher coverage
- region used in the ``piecewise-linear`` model.
-
-``enthalpy-change`` or ``entropy-change``
- Coverage that separates the lower and higher coverage regions of the
- coverage-dependent enthalpy or entropy used in the ``piecewise-linear`` model.
-
-``enthalpy-coverages`` or ``entropy-coverages``
- Array of discrete coverage values used in coverage-dependent enthalpy
- or entropy used in the ``interpolative`` model.
-
-``enthalpies`` or ``entropies``
- Array of discrete enthalpy or entropy values corresponding to the coverages
- in ``enthalpy-coverages`` or ``entropy-coverages``, respectively, used in the
- ``interpolative`` model.
-
-``heat-capacity-a`` or ``heat-capacity-b``
- Coefficient :math:`c^{(a)}` or :math:`c^{(b)}` used in the coverage-dependent
- ``heat capacity`` model.
-
-Example::
-
- coverage-dependencies:
- OC_Pt: {model: linear,
- units: {energy: eV, quantity: molec},
- enthalpy: 0.48, entropy: -0.031}
- C_Pt: {model: polynomial,
- units: {energy: J, quantity: mol},
- enthalpy-coefficients: [0.0, -3.86e4, 0.0, 4.2e5],
- entropy-coefficients: [0.8e3, 0.0, -1.26e4, 0.0]}
- CO2_Pt: {model: piecewise-linear,
- units: {energy: kJ, quantity: mol},
- enthalpy-low: 0.5e2, enthalpy-high: 1.0e2,
- enthalpy-change: 0.4,
- entropy-low: 0.1e2, entropy-high: -0.2e2,
- entropy-change: 0.4,
- heat-capacity-a: 0.02e-1, heat-capacity-b: -0.156e-1}
- O_Pt: {model: interpolative,
- units: {energy: kcal, quantity: mol},
- enthalpy-coverages: [0.0, 0.2, 0.4, 0.7, 0.9, 1.0],
- enthalpies: [0.0, 0.5, 1.0, 2.7, 3.5, 4.0],
- entropy-coverages: [0.0, 0.5, 1.0],
- entropies: [0.0, -0.7, -2.0]}
-
-
-.. _sec-yaml-species-transport:
-
-Species transport models
-========================
-
-``model``
- String specifying the model type. The only model that is specifically
- handled is ``gas``.
-
-Gas transport
--------------
-
-Species transport properties are a rare exception to Cantera's use of SI units,
-and use the units in which these properties are customarily reported. No
-conversions are supported.
-
-The additional fields of a ``gas`` transport entry are:
-
-``geometry``
- A string specifying the geometry of the molecule. One of ``atom``,
- ``linear``, or ``nonlinear``.
-
-``diameter``
- The Lennard-Jones collision diameter [Å]
-
-``well-depth``
- The Lennard-Jones well depth [K]
-
-``dipole``
- The permanent dipole moment [Debye]. Default 0.0.
-
-``polarizability``
- The dipole polarizability [Å^3]. Default 0.0.
-
-``rotational-relaxation``
- The rotational relaxation collision number at 298 K [-]. Default 0.0.
-
-``acentric-factor``
- Pitzer's acentric factor [-]. Default 0.0. This value may also be specified as part
- of the :ref:`critical-parameters ` field, in which case
- the value provided there supersedes this one.
-
-``dispersion-coefficient``
- The dispersion coefficient, normalized by :math:`e^2` [Å^5]. Default 0.0.
-
-``quadrupole-polarizability``
- The quadrupole polarizability [Å^5]. Default 0.0.
-
-Example::
-
- transport:
- model: gas
- geometry: linear
- well-depth: 107.4
- diameter: 3.458
- polarizability: 1.6
- rotational-relaxation: 3.8
diff --git a/doc/sphinx/yaml/yaml_format.rst b/doc/sphinx/yaml/yaml_format.rst
new file mode 100644
index 0000000000..7c5586b721
--- /dev/null
+++ b/doc/sphinx/yaml/yaml_format.rst
@@ -0,0 +1,7 @@
+*******************
+Cantera YAML Format
+*******************
+
+For information on the Cantera YAML format, refer to the
+:ct:`Cantera YAML Documentation `
+on the Cantera Developer website.
diff --git a/include/cantera/kinetics/BlowersMaselRate.h b/include/cantera/kinetics/BlowersMaselRate.h
index ac5d23aaf4..04cfa7821d 100644
--- a/include/cantera/kinetics/BlowersMaselRate.h
+++ b/include/cantera/kinetics/BlowersMaselRate.h
@@ -65,6 +65,7 @@ struct BlowersMaselData : public ReactionData
* k_f = A T^b \exp (-E_a/RT)
* \f]
*
+ * @since New in %Cantera 2.6
* @ingroup arrheniusGroup
*/
class BlowersMaselRate : public ArrheniusBase
diff --git a/include/cantera/thermo/BinarySolutionTabulatedThermo.h b/include/cantera/thermo/BinarySolutionTabulatedThermo.h
index 3ad35e59fd..0db4ddb92e 100644
--- a/include/cantera/thermo/BinarySolutionTabulatedThermo.h
+++ b/include/cantera/thermo/BinarySolutionTabulatedThermo.h
@@ -156,6 +156,7 @@ namespace Cantera
* molarVolume key is provided or not, the equation-of-state field in the pure species
* entries has to be defined.
*
+ * @since New in %Cantera 2.5
* @ingroup thermoprops
*/
class BinarySolutionTabulatedThermo : public IdealSolidSolnPhase
diff --git a/include/cantera/thermo/HMWSoln.h b/include/cantera/thermo/HMWSoln.h
index 5f040e1c62..2c19574d2a 100644
--- a/include/cantera/thermo/HMWSoln.h
+++ b/include/cantera/thermo/HMWSoln.h
@@ -582,8 +582,7 @@ class WaterProps;
* interaction may involve charged species in the solution as well.
*
* An example phase definition specifying a number of the above species interaction
- * parameters is given in the
- * YAML API Reference.
+ * parameters is given in the [YAML API Reference](@ref sec-yaml-HMW-electrolyte).
*
* ### Specification of the Debye-Huckel Constant
*
diff --git a/include/cantera/thermo/IdealGasPhase.h b/include/cantera/thermo/IdealGasPhase.h
index 989663a1c0..b9332250c0 100644
--- a/include/cantera/thermo/IdealGasPhase.h
+++ b/include/cantera/thermo/IdealGasPhase.h
@@ -242,7 +242,7 @@ namespace Cantera
* ## YAML Example
*
* An example ideal gas phase definition is given in the
- * YAML API Reference.
+ * [YAML API Reference](@ref sec-yaml-ideal-gas).
*
* @ingroup thermoprops
*/
diff --git a/include/cantera/thermo/IdealMolalSoln.h b/include/cantera/thermo/IdealMolalSoln.h
index 05ef4a52e7..0e950ff8a4 100644
--- a/include/cantera/thermo/IdealMolalSoln.h
+++ b/include/cantera/thermo/IdealMolalSoln.h
@@ -59,8 +59,7 @@ namespace Cantera
* constants involving species in this phase.
*
* An example phase definition is given in the
- *
- * YAML API Reference.
+ * [YAML API Reference](@ref sec-yaml-ideal-molal-solution).
*
* @ingroup thermoprops
*/
diff --git a/include/cantera/thermo/SurfPhase.h b/include/cantera/thermo/SurfPhase.h
index c1432fe7c3..4f88cc38d3 100644
--- a/include/cantera/thermo/SurfPhase.h
+++ b/include/cantera/thermo/SurfPhase.h
@@ -90,7 +90,7 @@ namespace Cantera
* \f]
*
* An example phase definition is given in the
- * YAML API Reference.
+ * [YAML API Reference](@ref sec-yaml-ideal-surface).
*
* @ingroup thermoprops
*/
diff --git a/interfaces/cython/cantera/_utils.pyx b/interfaces/cython/cantera/_utils.pyx
index 716f49906c..3480f88f60 100644
--- a/interfaces/cython/cantera/_utils.pyx
+++ b/interfaces/cython/cantera/_utils.pyx
@@ -174,7 +174,7 @@ cdef class AnyMap(dict):
A key-value store representing objects defined in Cantera's YAML input format.
Extends the capabilities of a normal `dict` object by providing functions for
- converting values between different unit systems. See :ref:`sec-yaml-units` for
+ converting values between different unit systems. See :ct:`sec-yaml-units` for
details on how units are handled in YAML input files.
"""
def __cinit__(self, *args, **kwawrgs):