research/cantera
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Copy editing for YAML docs

Browse source 
Improve consistency of formatting. Eliminate duplicate hyperlink targets
by making them anonymous links.
This commit is contained in:
Bryan W. Weber 2019-06-21 10:26:08 -04:00 • committed by Ray Speth
parent dced8fbcad
commit 360ac9b79e
5 changed files with 183 additions and 127 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
doc/sphinx/yaml/elements.rst
View file

@ -6,7 +6,7 @@
Elements
********
``element`` entries are needed only when defining custom elements which are not
``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:

26
doc/sphinx/yaml/general.rst
View file

@ -7,10 +7,10 @@ General Structure
Sections
--------
The top level of a Cantera `YAML <https://yaml.org/spec/1.2/spec.html#Introduction>`_
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
The top level of a Cantera `YAML <https://yaml.org/spec/1.2/spec.html#Introduction>`__
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,
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
@ -19,26 +19,26 @@ for :ref:`sec-yaml-reactions`, :ref:`sec-yaml-species`, and
following structure::
phases:
- name: gas
- name: spam
thermo: ideal-gas
additional: fields
- name: solid
# Additional fields come after this
- name: green-eggs
thermo: model-name
additional: fields
# Additional fields come after this
species:
- name: A
additional: fields
# Additional fields come after this
- name: B
additional: fields
# Additional fields come after this
- name: C
additional: fields
# Additional fields come after this
reactions:
- equation: A + B <=> C + D
additional: fields
# Additional fields come after this
- equation: A + C <=> 2 D
additional: fields
# Additional fields come after this
Units
-----

147
doc/sphinx/yaml/phases.rst
View file

@ -4,7 +4,9 @@
Phase Definitions
*****************
The fields of a ``phase`` entry are:
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.
@ -15,8 +17,8 @@ The fields of a ``phase`` entry are:
- 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
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
@ -26,13 +28,13 @@ The fields of a ``phase`` entry are:
``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.
- 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-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
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.
@ -41,7 +43,7 @@ The fields of a ``phase`` entry are:
``skip-undeclared-elements`` option.
``skip-undeclared-elements``
If set to ``true``, do not add species which contain elements that are not
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.
@ -87,9 +89,9 @@ The fields of a ``phase`` entry are:
are:
- none
- `gas <https://cantera.org/documentation/dev/doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details>`_
- `surface <https://cantera.org/documentation/dev/doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details>`_
- `edge <https://cantera.org/documentation/dev/doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details>`_
- `gas <https://cantera.org/documentation/dev/doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details>`__
- `surface <https://cantera.org/documentation/dev/doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details>`__
- `edge <https://cantera.org/documentation/dev/doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details>`__
``reactions``
Source of reactions to include in the phase, if a kinetics model has been
@ -109,7 +111,7 @@ The fields of a ``phase`` entry are:
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
- 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.
@ -118,14 +120,14 @@ The fields of a ``phase`` entry are:
are:
- none
- `high-pressure <https://cantera.org/documentation/dev/doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details>`_
- `ionized-gas <https://cantera.org/documentation/dev/doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details>`_
- `mixture-averaged <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details>`_
- `mixture-averaged-CK <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details>`_
- `multicomponent <https://cantera.org/documentation/dev/doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details>`_
- `multicomponent-CK <https://cantera.org/documentation/dev/doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details>`_
- `unity-Lewis-number <https://cantera.org/documentation/dev/doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details>`_
- `water <https://cantera.org/documentation/dev/doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details>`_
- `high-pressure <https://cantera.org/documentation/dev/doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details>`__
- `ionized-gas <https://cantera.org/documentation/dev/doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details>`__
- `mixture-averaged <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details>`__
- `mixture-averaged-CK <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details>`__
- `multicomponent <https://cantera.org/documentation/dev/doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details>`__
- `multicomponent-CK <https://cantera.org/documentation/dev/doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details>`__
- `unity-Lewis-number <https://cantera.org/documentation/dev/doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details>`__
- `water <https://cantera.org/documentation/dev/doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details>`__
@ -187,7 +189,7 @@ Phase thermodynamic models
-----------------------------
A phase implementing tabulated standard state thermodynamics for one species in
a binary solution, as `described here <https://cantera.org/documentation/dev/doxygen/html/de/ddf/classCantera_1_1BinarySolutionTabulatedThermo.html#details>`_.
a binary solution, as `described here <https://cantera.org/documentation/dev/doxygen/html/de/ddf/classCantera_1_1BinarySolutionTabulatedThermo.html#details>`__.
Includes the fields of :ref:`sec-yaml-ideal-molal-solution`, plus:
@ -216,7 +218,7 @@ Includes the fields of :ref:`sec-yaml-ideal-molal-solution`, plus:
--------------------
A phase that is comprised of a fixed additive combination of other lattice
phases, as `described here <https://cantera.org/documentation/dev/doxygen/html/de/de1/classCantera_1_1LatticeSolidPhase.html#details>`_.
phases, as `described here <https://cantera.org/documentation/dev/doxygen/html/de/de1/classCantera_1_1LatticeSolidPhase.html#details>`__.
Additional fields:
@ -235,7 +237,7 @@ Example::
--------------------
An incompressible phase with constant density, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/de4/classCantera_1_1ConstDensityThermo.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/de4/classCantera_1_1ConstDensityThermo.html#details>`__.
Additional fields:
@ -254,7 +256,7 @@ Example::
----------------
The Debye-Hückel model as
`described here <https://cantera.org/documentation/dev/doxygen/html/d8/d9a/classCantera_1_1DebyeHuckel.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d8/d9a/classCantera_1_1DebyeHuckel.html#details>`__.
Additional parameters for this model are contained in the ``activity-data``
field:
@ -277,7 +279,7 @@ field:
The maximum ionic strength
``use-Helgeson-fixed-form``
Boolean
Boolean, ``true`` or ``false``
``default-ionic-radius``
Ionic radius to use for species where the ionic radius has not been
@ -288,8 +290,8 @@ field:
``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
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::
@ -315,7 +317,7 @@ Example::
--------
A one-dimensional edge between two surfaces, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1EdgePhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/d17/classCantera_1_1EdgePhase.html#details>`__.
Additional fields:
@ -334,7 +336,7 @@ Example::
----------------------------
A phase defined by a fixed value of the chemical potential, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/db0/classCantera_1_1FixedChemPotSSTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/db0/classCantera_1_1FixedChemPotSSTP.html#details>`__.
Additional fields:
@ -353,7 +355,7 @@ Example::
-----------------------
A phase with fixed composition, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d3/d50/classCantera_1_1StoichSubstance.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d3/d50/classCantera_1_1StoichSubstance.html#details>`__.
.. _sec-yaml-HMW-electrolyte:
@ -361,9 +363,9 @@ A phase with fixed composition, as
``HMW-electrolyte``
-------------------
A dilute or concentrated liquid electrolyte phase which obeys the Pitzer
A dilute or concentrated liquid electrolyte phase that obeys the Pitzer
formulation for nonideality, as
`described here <https://cantera.org/documentation/dev/doxygen/html/de/d1d/classCantera_1_1HMWSoln.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/de/d1d/classCantera_1_1HMWSoln.html#details>`__.
Additional parameters for this model are contained in the ``activity-data``
field:
@ -374,58 +376,77 @@ field:
``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.
@ -467,7 +488,7 @@ Example::
-------------
The ideal gas model as
`described here <https://cantera.org/documentation/dev/doxygen/html/d7/dfa/classCantera_1_1IdealGasPhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d7/dfa/classCantera_1_1IdealGasPhase.html#details>`__.
.. _sec-yaml-ideal-gas-VPSS:
@ -475,16 +496,17 @@ The ideal gas model as
------------------
The ideal gas model, using variable pressure standard state methods as
`described here <https://cantera.org/documentation/dev/doxygen/html/dc/ddb/classCantera_1_1IdealSolnGasVPSS.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/dc/ddb/classCantera_1_1IdealSolnGasVPSS.html#details>`__.
.. _sec-yaml-ideal-molal-solution:
``ideal-molal-solution``
------------------------
A phase based upon the mixing-rule assumption that all molality-based activity
A phase based on the mixing-rule assumption that all molality-based activity
coefficients are equal to one, as
`described here <https://cantera.org/documentation/dev/doxygen/html/da/d5c/classCantera_1_1IdealMolalSoln.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/da/d5c/classCantera_1_1IdealMolalSoln.html#details>`__.
Additional fields:
@ -500,16 +522,21 @@ Additional fields:
``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
@ -533,7 +560,7 @@ Example::
-------------------
A condensed phase ideal solution as
`described here <https://cantera.org/documentation/dev/doxygen/html/d3/d4c/classCantera_1_1IdealSolidSolnPhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d3/d4c/classCantera_1_1IdealSolidSolnPhase.html#details>`__.
Additional fields:
@ -548,7 +575,7 @@ Additional fields:
-----------------------
An ideal solution model using variable pressure standard state methods as
`described here <https://cantera.org/documentation/dev/doxygen/html/dc/ddb/classCantera_1_1IdealSolnGasVPSS.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/dc/ddb/classCantera_1_1IdealSolnGasVPSS.html#details>`__.
Additional fields:
@ -556,6 +583,7 @@ Additional fields:
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``
@ -565,7 +593,7 @@ 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 <https://cantera.org/documentation/dev/doxygen/html/d7/d4a/classCantera_1_1IonsFromNeutralVPSSTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d7/d4a/classCantera_1_1IonsFromNeutralVPSSTP.html#details>`__.
Additional fields:
@ -591,7 +619,7 @@ Example::
A simple thermodynamic model for a bulk phase, assuming a lattice of solid
atoms, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d1/da0/classCantera_1_1LatticePhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d1/da0/classCantera_1_1LatticePhase.html#details>`__.
Additional fields:
@ -605,7 +633,7 @@ Additional fields:
------------
A phase employing the Margules approximation for the excess Gibbs free energy, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d7/dfe/classCantera_1_1MargulesVPSSTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d7/dfe/classCantera_1_1MargulesVPSSTP.html#details>`__.
Additional fields:
@ -614,20 +642,24 @@ Additional fields:
``species``
A list of two species names
``excess-enthalpy``
A list of two elements specifying the first and second 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 elements specifying the first and second 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 elements specifying the first and second 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 elements specifying the first and second 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].
@ -646,12 +678,13 @@ Example::
--------------------------
A condensed phase non-ideal solution with two species, as
`described here <https://cantera.org/documentation/dev/doxygen/html/dd/d3a/classCantera_1_1MaskellSolidSolnPhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/dd/d3a/classCantera_1_1MaskellSolidSolnPhase.html#details>`__.
Additional fields:
``excess-enthalpy``
The molar excess enthalpy
``product-species``
String specifying the "product" species
@ -668,20 +701,21 @@ Example::
------------------
A phase representing an electron cloud, such as conduction electrons in a metal,
as `described here <https://cantera.org/documentation/dev/doxygen/html/d9/d13/classCantera_1_1MetalPhase.html#details>`_.
as `described here <https://cantera.org/documentation/dev/doxygen/html/d9/d13/classCantera_1_1MetalPhase.html#details>`__.
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 <https://cantera.org/documentation/dev/doxygen/html/d1/d29/classCantera_1_1PureFluidPhase.html#details>`_.
as `described here <https://cantera.org/documentation/dev/doxygen/html/d1/d29/classCantera_1_1PureFluidPhase.html#details>`__.
Additional fields:
@ -696,6 +730,7 @@ Additional fields:
- ``oxygen``
- ``water``
.. _sec-yaml-Redlich-Kister:
``Redlich-Kister``
@ -703,7 +738,7 @@ Additional fields:
A phase employing the Redlich-Kister approximation for the excess Gibbs free
energy, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d23/classCantera_1_1RedlichKisterVPSSTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d23/classCantera_1_1RedlichKisterVPSSTP.html#details>`__.
Additional fields:
@ -712,9 +747,11 @@ Additional 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
@ -736,28 +773,30 @@ Example::
-----------------
A multi-species Redlich-Kwong phase as
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/d29/classCantera_1_1RedlichKwongMFTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/d29/classCantera_1_1RedlichKwongMFTP.html#details>`__.
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 <https://cantera.org/documentation/dev/doxygen/html/d2/d95/classCantera_1_1SurfPhase.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d2/d95/classCantera_1_1SurfPhase.html#details>`__.
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 <https://cantera.org/documentation/dev/doxygen/html/dc/d86/classCantera_1_1WaterSSTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/dc/d86/classCantera_1_1WaterSSTP.html#details>`__.

53
doc/sphinx/yaml/reactions.rst
View file

@ -6,12 +6,12 @@
Reactions
*********
The fields of a ``reaction`` entry are:
The fields common to all ``reaction`` entries 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.
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 ``=>``.
@ -28,7 +28,7 @@ The fields of a ``reaction`` entry are:
- :ref:`Chebyshev <sec-Chebyshev>`
Reactions on surfaces or edges are automatically treated as
:ref:`interface <sec-interface-reaction>` reactions, and reactions which
:ref:`interface <sec-interface-reaction>` reactions, and reactions that
involve charge transfer between phases are automatically treated as
:ref:`electrochemical <sec-electrochemical-reaction>` reactions, without the
need to specify the ``type``.
@ -41,17 +41,20 @@ The fields of a ``reaction`` entry are:
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 <https://cantera.org/science/reactions.html#reaction-orders>`_
`Reaction orders <https://cantera.org/science/reactions.html#reaction-orders>`__
for additional information.
``negative-orders``
Boolean indicating whether negative reaction orders are allowed. The default
is ``false``.
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.
.. _sec-arrhenius:
Arrhenius expression
@ -93,12 +96,12 @@ Reaction types
A homogeneous reaction with a pressure-independent rate coefficient and mass
action kinetics, as
`described here <https://cantera.org/science/reactions.html#reactions-with-a-pressure-independent-rate>`_.
`described here <https://cantera.org/science/reactions.html#reactions-with-a-pressure-independent-rate>`__.
Additional fields are:
``rate-constant``
An :ref:`sec-arrhenius`.
An :ref:`Arrhenius-type <sec-arrhenius>` list or mapping.
``negative-A``
A boolean indicating whether a negative value for the pre-exponential factor
@ -117,7 +120,7 @@ Example::
--------------
A three body reaction as
`described here <https://cantera.org/science/reactions.html#three-body-reactions>`_.
`described here <https://cantera.org/science/reactions.html#three-body-reactions>`__.
The reaction equation should include the third body collision partner ``M``.
@ -138,14 +141,14 @@ Example::
-----------
A falloff reaction as
`described here <https://cantera.org/science/reactions.html#falloff-reactions>`_.
`described here <https://cantera.org/science/reactions.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
latter case is equivalent to setting the efficiency for ``name`` to 1 and the
efficiency for all other species to 0.
Includes fields for specifying :ref:`efficiencies <sec-efficiencies>` as well
Includes field for specifying :ref:`efficiencies <sec-efficiencies>` as well
as:
``high-P-rate-constant``
@ -156,13 +159,13 @@ as:
``Troe``
Parameters for the
`Troe <https://cantera.org/science/reactions.html#the-troe-falloff-function>`_
`Troe <https://cantera.org/science/reactions.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/reactions.html#the-sri-falloff-function>`_
`SRI <https://cantera.org/science/reactions.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.
@ -182,7 +185,7 @@ Example::
------------------------
A chemically activated reaction as
`described here <https://cantera.org/science/reactions.html#chemically-activated-reactions>`_.
`described here <https://cantera.org/science/reactions.html#chemically-activated-reactions>`__.
The parameters are the same as for :ref:`sec-falloff` reactions.
@ -199,9 +202,9 @@ Example::
--------------------------------
A pressure-dependent reaction using multiple Arrhenius expressions as
`described here <https://cantera.org/science/reactions.html#pressure-dependent-arrhenius-rate-expressions-p-log>`_.
`described here <https://cantera.org/science/reactions.html#pressure-dependent-arrhenius-rate-expressions-p-log>`__.
The additional field is:
The only additional field in this reaction type is:
``rate-constants``
A list of mappings, where each mapping is the mapping form of an
@ -224,16 +227,16 @@ Example::
-------------
A reaction parameterized as a bivariate Chebyshev polynomial as
`described here <https://cantera.org/science/reactions.html#chebyshev-reaction-rate-expressions>`_.
`described here <https://cantera.org/science/reactions.html#chebyshev-reaction-rate-expressions>`__.
Additional fields are:
``temperature-range``
A list of two elements specifying the minimum and maximum temperatures at
A list of two values 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
A list of two values specifying the minimum and maximum pressures at
which the rate constant is valid
``data``
@ -260,12 +263,12 @@ Example::
A reaction occuring on a surface between two bulk phases, or along an edge
at the intersection of two surfaces, as
`described here <https://cantera.org/science/reactions.html#surface-reactions>`_.
`described here <https://cantera.org/science/reactions.html#surface-reactions>`__.
Includes the fields of an :ref:`sec-elementary` reaction plus:
``sticking-coefficient``
An :ref:`sec-arrhenius` expression for the sticking coefficient
An :ref:`Arrhenius-type <sec-arrhenius>` expression for the sticking coefficient
``Motz-Wise``
A boolean applicable to sticking reactions, indicating whether to use the
@ -302,7 +305,7 @@ Example::
-------------------
Interface reactions involving charge transfer between phases,
as `described here <https://cantera.org/documentation/dev/doxygen/html/d6/ddd/classCantera_1_1ElectrochemicalReaction.html#details>`_.
as `described here <https://cantera.org/documentation/dev/doxygen/html/d6/ddd/classCantera_1_1ElectrochemicalReaction.html#details>`__.
Includes the fields of an :ref:`sec-interface-reaction` reaction, plus:

82
doc/sphinx/yaml/species.rst
View file

@ -12,8 +12,8 @@ The fields of a ``species`` entry are:
String identifier used for the species. Required.
``composition``
Mapping which specifies the elemental composition of the species,
e.g. ``{C: 1, H: 4}``. Required.
Mapping that specifies the elemental composition of the species,
e.g., ``{C: 1, H: 4}``. Required.
``thermo``
Mapping containing the reference state thermodynamic model specification
@ -30,7 +30,7 @@ The fields of a ``species`` entry are:
parameters. See :ref:`sec-yaml-species-transport`.
``sites``
The number of sites occupied by a surface or edge species. Default 1.
The number of sites occupied by a surface or edge species. Default is 1.
``ionic-radius``
Size of the species. Used in the Debye-Hückel model.
@ -67,26 +67,27 @@ Fields of a species ``thermo`` entry used by all models are:
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 <https://cantera.org/science/science-species.html#the-nasa-7-coefficient-polynomial-parameterization>`_,
The polynomial form `described here <https://cantera.org/science/science-species.html#the-nasa-7-coefficient-polynomial-parameterization>`__,
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.
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.
ascending order. Note that this is different from the standard CHEMKIN
formulation that uses two temperature regions listed in descending order.
Example::
@ -99,19 +100,20 @@ Example::
- [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 <https://cantera.org/science/science-species.html#the-nasa-9-coefficient-polynomial-parameterization>`_,
The polynomial form `described here <https://cantera.org/science/science-species.html#the-nasa-9-coefficient-polynomial-parameterization>`__,
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.
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
@ -140,16 +142,15 @@ Example::
Shomate polynomials
-------------------
The polynomial form `described here <https://cantera.org/science/science-species.html#the-shomate-parameterization>`_,
The polynomial form `described here <https://cantera.org/science/science-species.html#the-shomate-parameterization>`__,
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.
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
@ -173,15 +174,18 @@ Example::
Constant heat capacity
----------------------
The constant heat capacity model `described here <https://cantera.org/science/science-species.html#constant-heat-capacity>`_.
The constant heat capacity model `described here <https://cantera.org/science/science-species.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.
@ -200,16 +204,18 @@ Piecewise Gibbs
---------------
A model based on piecewise interpolation of the Gibbs free energy as
`described here <https://cantera.org/documentation/dev/doxygen/html/d4/d9e/classCantera_1_1Mu0Poly.html#details>`_
`described here <https://cantera.org/documentation/dev/doxygen/html/d4/d9e/classCantera_1_1Mu0Poly.html#details>`__
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
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
@ -250,7 +256,7 @@ Constant volume
---------------
A constant volume model as
`described here <https://cantera.org/documentation/dev/doxygen/html/da/d33/classCantera_1_1PDSS__ConstVol.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/da/d33/classCantera_1_1PDSS__ConstVol.html#details>`__.
Any one of the following may be specified:
@ -276,7 +282,7 @@ Density temperature polynomial
------------------------------
A model in which the density varies with temperature as
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d2f/classCantera_1_1PDSS__SSVol.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d2f/classCantera_1_1PDSS__SSVol.html#details>`__.
Additional fields:
@ -297,7 +303,7 @@ HKFT
----
The Helgeson-Kirkham-Flowers-Tanger model as
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/d18/classCantera_1_1PDSS__HKFT.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d9/d18/classCantera_1_1PDSS__HKFT.html#details>`__.
Additional fields:
@ -308,7 +314,7 @@ Additional fields:
Entropy of formation at the reference temperature and pressure
``a``
4-element vector containing the coefficients :math:`a_1, \ldots a_4`
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`
@ -334,8 +340,8 @@ Ideal gas
---------
A species using the ideal gas equation of state, as
`described here <https://cantera.org/documentation/dev/doxygen/html/df/d31/classCantera_1_1PDSS__IdealGas.html#details>`_. This model is the default
if no `equation-of-state` section is included.
`described here <https://cantera.org/documentation/dev/doxygen/html/df/d31/classCantera_1_1PDSS__IdealGas.html#details>`__.
This model is the default if no ``equation-of-state`` section is included.
.. _sec-yaml-eos-ions-from-neutral:
@ -345,7 +351,7 @@ Ions from neutral molecule
A species equation of state model used with the ``ions-from-neutral-molecule``
phase model, as
`described here <https://cantera.org/documentation/dev/doxygen/html/d5/df4/classCantera_1_1PDSS__IonsFromNeutral.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d5/df4/classCantera_1_1PDSS__IonsFromNeutral.html#details>`__.
Additional fields:
@ -369,7 +375,7 @@ Molar volume temperature polynomial
-----------------------------------
A model in which the molar volume varies with temperature as
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d2f/classCantera_1_1PDSS__SSVol.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d0/d2f/classCantera_1_1PDSS__SSVol.html#details>`__.
Additional fields:
@ -383,12 +389,12 @@ Redlich-Kwong
-------------
A model where species follow the Redlich-Kwong equation of state as
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/d29/classCantera_1_1RedlichKwongMFTP.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/d6/d29/classCantera_1_1RedlichKwongMFTP.html#details>`__.
Additional fields:
``a``
Pure-species ``a`` coefficient. Scalar or list of two elements for a
Pure-species ``a`` coefficient. Scalar or list of two values for a
temperature-dependent expression.
``b``
@ -405,7 +411,7 @@ Water IAPWS95
-------------
A detailed equation of state for liquid water as
`described here <https://cantera.org/documentation/dev/doxygen/html/de/d64/classCantera_1_1PDSS__Water.html#details>`_.
`described here <https://cantera.org/documentation/dev/doxygen/html/de/d64/classCantera_1_1PDSS__Water.html#details>`__.
.. _sec-yaml-species-transport:
@ -429,20 +435,28 @@ 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.