[docs] Merge element/species information from website

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:
 

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:
+
+-   <tt>@ref sec-yaml-constant-cp</tt>: Constant heat capacity
+-   <tt>@ref sec-yaml-nasa7</tt>: 7-coefficient NASA polynomials in one or two
+    temperature regions
+-   <tt>@ref sec-yaml-nasa9</tt>: 9-coefficient NASA polynomials in one or more
+    temperature regions
+-   <tt>@ref sec-yaml-piecewise-gibbs</tt>: Interpolation between tabulated Gibbs free
+    energies using a constant heat capacity in each temperature interval
+-   <tt>@ref sec-yaml-shomate</tt>: 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:
+
+-   <tt>@ref sec-yaml-eos-constant-volume</tt>: A fixed value of mass density, molar
+    density, or molar volume
+-   <tt>@ref sec-yaml-eos-density-temperature-polynomial</tt>: Mass density
+    parameterized using a cubic polynomial in temperature
+-   <tt>@ref sec-yaml-eos-hkft</tt>: The Helgeson-Kirkham-Flowers-Tanger model for
+    aqueous species
+-   <tt>@ref sec-yaml-eos-ideal-gas</tt>: A species following the ideal gas law
+-   <tt>@ref sec-yaml-eos-ions-from-neutral</tt>: Used with the
+    ions-from-neutral-molecule phase model
+-   <tt>@ref sec-yaml-eos-liquid-water-iapws95</tt>: The IAPWS95 equation of state for
+    water, applied only in the liquid region
+-   <tt>@ref sec-yaml-eos-molar-volume-temperature-polynomial</tt>: Molar volume
+    parameterized using a cubic polynomial in temperature
+-   <tt>@ref sec-yaml-eos-peng-robinson</tt>: A species which follows the Peng-Robinson
+    equation of state
+-   <tt>@ref sec-yaml-eos-redlich-kwong</tt>: 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:
+
+-   <tt>@ref sec-yaml-species-transport-gas</tt>: 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:
+
+-   <tt>@ref sec-yaml-species-coverage-linear</tt>: Linear dependency model
+-   <tt>@ref sec-yaml-species-coverage-polynomial</tt>: Polynomial dependency model
+-   <tt>@ref sec-yaml-species-coverage-piecewise-linear</tt>:
+    Piecewise-linear dependency model
+-   <tt>@ref sec-yaml-species-coverage-interpolative</tt>:
+    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.
 <b>`thermo`</b>
 
 Mapping containing the reference state thermodynamic model
-specification and parameters. See <tt>@ref sec-yaml-species-thermo</tt>.
+specification and parameters.
+
+-   <b>`model`</b>: String specifying the model to be used. Required.
+    See @ref sec-yaml-species-thermo-properties for supported models.
+
+-   <b>`reference-pressure`</b>: 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).
 
 <b>`equation-of-state`</b>
 
@@ -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 <tt>@ref sec-yaml-species-eos</tt>.
+
+-   <b>`model`</b>: 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).
 
 <b>`critical-parameters`</b>
 
 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 <tt>@ref sec-yaml-species-crit-props</tt>.
+as @ref sec-yaml-eos-redlich-kwong.
+
+-   <b>`critical-temperature`</b>: The critical temperature of the species \[K\]
+
+-   <b>`critical-pressure`</b>: The critical pressure of the species \[Pa\]
+
+-   <b>`acentric-factor`</b>: Pitzer's acentric factor \f$\omega\f$ \[-\]
 
 <b>`transport`</b>
 
 Mapping containing the species transport model specification and
-parameters. See <tt>@ref sec-yaml-species-transport</tt>.
+parameters.
+
+-   <b>`model`</b>: String specifying the model type. See
+    @ref sec-yaml-species-transport-coefficients and
+    @ref sec-yaml-species-transport-models.
 
 <b>`sites`</b>
 
@@ -51,89 +214,11 @@ Additional model parameters used in the Debye-Hückel model. See
 
 <b>`coverage-dependencies`</b>
 
-Used in conjunction with the [coverage-dependent surface phase
-model](@ref sec-yaml-coverage-dependent-surface). See
-<tt>@ref sec-yaml-species-coverage</tt>.
-
-### thermo {#sec-yaml-species-thermo}
-
-Fields of a species `thermo` entry used by all models are:
-
-<b>`model`</b>
-
-String specifying the model to be used. Required. Supported model strings are:
-
--   <tt>@ref sec-yaml-constant-cp</tt>
--   <tt>@ref sec-yaml-nasa7</tt>
--   <tt>@ref sec-yaml-nasa9</tt>
--   <tt>@ref sec-yaml-piecewise-gibbs</tt>
--   <tt>@ref sec-yaml-shomate</tt>
-
-<b>`reference-pressure`</b>
-
-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
-
-<b>`model`</b>
-
-String specifying the model to be used. Required. Supported model strings are:
-
--   <tt>@ref sec-yaml-eos-constant-volume</tt>
--   <tt>@ref sec-yaml-eos-density-temperature-polynomial</tt>
--   <tt>@ref sec-yaml-eos-hkft</tt>
--   <tt>@ref sec-yaml-eos-ideal-gas</tt>
--   <tt>@ref sec-yaml-eos-ions-from-neutral</tt>
--   <tt>@ref sec-yaml-eos-liquid-water-iapws95</tt>
--   <tt>@ref sec-yaml-eos-molar-volume-temperature-polynomial</tt>
--   <tt>@ref sec-yaml-eos-peng-robinson</tt>
--   <tt>@ref sec-yaml-eos-redlich-kwong</tt>
-
-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}
-
-<b>`critical-temperature`</b>
-
-The critical temperature of the species \[K\]
-
-<b>`critical-pressure`</b>
-
-The critical pressure of the species \[Pa\]
-
-<b>`acentric-factor`</b>
-
-Pitzer's acentric factor \f$\omega\f$ \[-\]
-
-### transport {#sec-yaml-species-transport}
-
-<b>`model`</b>
-
-String specifying the model type. The only model that is
-specifically handled is <tt>@ref sec-yaml-species-transport-gas</tt>.
-
-### 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
-
-<b>`model`</b>
-
-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.
 
--   <tt>@ref sec-yaml-species-coverage-linear</tt>
--   <tt>@ref sec-yaml-species-coverage-polynomial</tt>
--   <tt>@ref sec-yaml-species-coverage-piecewise-linear</tt>
--   <tt>@ref sec-yaml-species-coverage-interpolative</tt>
+-   <b>`model`</b>: 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).

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:
 
 <b>`geometry`</b>
@@ -39,7 +39,7 @@ The rotational relaxation collision number at 298 K \[-\]. Default 0.0.
 <b>`acentric-factor`</b>
 
 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.
 
 <b>`dispersion-coefficient`</b>