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):