diff --git a/doc/sphinx/index.rst b/doc/sphinx/index.rst index 635c395db..b2b307944 100644 --- a/doc/sphinx/index.rst +++ b/doc/sphinx/index.rst @@ -11,6 +11,7 @@ format. .. toctree:: :maxdepth: 2 + yaml/index cti/classes cython/index matlab/index diff --git a/doc/sphinx/yaml/elements.rst b/doc/sphinx/yaml/elements.rst new file mode 100644 index 000000000..6fd6a35ea --- /dev/null +++ b/doc/sphinx/yaml/elements.rst @@ -0,0 +1,25 @@ +.. highlight:: yaml + +.. _sec-yaml-elements: + +******** +Elements +******** + +``element`` entries are needed only when defining custom elements which 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 new file mode 100644 index 000000000..68ce0ee33 --- /dev/null +++ b/doc/sphinx/yaml/general.rst @@ -0,0 +1,97 @@ +.. highlight:: yaml + +***************** +General Structure +***************** + +Sections +-------- + +The top level of a Cantera `YAML `_ +input file is a mapping which defines different input file sections. Each +section consists of a list of mappings which define objects of the same type, +e.g. 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: gas + thermo: ideal-gas + additional: fields + - name: solid + thermo: model-name + additional: fields + + species: + - name: A + additional: fields + - name: B + additional: fields + - name: C + additional: fields + + reactions: + - equation: A + B <=> C + D + additional: fields + - equation: A + C <=> 2 D + additional: fields + +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``, or any unit of energy per quantity (``J/kmol``, + ``cal/mol``, etc.) +- 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. + +Conversions of activation energies implicitly include scaling by the gas +constant where necessary. 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 new file mode 100644 index 000000000..ea66b5588 --- /dev/null +++ b/doc/sphinx/yaml/index.rst @@ -0,0 +1,13 @@ + +************************* +YAML Input File Reference +************************* + +.. toctree:: + :maxdepth: 2 + + general + phases + elements + species + reactions diff --git a/doc/sphinx/yaml/phases.rst b/doc/sphinx/yaml/phases.rst new file mode 100644 index 000000000..95d33dfab --- /dev/null +++ b/doc/sphinx/yaml/phases.rst @@ -0,0 +1,728 @@ +.. highlight:: yaml + +***************** +Phase Definitions +***************** + +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-element 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 which 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-element 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 which contain elements that are not + explicitly included in the phase. The default is ``false``, where the + presence of such species is considered an error. + +``state`` + A mapping specifying the thermodynamic state. See + :ref:`sec-yaml-setting-state`. + +``thermo`` + String specifying the phase thermodynamic model to be used. Supported model + strings are: + + - :ref:`compound-lattice ` + - :ref:`constant-density ` + - :ref:`Debye-Huckel ` + - :ref:`edge ` + - :ref:`fixed-chemical-potential ` + - :ref:`fixed-stoichiometry ` + - :ref:`HMW-electrolyte ` + - :ref:`ideal-gas ` + - :ref:`ideal-gas-VPSS ` + - :ref:`ideal-molal-solution ` + - :ref:`ideal-condensed ` + - :ref:`ideal-solution-VPSS ` + - :ref:`ideal-surface ` + - :ref:`ions-from-neutral-molecule ` + - :ref:`lattice ` + - :ref:`Margules ` + - :ref:`Maskell-solid-solution ` + - :ref:`electron-cloud ` + - :ref:`pure-fluid ` + - :ref:`Redlich-Kister ` + - :ref:`Redlich-Kwong ` + - :ref:`water-IAPWS95 ` + +``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-item 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. + +``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-phase-thermo-models: + +Phase thermodynamic models +========================== + +.. _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-constant-density: + +``constant-density`` +-------------------- + +An incompressible phase with constant density, as +`described here `_. + +Additional fields: + +``density`` + The density of the phase + +Example:: + + thermo: constant-density + density: 0.7 g/cm^3 + + +.. _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. + + ``B_Debye`` + The Debye "B" parameter + + ``max-ionic-strength`` + The maximum ionic strength + + ``use-Helgeson-fixed-form`` + Boolean + + ``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 which contains a + list of two species names, and a ``beta`` key which 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 + + +.. _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-chemical-potential: + +``fixed-chemical-potential`` +---------------------------- + +A phase defined by a fixed value of the chemical potential, as +`described here `_. + +Additional fields: + +``chemical-potential`` + The molar chemical potential of the phase + +Example:: + + thermo: fixed-chemical-potential + chemical-potential: -2.3e7 J/kmol + + +.. _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 which 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``. + ``A_Debye`` + The value of the Debye "A" parameter, or the string ``variable`` to use + a calculation based on the water equation of state. + ``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 `_. + +.. _sec-yaml-ideal-gas-VPSS: + +``ideal-gas-VPSS`` +------------------ + +The ideal gas model, using variable pressure standard state methods as +`described here `_. + +.. _sec-yaml-ideal-molal-solution: + +``ideal-molal-solution`` +------------------------ + +A phase based upon 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-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 `_. + +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-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 elements 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 elements 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 elements 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 elements 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 `_. + +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: + - ``carbondioxide`` + - ``heptane`` + - ``hfc134a`` + - ``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. + +.. _sec-yaml-ideal-surface: + +``ideal-surface`` +----------------- + +An ideal surface phase, as +`described here `_. + +Additional fields: + +``site-density`` + The molar density of surface sites + +.. _sec-yaml-water-IAPWS95: + +``water-IAPWS95`` +----------------- + +An equation of state for liquid water, as +`described here `_. diff --git a/doc/sphinx/yaml/reactions.rst b/doc/sphinx/yaml/reactions.rst new file mode 100644 index 000000000..4af1a1d9a --- /dev/null +++ b/doc/sphinx/yaml/reactions.rst @@ -0,0 +1,294 @@ +.. highlight:: yaml + +.. _sec-yaml-reactions: + +********* +Reactions +********* + +The fields of a ``reaction`` entry are: + +``equation`` + The stoichiometric equation for the reaction. Each term (i.e. 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 reacions 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:`falloff ` + - :ref:`chemically-activated ` + - :ref:`pressure-dependent-Arrhenius ` + - :ref:`Chebyshev ` + + Reactions on surfaces or edges are automatically treated as + :ref:`interface ` reactions, without the need to + specify the ``type``. + +``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``. + +.. _sec-arrhenius: + +Arrhenius expression +==================== + +Arrhenius expressions can be specified as either a three-element list containing +the pre-exponential factor :math:`A`, the temperature exponent :math:`b`, and +the activation energy :math:`E_a`, or a mapping containing the fields ``A``, +``b``, and ``Ea``. 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-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-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:`sec-arrhenius`. + +``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-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-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 +efficiency for all other species to 0. + +Includes fields for specifying :ref:`efficiencies ` as well +as: + +``high-P-rate-constant`` + An :ref:`sec-arrhenius` expression for the high-pressure limit + +``low-P-rate-constant`` + An :ref:`sec-arrhenius` 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. + +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-chemically-activated: + +``chemically-activated`` +------------------------ + +A chemically activated reaction as +`described here `_. + +The parameters are the same as for :ref:`sec-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-pressure-dependent-Arrhenius: + +``pressure-dependent-Arrhenius`` +-------------------------------- + +A pressure-dependent reaction using multiple Arrhenius expressions as +`described here `_. + +The additional field is: + +``rate-constants`` + A list of mappings, where each mapping is the mapping form of an + :ref:`sec-arrhenius` 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-Chebyshev: + +``Chebyshev`` +------------- + +A reaction parameterized as a bivariate Chebyshev polynomial as +`described here `_. + +Additional fields are: + +``temperature-range`` + A list of two elements specifying the minimum and maximum temperatures at + which the rate constant is valid + +``pressure-range`` + A list of two elements 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-interface-reaction: + +``interface`` +------------- + +A reaction occuring 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-elementary` reaction plus: + +``sticking-coefficient`` + An :ref:`sec-arrhenius` expression for the sticking coefficient + +``Motz-Wise`` + A boolean applicable to sticking reactions, 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 for sticking reactions only if + the reaction includes multiple non-surface species. + +``coverage-dependencies`` + A mapping of species names to coverage dependence parameters, where these + parameters are contained in 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 + +Example:: + + 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}} diff --git a/doc/sphinx/yaml/species.rst b/doc/sphinx/yaml/species.rst new file mode 100644 index 000000000..96285a297 --- /dev/null +++ b/doc/sphinx/yaml/species.rst @@ -0,0 +1,457 @@ +.. highlight:: yaml + +.. _sec-yaml-species: + +******* +Species +******* + +The fields of a ``species`` entry are: + +``name`` + String identifier used for the species. Required. + +``composition`` + Mapping which specifies the elemental composition of the species, + e.g. ``{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`` + Mapping containing the equation of state model specification for the + species, any parameters for that model, and any parameters for interactions + with other species. :ref:`sec-yaml-species-eos`. If this field is absent, + the ``ideal-gas`` model is assumed. + +``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 1. + +``ionic-radius`` + Size of the species. Used in the Debye-Hückel model. + +``electrolyte-species-type`` + One of ``solvent``, ``charged-species``, ``weak-acid-associated``, + ``strong-acid-associated``, ``polar-neutral``, or ``nonpolar-neutral``. + The types ``solvent``, ``charged-species``, and ``nonpolar-neutral`` can be + inferred automatically. Used in the Debye-Hückel model. + +``weak-acid-charge`` + Charge to use for species can break apart into charged species. Used in the + Debye-Hückel model. + + +.. _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 of giving the temperature intervals on which the given 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 temperature, intermediate temperature, 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: 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 of giving the temperature intervals on which the given 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 of giving the temperature intervals on which the given 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 temperature, intermediate temperature, 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] + 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. + +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, i.e. 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. + +Example:: + + thermo: + model: piecewise-Gibbs + h0: -230.015 kJ/mol + dimensionless: true + data: {298.15: -91.50963, 333.15: -85.0} + + +.. _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:`molar-volume-temperature-polynomial ` + - :ref:`Redlich-Kwong ` + - :ref:`water-IAPWS95 ` + + +.. _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 `_. This model is the default +if no `equation-of-state` section is included. + + +.. _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 `_. + +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-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-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 elements 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-eos-water-iapws95: + +Water IAPWS95 +------------- + +A detailed equation of state for liquid water as +`described here `_. + + +.. _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. +``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