diff --git a/doc/doxygen/yaml/elements.md b/doc/doxygen/yaml/elements.md index d9aa44070c0..3a6a6eeb13e 100644 --- a/doc/doxygen/yaml/elements.md +++ b/doc/doxygen/yaml/elements.md @@ -1,7 +1,35 @@ # Element Entries {#sec-yaml-elements} -`element` entries are needed only when defining custom elements that are -not standard chemical elements, or defining specific isotopes. +[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 +``` + +## Supported Fields The fields of an `element` entry are: diff --git a/doc/doxygen/yaml/species.md b/doc/doxygen/yaml/species.md index 9d0a05a2aab..0db5a2dbf70 100644 --- a/doc/doxygen/yaml/species.md +++ b/doc/doxygen/yaml/species.md @@ -2,7 +2,146 @@ [TOC] -## Fields +## 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 @ref 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 @ref 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 @ref 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 + +For descriptions of fields used by each model as well as examples, +see @ref sec-yaml-species-coverage-models. + +## Supported Fields The fields of a `species` entry are: @@ -18,7 +157,16 @@ example, `{C: 1, H: 4}`. Required. `thermo` Mapping containing the reference state thermodynamic model -specification and parameters. See @ref sec-yaml-species-thermo. +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` @@ -27,18 +175,33 @@ 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. -See @ref sec-yaml-species-eos. + +- `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. See @ref sec-yaml-species-crit-props. +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. See @ref sec-yaml-species-transport. +parameters. + +- `model`: String specifying the model type. See + @ref sec-yaml-species-transport-coefficients and + @ref sec-yaml-species-transport-models. `sites` @@ -51,89 +214,11 @@ Additional model parameters used in the Debye-Hückel model. See `coverage-dependencies` -Used in conjunction with the [coverage-dependent surface phase -model](@ref sec-yaml-coverage-dependent-surface). See -@ref sec-yaml-species-coverage. - -### thermo {#sec-yaml-species-thermo} - -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 sec-yaml-constant-cp -- @ref sec-yaml-nasa7 -- @ref sec-yaml-nasa9 -- @ref sec-yaml-piecewise-gibbs -- @ref sec-yaml-shomate - -`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. - -### equation-of-state {#sec-yaml-species-eos} - -A species `equation-of-state` entry is identified by the field - -`model` - -String specifying the model to be used. Required. Supported model strings are: - -- @ref sec-yaml-eos-constant-volume -- @ref sec-yaml-eos-density-temperature-polynomial -- @ref sec-yaml-eos-hkft -- @ref sec-yaml-eos-ideal-gas -- @ref sec-yaml-eos-ions-from-neutral -- @ref sec-yaml-eos-liquid-water-iapws95 -- @ref sec-yaml-eos-molar-volume-temperature-polynomial -- @ref sec-yaml-eos-peng-robinson -- @ref sec-yaml-eos-redlich-kwong - -Additional fields are specific to the species equation of state model -(see @ref sec-yaml-species-eos-models). - -### critical-parameters {#sec-yaml-species-crit-props} - -`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 {#sec-yaml-species-transport} - -`model` - -String specifying the model type. The only model that is -specifically handled is @ref sec-yaml-species-transport-gas. - -### coverage-dependencies {#sec-yaml-species-coverage} - -Species `coverage-dependencies` entries are mappings where keys are the name of species -whose coverage affects thermodynamic properties of the node-owner species, see -@ref Cantera.CoverageDependentSurfPhase. - -Map entries of `coverage-dependencies` are identified by the field - -`model` - -String specifying the model to be used. Required. Supported model strings are: +Mappings where keys are the name of species whose coverage affects thermodynamic +properties of the node-owner species, see @ref Cantera.CoverageDependentSurfPhase. -- @ref sec-yaml-species-coverage-linear -- @ref sec-yaml-species-coverage-polynomial -- @ref sec-yaml-species-coverage-piecewise-linear -- @ref sec-yaml-species-coverage-interpolative +- `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). +- 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/speciestransport.md b/doc/doxygen/yaml/speciestransport.md index c32fff90c3a..1179b9b3018 100644 --- a/doc/doxygen/yaml/speciestransport.md +++ b/doc/doxygen/yaml/speciestransport.md @@ -3,12 +3,12 @@ Species transport models are specified using the `transport` field of @ref sec-yaml-species. -## gas {#sec-yaml-species-transport-gas} - 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` @@ -39,7 +39,7 @@ 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 sec-yaml-species-crit-props field, +specified as part of the `critical-parameters` field, in which case the value provided there supersedes this one. `dispersion-coefficient`