From 197d584939e8ad9aed9811d9a6b6dc9144c175c4 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 28 Jun 2019 13:48:03 -0400 Subject: [PATCH 01/45] Add link to YAML reference documentation --- pages/documentation/dev-docs.html | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pages/documentation/dev-docs.html b/pages/documentation/dev-docs.html index 98aeeacb4..2c48a1427 100644 --- a/pages/documentation/dev-docs.html +++ b/pages/documentation/dev-docs.html @@ -111,6 +111,11 @@

Search the documentation

Other Documentation
+
+ + YAML Input File Reference + +
CTI Input File Class Reference From 716da1af690baff5c9c5cb7197505f899efb3c93 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 28 Jun 2019 18:24:18 -0400 Subject: [PATCH 02/45] Fix broken link to class ThermoPhase documentation Needed to be updated after setting Doxygen to use subdirectories --- pages/tutorials/cti/phases.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/tutorials/cti/phases.rst b/pages/tutorials/cti/phases.rst index 3f882434b..afc1dfd50 100644 --- a/pages/tutorials/cti/phases.rst +++ b/pages/tutorials/cti/phases.rst @@ -22,7 +22,7 @@ corresponding to different types of phases, such as ``ideal_gas``, using one of the directives corresponding to an implemented phase type. A map with the full listing of available phase types is provided at the `ThermoPhase Class Reference -<{{% ct_docs doxygen/html/classCantera_1_1ThermoPhase.html %}}>`__. However, these phase types +<{{% ct_docs doxygen/html/dc/d38/classCantera_1_1ThermoPhase.html %}}>`__. However, these phase types share many common features, and so we will begin by discussing those aspects common to all entries for phases. The :cti:class:`phase` class contains the features common to all phase types. From b910987c3cea730fe2fb040af3e1c69e96131185 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 8 Oct 2019 15:42:31 -0400 Subject: [PATCH 03/45] Remove CTI-specific content from the 'science' section Useful content that was not already in the CTI tutorial has been relocated to that section. --- pages/science/phases.rst | 100 ++----------- pages/science/reactions.rst | 192 ++++++++----------------- pages/science/species.rst | 231 ++++++------------------------ pages/tutorials/cti/reactions.rst | 75 ++++++++++ pages/tutorials/cti/species.rst | 126 ++++++++++++++++ 5 files changed, 315 insertions(+), 409 deletions(-) diff --git a/pages/science/phases.rst b/pages/science/phases.rst index d99a5033c..dcc382260 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -18,30 +18,14 @@ Bulk, Three-Dimensional Phases Ideal Gas Mixtures ------------------ -Far and away, the most commonly-used phase model in Cantera is the :cti:class:`ideal_gas` model. -Many combustion and CVD simulations make use of reacting ideal gas mixtures. These can be defined -using the :cti:class:`ideal_gas` entry. The Cantera ideal gas model allows any number of species, -and any number of reactions among them. It supports all of the options in the widely-used model -described by Kee et al. [#Kee1989]_, plus some additional options for species thermodynamic -properties and reaction rate expressions. - -An example of an :cti:class:`ideal_gas` entry is shown below: - -.. code:: python - - ideal_gas(name='air8', - elements='N O Ar', - species='gri30: N2 O2 N O NO NO2 N2O AR', - reactions='all', - transport='Mix', - initial_state=state(temperature=500.0, - pressure=(1.0, 'atm'), - mole_fractions='N2:0.78, O2:0.21, AR:0.01')) - -This entry defines an ideal gas mixture that contains 8 species, the definitions of which are -imported from dataset ``gri30`` (file ``gri30.xml``). All reactions defined in the file are to be -included, transport properties are to be computed using the mixture-averaged rule, and the state of -the gas is to be set initially to 500 K, 1 atm, and a composition that corresponds to air. +Far and away, the most commonly-used phase model in Cantera is the **ideal gas** model. +Many combustion and CVD simulations make use of reacting ideal gas mixtures. The Cantera +ideal gas model allows any number of species, and any number of reactions among them. +It supports all of the options in the widely-used model described by Kee et al. +[#Kee1989]_, plus some additional options for species thermodynamic properties +and reaction rate expressions. + +Ideal gas mixtures can be defined in the CTI format using the :cti:class:`ideal_gas` entry. .. _sec-transport-models: @@ -50,43 +34,18 @@ Transport Models Two transport models are available for use with ideal gas mixtures. The first is a multicomponent transport model that is based on the model described by Dixon-Lewis [#dl68]_ (see also Kee et al. -[#Kee2017]_). The second is a model that uses the mixture-averaged rule. To select the -multicomponent model, set the transport field to the string ``'Multi'``, and to select the -mixture-averaged model, set it to the string ``'Mix'``: - -.. code:: python - - ideal_gas(name="gas1", - # ... - transport="Multi", # use multicomponent formulation - # ... - ) - - ideal_gas(name="gas2", - # ... - transport="Mix", # use mixture-averaged formulation - # ... - ) +[#Kee2017]_). The second is a model that uses the mixture-averaged rule. Stoichiometric Solid -------------------- -A :cti:class:`stoichiometric_solid` is one that is modeled as having a precise, fixed composition, +A **stoichiometric solid** is one that is modeled as having a precise, fixed composition, given by the composition of the one species present. A stoichiometric solid can be used to define a condensed phase that can participate in heterogeneous reactions. (Of course, there cannot be homogeneous reactions, since the composition is fixed.) -.. code:: python - - stoichiometric_solid(name='graphite', - elements='C', - species='C(gr)', - density=(2.2, 'g/cm3'), - initial_state=state(temperature=300.0, - pressure=(1.0, 'atm'))) - -In the example above, the definition of the species ``'C(gr)'`` must appear -elsewhere in the input file. +A stoichiometric solid can be defined in the CTI format using the +:cti:class:`stoichiometric_solid` entry. Stoichiometric Liquid --------------------- @@ -115,40 +74,7 @@ to the surface concentration :math:`C_k` by where :math:`n_k` is the number of sites covered or blocked by species :math:`k`. -The entry type for this interface model is :cti:class:`ideal_interface`. Additional interface -models may be added to allow non-ideal, coverage-dependent properties. - -Defining an interface is much like defining a phase. There are two new fields: -``phases`` and ``site_density``. The ``phases`` field specifies the bulk phases that -participate in the heterogeneous reactions. Although in most cases this string -will list one or two phases, no limit is placed on the number. This is -particularly useful in some electrochemical problems, where reactions take place -near the triple-phase boundary where a gas, an electrolyte, and a metal all meet. - -The ``site_density`` field is the number of adsorption sites per unit area. - -Another new aspect is in the embedded :cti:class:`state` entry in the -``initial_state`` field. When specifying the initial state of an interface, the -:cti:class:`state` entry has a field ``coverages``, which can be assigned a string -specifying the initial surface species coverages: - -.. code:: python - - ideal_interface(name='silicon_surface', - elements='Si H', - species='s* s-SiH3 s-H', - reactions='all', - phases='gas bulk-Si', - site_density=(1.0e15, 'molec/cm2'), - initial_state=state(temperature=1200.0, - coverages='s-H:1')) - -The State Entry -############### - -The initial state of either a phase or an interface may be set using an embedded -:cti:class:`state` entry. Note that only one of (``pressure``, ``density``) may be -specified, and only one of (``mole_fractions``, ``mass_fractions``, ``coverages``). +An interface can be defined in the CTI format using the :cti:class:`ideal_interface` entry. .. rubric:: References diff --git a/pages/science/reactions.rst b/pages/science/reactions.rst index 96831ca81..a67e01f5e 100644 --- a/pages/science/reactions.rst +++ b/pages/science/reactions.rst @@ -13,25 +13,30 @@ Here, we describe how Cantera calculates chemical reaction rates for various reaction types. -Reactions with a Pressure-Independent Rate ------------------------------------------- - -The :cti:class:`reaction` entry is used to represent homogeneous reactions with -pressure-independent rate coefficients and mass action kinetics. Examples of -reaction entries that implement some reactions in the GRI-Mech 3.0 natural gas -combustion mechanism [#Smith1997]_ are shown below: - -.. code:: python - - units(length = 'cm', quantity = 'mol', act_energy = 'cal/mol') - ... - reaction( "O + H2 <=> H + OH", [3.87000E+04, 2.7, 6260]) - reaction( "O + HO2 <=> OH + O2", [2.00000E+13, 0.0, 0]) - reaction( "O + H2O2 <=> OH + HO2", [9.63000E+06, 2.0, 4000]) - reaction( "O + HCCO <=> H + 2 CO", [1.00000E+14, 0.0, 0]) - reaction( "H + O2 + AR <=> HO2 + AR", kf=Arrhenius(A=7.00000E+17, b=-0.8, E=0)) - reaction( equation = "HO2 + C3H7 <=> O2 + C3H8", kf=Arrhenius(2.55000E+10, 0.255, -943)) - reaction( equation = "HO2 + C3H7 => OH + C2H5 + CH2O", kf=[2.41000E+13, 0.0, 0]) +Elementary Reactions +-------------------- + +The basic reaction type is a homogeneous reaction with a pressure-independent +rate coefficient and mass action kinetics, e.g. + +.. math:: + + \mathrm{A + B \rightleftharpoons C + D} + +with a forward rate constant defined as a modified Arrhenius function: + +.. math:: + + k_f = A T^b e^{-E_a / RT} + +and the forward reaction rate calculated as: + +.. math:: + + R_f = [\mathrm{A}] [\mathrm{B}] k_f + +An elementary reaction can be defined in the CTI format using the +:cti:class:`reaction` entry. Three-Body Reactions -------------------- @@ -70,30 +75,8 @@ where :math:`C_{\mathrm{k}}` is the concentration of species :math:`\mathrm{k}`. collision efficiency can be absorbed into the rate coefficient :math:`k_f(T)`, the default collision efficiency is 1.0. -A three-body reaction may be defined using the :cti:class:`three_body_reaction` -entry. The equation string for a three-body reaction must contain an ``'M'`` or -``'m'`` on both the reactant and product sides of the equation. The collision -efficiencies are specified as a string, with the species name followed by a -colon and the efficiency. - -Some examples from GRI-Mech 3.0 are shown below: - -.. code:: python - - three_body_reaction("2 O + M <=> O2 + M", [1.20000E+17, -1, 0], - "AR:0.83 C2H6:3 CH4:2 CO:1.75 CO2:3.6 H2:2.4 H2O:15.4 ") - - three_body_reaction("O + H + M <=> OH + M", [5.00000E+17, -1, 0], - efficiencies="AR:0.7 C2H6:3 CH4:2 CO:1.5 CO2:2 H2:2 H2O:6 ") - - three_body_reaction( - equation = "H + OH + M <=> H2O + M", - rate_coeff=[2.20000E+22, -2, 0], - efficiencies="AR:0.38 C2H6:3 CH4:2 H2:0.73 H2O:3.65 " - ) - -As always, the field names are optional *if* the field values are entered in the -declaration order. +A three-body reaction may be defined in the CTI format using the +:cti:class:`three_body_reaction` entry. Falloff Reactions ----------------- @@ -137,6 +120,9 @@ This expression is used to compute the rate coefficient for falloff reactions. The function :math:`F(T, P_r)` is the falloff function, and is specified by assigning an embedded entry to the ``falloff`` field. +A falloff reaction may be defined in the CTI format using the +:cti:class:`falloff_reaction` entry. + The Troe Falloff Function ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -155,9 +141,10 @@ al. [#Gilbert1983]_: N = 0.75 - 1.27\; \log_{10} F_{cent} -The :cti:class:`Troe` directive requires specifying the first three parameters -:math:`(A, T_3, T_1)`. The fourth parameter, :math:`T_2`, is optional; if -omitted, the last term of the falloff function is not used. +A Troe falloff function may be specified in the CTI format using the +:cti:class:`Troe` directive. The first three parameters, :math:`(A, T_3, T_1)`, +are required. The fourth parameter, :math:`T_2`, is optional; if omitted, the +last term of the falloff function is not used. .. _sec-sri-falloff: @@ -175,7 +162,10 @@ given by: F(T, P_r) = d \bigl[a \exp(-b/T) + \exp(-T/c)\bigr]^{1/(1+\log_{10}^2 P_r )} T^e In keeping with the nomenclature of Kee et al. [#Kee1989]_, we will refer to this as -the "SRI" falloff function. It is implemented by the :cti:class:`SRI` directive. +the "SRI" falloff function. + +An SRI falloff function may be specified in the CTI format using the +:cti:class:`SRI` directive. Chemically-Activated Reactions ------------------------------ @@ -203,26 +193,16 @@ to the *low pressure* rate constant: k_f(T, P_r) = k_0 \left(\frac{1}{1 + P_r}\right) F(T, P_r) and the optional blending function :math:`F` may described by any of the -parameterizations allowed for falloff reactions. Chemically-activated -reactions can be defined using the :cti:class:`chemically_activated_reaction` -directive. - -An example of a reaction specified with this parameterization: - -.. code:: python +parameterizations allowed for falloff reactions. - chemically_activated_reaction('CH3 + OH (+ M) <=> CH2O + H2 (+ M)', - kLow=[2.823201e+02, 1.46878, (-3270.56495, 'cal/mol')], - kHigh=[5.880000e-14, 6.721, (-3022.227, 'cal/mol')], - falloff=Troe(A=1.671, T3=434.782, T1=2934.21, T2=3919.0)) +Chemically-activated reactions can be defined in the CTI format using the +:cti:class:`chemically_activated_reaction` entry. -In this example, the units of :math:`k_0` (``kLow``) are m\ :sup:`3`\ /kmol/s and the -units of :math:`k_\infty` (``kHigh``) are 1/s. Pressure-Dependent Arrhenius Rate Expressions (P-Log) ----------------------------------------------------- -The :cti:class:`pdep_arrhenius` class represents pressure-dependent reaction rates +This parameterization represents pressure-dependent reaction rates by logarithmically interpolating between Arrhenius rate expressions at various pressures. Given two rate expressions at two specific pressures: @@ -244,26 +224,13 @@ rate used in the interpolation formula is the sum of all the rates given at that pressure. For pressures outside the given range, the rate expression at the nearest pressure is used. -An example of a reaction specified in this format: - -.. code:: python - - pdep_arrhenius('R1 + R2 <=> P1 + P2', - [(0.001315789, 'atm'), 2.440000e+10, 1.04, 3980.0], - [(0.039473684, 'atm'), 3.890000e+10, 0.989, 4114.0], - [(1.0, 'atm'), 3.460000e+12, 0.442, 5463.0], - [(10.0, 'atm'), 1.720000e+14, -0.01, 7134.0], - [(100.0, 'atm'), -7.410000e+30, -5.54, 12108.0], - [(100.0, 'atm'), 1.900000e+15, -0.29, 8306.0]) - -The first argument is the reaction equation. Each subsequent argument is a -sequence of four elements specifying a pressure and the Arrhenius parameters at -that pressure. +P-log reactions can be defined in the CTI format using the +:cti:class:`pdep_arrhenius` entry. Chebyshev Reaction Rate Expressions ----------------------------------- -Class :cti:class:`chebyshev_reaction` represents a phenomenological rate coefficient +Chebyshev rate expressions represents a phenomenological rate coefficient :math:`k(T,P)` in terms of a bivariate Chebyshev polynomial. The rate constant can be written as: @@ -289,25 +256,15 @@ are reduced temperatures and reduced pressures which map the ranges P_\mathrm{max})` to :math:`(-1, 1)`. A Chebyshev rate expression is specified in terms of the coefficient matrix -:math:`\alpha` and the temperature and pressure ranges. An example of a -Chebyshev rate expression where :math:`N_T = 6` and :math:`N_P = 4` is: - -.. code:: python - - chebyshev_reaction('R1 + R2 <=> P1 + P2', - Tmin=290.0, Tmax=3000.0, - Pmin=(0.001, 'atm'), Pmax=(100.0, 'atm'), - coeffs=[[-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]]) +:math:`\alpha` and the temperature and pressure ranges. Note that the Chebyshev polynomials are not defined outside the interval :math:`(-1,1)`, and therefore extrapolation of rates outside the range of temperatures and pressure for which they are defined is strongly discouraged. +Chebyshev reactions can be defined in the CTI format using the +:cti:class:`chebyshev_reaction` entry. + Surface Reactions ----------------- @@ -326,26 +283,13 @@ reaction of this type is: where :math:`A`, :math:`b`, and :math:`E_a` are the modified Arrhenius parameters and :math:`a_{\mathrm{k}}`, :math:`m_{\mathrm{k}}`, and :math:`E_{\mathrm{k}}` are the coverage -dependencies from species :math:`\mathrm{k}`. A reaction of this form with a single coverage -dependency (on the species ``H(S)``) can be written using class -:cti:class:`surface_reaction` with the ``coverage`` keyword argument supplied to the -class :cti:class:`Arrhenius`: - -.. code:: python - - surface_reaction("2 H(S) => H2 + 2 PT(S)", - Arrhenius(A, b, E_a, - coverage=['H(S)', a_1, m_1, E_1])) +dependencies from species :math:`\mathrm{k}`. -For a reaction with multiple coverage dependencies, the following syntax is -used: - -.. code:: python +Surface reactions can be defined in the CTI format using the +:cti:class:`surface_reaction` entry, with coverage information provided using +the ``coverage`` keyword argument supplied to the :cti:class:`Arrhenius` +directive. - surface_reaction("2 H(S) => H2 + 2 PT(S)", - Arrhenius(A, b, E_a, - coverage=[['H(S)', a_1, m_1, E_1], - ['PT(S)', a_2, m_2, E_2]])) Sticking Coefficients ~~~~~~~~~~~~~~~~~~~~~ @@ -373,11 +317,8 @@ where :math:`\Gamma_\mathrm{tot}` is the total molar site density, :math:`m` is the sum of all the surface reactant stoichiometric coefficients, and :math:`W` is the molecular weight of the gas phase species. -A reaction of this form can be written as: - -.. code:: python - - surface_reaction("H2O + PT(S) => H2O(S)", stick(a, b, c)) +.. TODO: Link to :cti:class:`stick` after 2.5.0 release adds that to the docs +Sticking reactions can be defined in the CTI format using the `stick` entry. Additional Options ------------------ @@ -400,13 +341,6 @@ the forward rate constant might be given as [#Westbrook1981]_: k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5} \exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right) -This reaction could be defined as: - -.. code:: python - - reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0], - order="C8H18:0.25 O2:1.5") - Special care is required in this case since the units of the pre-exponential factor depend on the sum of the reaction orders, which may not be an integer. @@ -414,22 +348,8 @@ Note that you can change reaction orders only for irreversible reactions. Normally, reaction orders are required to be positive. However, in some cases negative reaction orders are found to be better fits for experimental data. In -these cases, the default behavior may be overridden by adding -``negative_orders`` to the reaction options like the following: - -.. code:: python - - reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0], - order="C8H18:-0.25 O2:1.75", options=['negative_orders']) - -Some global reactions could have reactions orders for non-reactant species. One -should add ``nonreactant_orders`` to the reaction options to use this feature: - -.. code:: python +these cases, the default behavior may be overridden in the input file. - reaction("C8H18 + 12.5 O2 => 8 CO2 + 9 H2O", [4.6e11, 0.0, 30.0], - order="C8H18:-0.25 CO:0.15", - options=['negative_orders', 'nonreactant_orders']) .. rubric:: References diff --git a/pages/science/species.rst b/pages/science/species.rst index 8ea65f565..9c6d7b099 100644 --- a/pages/science/species.rst +++ b/pages/science/species.rst @@ -10,56 +10,46 @@ .. class:: lead - All :cti:class:`phase` entries in Cantera are made up of one or more :cti:class:`species` - entries, which in turn consist :cti:class:`element` entries. This section describes how - :cti:class:`element` entries and :cti:class:`species` entries are defined. + All phases in Cantera are made up of one or more species, which in turn + contain one or more elements. Elements ======== -The :cti:class:`element` entry defines an element or an isotope of an element. Note that these -entries are not often needed, since the the database file ``elements.xml`` is searched for element -definitions when importing phase and interface definitions. An explicit element entry is needed -only if an isotope not in ``elements.xml`` is required: +In Cantera, an **element** may refer to a chemical element or an isotope. Note +that definitions of elements are not often needed, since Cantera has definitions +for the standard chemical elements. Explicit element definitions are usually +only needed for isotopes. -.. code:: python +An element can be defined in the CTI format using the :cti:class:`element` entry. - element(symbol='C-13', - atomic_mass=13.003354826) - element("O-18", 17.9991603) Species ======= -For each species, a :cti:class:`species` entry is required. Species are defined at -the top-level of the input file—their definitions are not embedded in a phase -or interface entry. +For each species, a species definition is required. + +A species can be defined in the CTI format using the :cti:class:`species` entry. + Species Name ------------ -The name field may contain embedded parentheses, ``+`` or ``-`` signs to -indicate the charge, or just about anything else that is printable and not a -reserved character in XML. Some example name specifications: +The name of a species may contain embedded parentheses, ``+`` or ``-`` signs to +indicate the charge, or just about anything else that is a printable character. +Some example name specifications: -.. code:: python +.. code:: - name = 'CH4' - name = 'methane' - name = 'argon_2+' - name = 'CH2(singlet)' + CH4 + methane + argon_2+ + CH2(singlet) Elemental Composition --------------------- -The elemental composition is specified in the atoms entry, as follows: - -.. code:: python - - atoms = "C:1, O:2" # CO2 with optional comma - atoms = "Y:1 Ba:2 Cu:3 O:6.5" # stoichiometric YBCO - atoms = "" # a surface species representing an empty site - atoms = "Ar:1 E:-2" # Ar++ +The elemental composition of each species must be specified. For gaseous species, the elemental composition is well-defined, since the species represent distinct molecules. For species in solid or liquid solutions, @@ -67,20 +57,10 @@ 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 to omit the ``atoms`` field entirely, in +For surface species, it is possible to omit the elemental composition, in which case it 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: - -.. code:: python - - species(name = 'ysz-oxygen-vacancy', - atoms = 'O:0, E:2', - # ..., - ) - -Note that an atom number of zero may be given if desired, but is completely -equivalent to omitting that element. +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. @@ -88,12 +68,12 @@ The number of atoms of an element must be non-negative, except for the special Thermodynamic Properties ------------------------ -The :cti:class:`phase` and :cti:class:`ideal_interface` entries discussed in the last -chapter implement specific models for the thermodynamic properties appropriate -for the type of phase or interface they represent. Although each one may use -different expressions to compute the properties, they all require thermodynamic -property information for the individual species. For the phase types implemented -at present, the properties needed are: +The phase models discussed in the last chapter implement specific models for the +thermodynamic properties appropriate for the type of phase or interface they +represent. Although each one may use different expressions to compute the +properties, they all require thermodynamic property information for the +individual species. For the phase types implemented at present, the properties +needed are: 1. the molar heat capacity at constant pressure :math:`\hat{c}^0_p(T)` for a range of temperatures and a reference pressure :math:`P_0`; @@ -107,26 +87,19 @@ Species Transport Coefficients ------------------------------ Transport property models in general require coefficients that express the -effect of each species on the transport properties of the phase. The -``transport`` field may be assigned an embedded entry that provides -species-specific coefficients. - -Currently, the only entry type is :cti:class:`gas_transport`, which supplies -parameters needed by the ideal-gas transport property models. The field values -and their units of the :cti:class:`gas_transport` entry are compatible with the -transport database parameters described by Kee et al. [#Kee1986]_. Entries in -transport databases in the format described in their report can be used directly -in the fields of the :cti:class:`gas_transport` entry, without requiring any unit -conversion. The numeric field values should all be entered as pure numbers, with -no attached units string. +effect of each species on the transport properties of the phase. Currently, +ideal-gas transport property models are implemented. + +Transport properties can be defined in the CTI format using the +:cti:class:`gas_transport` entry. .. _sec-thermo-models: Thermodynamic Property Models ============================= -The entry types described in this section can be used to provide data for the -``thermo`` field of a :cti:class:`species`. Each implements a different +The models described in this section can be used to provide thermodynamic data +for each species in a phase. Each model implements a different *parameterization* (functional form) for the heat capacity. Note that there is no requirement that all species in a phase use the same parameterization; each species can use the one most appropriate to represent how the heat capacity @@ -162,23 +135,9 @@ temperature regions. It is not compatible with the form used in the most recent version of the NASA equilibrium program, which uses 9 coefficients for each temperature region. -A NASA parameterization is defined by an embedded :cti:class:`NASA` entry. Very -often, two NASA parameterizations are used for two contiguous temperature -ranges. This can be specified by assigning the ``thermo`` field of the -``species`` entry a sequence of two :cti:class:`NASA` entries: - -.. code:: python +A NASA-7 parameterization can be defined in the CTI format using the +:cti:class:`NASA` entry. - # use one NASA parameterization for T < 1000 K, and another for T > 1000 K. - species(name = "O2", - atoms = " O:2 ", - thermo = ( - NASA( [ 200.00, 1000.00], [ 3.782456360E+00, -2.996734160E-03, - 9.847302010E-06, -9.681295090E-09, 3.243728370E-12, - -1.063943560E+03, 3.657675730E+00] ), - NASA( [ 1000.00, 3500.00], [ 3.282537840E+00, 1.483087540E-03, - -7.579666690E-07, 2.094705550E-10, -2.167177940E-14, - -1.088457720E+03, 5.453231290E+00] ) ) ) The NASA 9-Coefficient Polynomial Parameterization -------------------------------------------------- @@ -203,87 +162,8 @@ the following equations: \frac{s^0(T)}{R} = - \frac{a_0}{2} T^{-2} - a_1 T^{-1} + a_2 \ln T + a_3 T + \frac{a_4}{2} T^2 + \frac{a_5}{3} T^3 + \frac{a_6}{4} T^4 + a_8 -The following is an example of a species defined using the :cti:class:`NASA9` -parameterization in three different temperature regions: - -.. code:: python - - species(name=u'CO2', - atoms='C:1 O:2', - thermo=(NASA9([200.00, 1000.00], - [ 4.943650540E+04, -6.264116010E+02, 5.301725240E+00, - 2.503813816E-03, -2.127308728E-07, -7.689988780E-10, - 2.849677801E-13, -4.528198460E+04, -7.048279440E+00]), - NASA9([1000.00, 6000.00], - [ 1.176962419E+05, -1.788791477E+03, 8.291523190E+00, - -9.223156780E-05, 4.863676880E-09, -1.891053312E-12, - 6.330036590E-16, -3.908350590E+04, -2.652669281E+01]), - NASA9([6000.00, 20000.00], - [-1.544423287E+09, 1.016847056E+06, -2.561405230E+02, - 3.369401080E-02, -2.181184337E-06, 6.991420840E-11, - -8.842351500E-16, -8.043214510E+06, 2.254177493E+03])), - note='Gurvich,1991 pt1 p27 pt2 p24. [g 9/99]') - -Thermodynamic data for a range of species can be obtained from the -`NASA ThermoBuild `__ tool. Using the web -interface, an input file can be obtained for a set of species. This input file -should then be modified so that the first line reads "`thermo nasa9`", as in the -following example: - -.. code:: - - thermo nasa9 - 200.000 1000.000 6000.000 20000.000 9/09/04 - CO Gurvich,1979 pt1 p25 pt2 p29. - 3 tpis79 C 1.00O 1.00 0.00 0.00 0.00 0 28.0101000 -110535.196 - 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 1.489045326D+04-2.922285939D+02 5.724527170D+00-8.176235030D-03 1.456903469D-05 - -1.087746302D-08 3.027941827D-12 -1.303131878D+04-7.859241350D+00 - 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 4.619197250D+05-1.944704863D+03 5.916714180D+00-5.664282830D-04 1.398814540D-07 - -1.787680361D-11 9.620935570D-16 -2.466261084D+03-1.387413108D+01 - 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 - 8.868662960D+08-7.500377840D+05 2.495474979D+02-3.956351100D-02 3.297772080D-06 - -1.318409933D-10 1.998937948D-15 5.701421130D+06-2.060704786D+03 - CO2 Gurvich,1991 pt1 p27 pt2 p24. - 3 g 9/99 C 1.00O 2.00 0.00 0.00 0.00 0 44.0095000 -393510.000 - 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - 4.943650540D+04-6.264116010D+02 5.301725240D+00 2.503813816D-03-2.127308728D-07 - -7.689988780D-10 2.849677801D-13 -4.528198460D+04-7.048279440D+00 - 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - 1.176962419D+05-1.788791477D+03 8.291523190D+00-9.223156780D-05 4.863676880D-09 - -1.891053312D-12 6.330036590D-16 -3.908350590D+04-2.652669281D+01 - 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 - -1.544423287D+09 1.016847056D+06-2.561405230D+02 3.369401080D-02-2.181184337D-06 - 6.991420840D-11-8.842351500D-16 -8.043214510D+06 2.254177493D+03 - END PRODUCTS - END REACTANTS - -This file (saved for example as ``nasathermo.dat``) can then be converted to the -CTI format using the ``ck2cti`` script: - -.. code:: bash - - ck2cti --thermo=nasathermo.dat - -To generate a full phase definition, create an input file defining the phase as -well, saved for example as ``nasa.inp``: - -.. code:: - - elements - C O - end - - species - CO CO2 - end - -The two input files can then be converted together by calling: - -.. code:: bash - - ck2cti --input=nasa.inp --thermo=nasathermo.dat +A NASA-9 parameterization can be defined in the CTI format using the +:cti:class:`NASA9` entry. The Shomate Parameterization @@ -307,25 +187,16 @@ properties in the `NIST Chemistry WebBook `__ coefficients :math:`A` through :math:`G` should be entered precisely as shown there, with no units attached. Unit conversions to SI will be handled internally. -Example usage of the :cti:class:`Shomate` directive: - -.. code:: python - - # use a single Shomate parameterization. - species(name = "O2", - atoms = " O:2 ", - thermo = Shomate( [298.0, 6000.0], - [29.659, 6.137261, -1.186521, 0.09578, -0.219663, - -9.861391, 237.948] ) ) +A Shomate parameterization can be defined in the CTI format using the +:cti:class:`Shomate` entry. Constant Heat Capacity ---------------------- In some cases, species properties may only be required at a single temperature or over a narrow temperature range. In such cases, the heat capacity can be -approximated as constant, and simpler expressions can be used for the thermodynamic -properties. The :cti:class:`const_cp` parameterization computes the properties as -follows: +approximated as constant, and simple expressions can be used for the +thermodynamic properties: .. math:: @@ -339,21 +210,9 @@ The parameterization uses four constants: :math:`T_0, \hat{c}_p^0(T_0), \hat{h}^0(T_0), \hat{s}^0(T)`. The default value of :math:`T_0` is 298.15 K; the default value for the other parameters is 0.0. -Example: - -.. code:: python - - thermo = const_cp(h0=(-393.51, 'kJ/mol'), - s0=(213.785, 'J/mol/K'), - cp0=(37.12, 'J/mol/K')) - -Assuming that the :cti:func:`units` function has been used to set the default energy -units to Joules and the default quantity unit to kmol, this may be equivalently -written as: - -.. code:: python +A constant heat capacity parameterization can be defined in the CTI format +using the :cti:class:`const_cp` entry. - thermo = const_cp(h0=-3.9351e8, s0=2.13785e5, cp0=3.712e4) .. rubric:: References diff --git a/pages/tutorials/cti/reactions.rst b/pages/tutorials/cti/reactions.rst index d33187501..eba29284e 100644 --- a/pages/tutorials/cti/reactions.rst +++ b/pages/tutorials/cti/reactions.rst @@ -206,6 +206,81 @@ should add ``nonreactant_orders`` to the reaction options to use this feature: order="C8H18:-0.25 CO:0.15", options=['negative_orders', 'nonreactant_orders']) +Three-body reactions +==================== + +A three-body reaction may be defined using the :cti:class:`three_body_reaction` +entry. The equation string for a three-body reaction must contain an ``'M'`` or +``'m'`` on both the reactant and product sides of the equation. The collision +efficiencies are specified as a string, with the species name followed by a +colon and the efficiency. + +.. code:: python + + three_body_reaction("2 O + M <=> O2 + M", [1.20000E+17, -1, 0], + "AR:0.83 C2H6:3 CH4:2 CO:1.75 CO2:3.6 H2:2.4 H2O:15.4 ") + + three_body_reaction("O + H + M <=> OH + M", [5.00000E+17, -1, 0], + efficiencies="AR:0.7 C2H6:3 CH4:2 CO:1.5 CO2:2 H2:2 H2O:6 ") + + three_body_reaction( + equation = "H + OH + M <=> H2O + M", + rate_coeff=[2.20000E+22, -2, 0], + efficiencies="AR:0.38 C2H6:3 CH4:2 H2:0.73 H2O:3.65 " + ) + + +Other Examples +============== + +.. code:: python + + units(length = 'cm', quantity = 'mol', act_energy = 'cal/mol') + ... + reaction( "O + H2 <=> H + OH", [3.87000E+04, 2.7, 6260]) + reaction( "O + HO2 <=> OH + O2", [2.00000E+13, 0.0, 0]) + reaction( "O + H2O2 <=> OH + HO2", [9.63000E+06, 2.0, 4000]) + reaction( "O + HCCO <=> H + 2 CO", [1.00000E+14, 0.0, 0]) + reaction( "H + O2 + AR <=> HO2 + AR", kf=Arrhenius(A=7.00000E+17, b=-0.8, E=0)) + reaction( equation = "HO2 + C3H7 <=> O2 + C3H8", kf=Arrhenius(2.55000E+10, 0.255, -943)) + reaction( equation = "HO2 + C3H7 => OH + C2H5 + CH2O", kf=[2.41000E+13, 0.0, 0]) + + + chemically_activated_reaction('CH3 + OH (+ M) <=> CH2O + H2 (+ M)', + kLow=[2.823201e+02, 1.46878, (-3270.56495, 'cal/mol')], + kHigh=[5.880000e-14, 6.721, (-3022.227, 'cal/mol')], + falloff=Troe(A=1.671, T3=434.782, T1=2934.21, T2=3919.0)) + + pdep_arrhenius('R1 + R2 <=> P1 + P2', + [(0.001315789, 'atm'), 2.440000e+10, 1.04, 3980.0], + [(0.039473684, 'atm'), 3.890000e+10, 0.989, 4114.0], + [(1.0, 'atm'), 3.460000e+12, 0.442, 5463.0], + [(10.0, 'atm'), 1.720000e+14, -0.01, 7134.0], + [(100.0, 'atm'), -7.410000e+30, -5.54, 12108.0], + [(100.0, 'atm'), 1.900000e+15, -0.29, 8306.0]) + + chebyshev_reaction('R1 + R2 <=> P1 + P2', + Tmin=290.0, Tmax=3000.0, + Pmin=(0.001, 'atm'), Pmax=(100.0, 'atm'), + coeffs=[[-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]]) + + surface_reaction("2 H(S) => H2 + 2 PT(S)", + Arrhenius(A, b, E_a, + coverage=['H(S)', a_1, m_1, E_1])) + + surface_reaction("2 H(S) => H2 + 2 PT(S)", + Arrhenius(A, b, E_a, + coverage=[['H(S)', a_1, m_1, E_1], + ['PT(S)', a_2, m_2, E_2]])) + + surface_reaction("H2O + PT(S) => H2O(S)", stick(a, b, c)) + + .. container:: container .. container:: row diff --git a/pages/tutorials/cti/species.rst b/pages/tutorials/cti/species.rst index 60ae9351c..f5e872f29 100644 --- a/pages/tutorials/cti/species.rst +++ b/pages/tutorials/cti/species.rst @@ -102,6 +102,132 @@ implemented at present, the properties needed are: See: :ref:`sec-thermo-models` for a listing of the available species thermodynamic models available in Cantera. +7-Coefficient NASA Polynomials +------------------------------ + +A NASA parameterization is defined by an embedded :cti:class:`NASA` entry. Very +often, two NASA parameterizations are used for two contiguous temperature +ranges. This can be specified by assigning the ``thermo`` field of the +``species`` entry a sequence of two :cti:class:`NASA` entries: + +.. code:: python + + # use one NASA parameterization for T < 1000 K, and another for T > 1000 K. + species(name = "O2", + atoms = " O:2 ", + thermo = ( + NASA( [ 200.00, 1000.00], [ 3.782456360E+00, -2.996734160E-03, + 9.847302010E-06, -9.681295090E-09, 3.243728370E-12, + -1.063943560E+03, 3.657675730E+00] ), + NASA( [ 1000.00, 3500.00], [ 3.282537840E+00, 1.483087540E-03, + -7.579666690E-07, 2.094705550E-10, -2.167177940E-14, + -1.088457720E+03, 5.453231290E+00] ) ) ) + +9-Coefficient NASA polynomials +------------------------------ + +The following is an example of a species defined using the :cti:class:`NASA9` +parameterization in three different temperature regions: + +.. code:: python + + species(name=u'CO2', + atoms='C:1 O:2', + thermo=(NASA9([200.00, 1000.00], + [ 4.943650540E+04, -6.264116010E+02, 5.301725240E+00, + 2.503813816E-03, -2.127308728E-07, -7.689988780E-10, + 2.849677801E-13, -4.528198460E+04, -7.048279440E+00]), + NASA9([1000.00, 6000.00], + [ 1.176962419E+05, -1.788791477E+03, 8.291523190E+00, + -9.223156780E-05, 4.863676880E-09, -1.891053312E-12, + 6.330036590E-16, -3.908350590E+04, -2.652669281E+01]), + NASA9([6000.00, 20000.00], + [-1.544423287E+09, 1.016847056E+06, -2.561405230E+02, + 3.369401080E-02, -2.181184337E-06, 6.991420840E-11, + -8.842351500E-16, -8.043214510E+06, 2.254177493E+03])), + note='Gurvich,1991 pt1 p27 pt2 p24. [g 9/99]') + +Thermodynamic data for a range of species can be obtained from the +`NASA ThermoBuild `__ tool. Using the web +interface, an input file can be obtained for a set of species. This input file +should then be modified so that the first line reads "`thermo nasa9`", as in the +following example: + +.. code:: + + thermo nasa9 + 200.000 1000.000 6000.000 20000.000 9/09/04 + CO Gurvich,1979 pt1 p25 pt2 p29. + 3 tpis79 C 1.00O 1.00 0.00 0.00 0.00 0 28.0101000 -110535.196 + 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 + 1.489045326D+04-2.922285939D+02 5.724527170D+00-8.176235030D-03 1.456903469D-05 + -1.087746302D-08 3.027941827D-12 -1.303131878D+04-7.859241350D+00 + 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 + 4.619197250D+05-1.944704863D+03 5.916714180D+00-5.664282830D-04 1.398814540D-07 + -1.787680361D-11 9.620935570D-16 -2.466261084D+03-1.387413108D+01 + 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 8671.104 + 8.868662960D+08-7.500377840D+05 2.495474979D+02-3.956351100D-02 3.297772080D-06 + -1.318409933D-10 1.998937948D-15 5.701421130D+06-2.060704786D+03 + CO2 Gurvich,1991 pt1 p27 pt2 p24. + 3 g 9/99 C 1.00O 2.00 0.00 0.00 0.00 0 44.0095000 -393510.000 + 200.000 1000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 + 4.943650540D+04-6.264116010D+02 5.301725240D+00 2.503813816D-03-2.127308728D-07 + -7.689988780D-10 2.849677801D-13 -4.528198460D+04-7.048279440D+00 + 1000.000 6000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 + 1.176962419D+05-1.788791477D+03 8.291523190D+00-9.223156780D-05 4.863676880D-09 + -1.891053312D-12 6.330036590D-16 -3.908350590D+04-2.652669281D+01 + 6000.000 20000.0007 -2.0 -1.0 0.0 1.0 2.0 3.0 4.0 0.0 9365.469 + -1.544423287D+09 1.016847056D+06-2.561405230D+02 3.369401080D-02-2.181184337D-06 + 6.991420840D-11-8.842351500D-16 -8.043214510D+06 2.254177493D+03 + END PRODUCTS + END REACTANTS + +This file (saved for example as ``nasathermo.dat``) can then be converted to the +CTI format using the ``ck2cti`` script: + +.. code:: bash + + ck2cti --thermo=nasathermo.dat + +To generate a full phase definition, create an input file defining the phase as +well, saved for example as ``nasa.inp``: + +.. code:: + + elements + C O + end + + species + CO CO2 + end + +The two input files can then be converted together by calling: + +.. code:: bash + + ck2cti --input=nasa.inp --thermo=nasathermo.dat + +Constant Heat Capacity +---------------------- + +Example: + +.. code:: python + + thermo = const_cp(h0=(-393.51, 'kJ/mol'), + s0=(213.785, 'J/mol/K'), + cp0=(37.12, 'J/mol/K')) + +Assuming that the :cti:func:`units` function has been used to set the default energy +units to Joules and the default quantity unit to kmol, this may be equivalently +written as: + +.. code:: python + + thermo = const_cp(h0=-3.9351e8, s0=2.13785e5, cp0=3.712e4) + + Species Transport Coefficients ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 707ab504874afbbcac541a6938e5948fe6ec529a Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 28 Jun 2019 23:34:28 -0400 Subject: [PATCH 04/45] Add skeleton for YAML version of "Defining Phases" --- pages/tutorials/input-files.rst | 83 ++++++++++---- pages/tutorials/yaml/defining-phases.rst | 134 +++++++++++++++++++++++ pages/tutorials/yaml/phases.rst | 75 +++++++++++++ pages/tutorials/yaml/reactions.rst | 78 +++++++++++++ pages/tutorials/yaml/species.rst | 62 +++++++++++ pages/tutorials/yaml/yaml-format.rst | 68 ++++++++++++ 6 files changed, 479 insertions(+), 21 deletions(-) create mode 100644 pages/tutorials/yaml/defining-phases.rst create mode 100644 pages/tutorials/yaml/phases.rst create mode 100644 pages/tutorials/yaml/reactions.rst create mode 100644 pages/tutorials/yaml/species.rst create mode 100644 pages/tutorials/yaml/yaml-format.rst diff --git a/pages/tutorials/input-files.rst b/pages/tutorials/input-files.rst index 7e9d31a45..7faa64623 100644 --- a/pages/tutorials/input-files.rst +++ b/pages/tutorials/input-files.rst @@ -14,24 +14,26 @@ `), all calculations in Cantera require an input file to describe the properties of the relevant phase(s) of matter. -The required input files can be provided via one of three methods: +The required input files can be provided via one of several methods: - Use one of the pre-existing input files provided with Cantera - Convert a pre-existing mechanism from Chemkin (CK) format to Cantera (CTI) format - Create your own CTI file, either from scratch (not recommended) or by editing an existing file +- Create your own YAML file from scratch or by editing an existing file *(New in + Cantera 2.5)* The first two options will suffice for a majority of Cantera users. Advanced -users may, however, need to edit an existing CTI file in order to define +users may, however, need to edit an existing input file in order to define additional species, reactions, or entirely new phases. Even if you need to -create an entirely new CTI file, it is still advisable to start from an existing +create an entirely new input file, it is still advisable to start from an existing file, to cut down on syntax errors. -Whenever you edit a CTI file, it is *highly advised* that you begin by copying the existing file and +Whenever you edit a Cantera input file, it is *highly advised* that you begin by copying the existing file and saving it under a new name, before editing the new file. Editing a file under its original name can easily lead to errors, if one forgets that this file does not represent the original mechanism. -CTI files distributed with Cantera -================================== +Input files distributed with Cantera +==================================== Several reaction mechanism files in the CTI format are included in the Cantera distribution, including ones that model natural gas combustion (``gri30.cti``), high-temperature air @@ -40,19 +42,20 @@ liquid-vapor region (``liquidvapor.cti``), and a few surface reaction mechanisms ``ptcombust.cti``, ``diamond.cti``, etc.), among others. Under Windows, these files may be located in ``C:\Program Files\Cantera\data`` depending on how you installed Cantera and the options you specified. On a Unix/Linux/macOS machine, they are usually kept in the ``data`` subdirectory -within the Cantera installation directory. +within the Cantera installation directory. Starting with Cantera 2.5, corresponding +versions of these input files in the YAML format are also installed. Please see the tutorials for :doc:`Python ` and :doc:`Matlab ` for instructions on how to import from these pre-existing files. -Converting or Creating New CTI Files -==================================== +Converting or Creating New Input Files +====================================== -If you want to model a phase not available in the CTI files distributed with Cantera, you will need -to either procure a new CTI file (there are a limited number of CTI files available on the web), or +If you want to model a phase not available in the input files distributed with Cantera, you will need +to either procure a new input file (there are a limited number of input files available on the web), or create a new one. -There are two primary options for creating a new CTI file: +There are three primary options for creating a new Cantera input file: .. container:: container @@ -73,14 +76,14 @@ There are two primary options for creating a new CTI file: .. container:: card-text - Convert a Chemkin-formatted ('CK') file to the CTI input format. + Convert a Chemkin-formatted ('CK') file to the Cantera input format. .. container:: card .. container:: :tagname: a :attributes: href="cti/defining-phases.html" - title="Defining Phases" + title="Defining Phases in CTI" .. container:: card-header section-card @@ -90,15 +93,35 @@ There are two primary options for creating a new CTI file: .. container:: card-text - Create a completely new mechanism, by defining new species, phases, and/or reactions. + Create a completely new mechanism, by defining new species, + phases, and/or reactions, using the CTI format. + + .. container:: card + + .. container:: + :tagname: a + :attributes: href="yaml/defining-phases.html" + title="Defining Phases in YAML" + + .. container:: card-header section-card + + Create a new YAML file + + .. container:: card-body + + .. container:: card-text + + Create a completely new mechanism, by defining new species, + phases, and/or reactions, using the YAML format. + *(New in Cantera 2.5)* -Understanding CTI Syntax -======================== +Understanding Input File Syntax +=============================== -For any of these options (adapting an external CTI file, converting from CK, or creating a new CTI -file), it can be helpful to understand the CTI syntax requirements. Clearly, anyone writing directly -in the CTI format must conform to these standards. However, even when importing an -externally-provided CTI file or converting from CK format, understanding the CTI file syntax can +For any of these options (adapting an existing Cantera input file, converting from CK, or creating a new input +file), it can be helpful to understand the input file syntax requirements. Clearly, anyone writing directly +in the CTI or YAML formats must conform to these standards. However, even when importing an +externally-provided file or converting from CK format, understanding the input file syntax can help diagnose and correct any errors (although many/most of the CK conversion errors will be related to errors in the CK syntax formatting). @@ -120,3 +143,21 @@ to errors in the CK syntax formatting). .. container:: card-text This tutorial covers the details of the CTI format and its syntax + + .. container:: card + + .. container:: + :tagname: a + :attributes: href="yaml/yaml-format.html" + title="YAML Format Tutorial" + + .. container:: card-header section-card + + YAML Format Tutorial + + .. container:: card-body + + .. container:: card-text + + This tutorial covers the details of the YAML format and its syntax. + *(New in Cantera 2.5)* diff --git a/pages/tutorials/yaml/defining-phases.rst b/pages/tutorials/yaml/defining-phases.rst new file mode 100644 index 000000000..55d07c7f2 --- /dev/null +++ b/pages/tutorials/yaml/defining-phases.rst @@ -0,0 +1,134 @@ +.. slug: defining-phases +.. title: Defining Phases + +.. jumbotron:: + + .. raw:: html + +

Defining Phases

+ + .. class:: lead + + A guide to Cantera's YAML input file format + +Virtually every Cantera simulation involves one or more phases of matter. +Depending on the calculation being performed, it may be necessary to evaluate +thermodynamic properties, transport properties, and/or reaction rates for the +phase(s) present. Before the properties can be evaluated, each phase must be +defined, meaning that the models to use to compute its properties and reaction +rates must be specified, along with any parameters the models require. + +Because the amount of data required can be quite large, this data is imported +from a YAML file that can be read by the application, so that a given phase +model can be re-used for other simulations. + +This guide describes how to write such files to define phases and interfaces for +use in Cantera simulations. Each link below represents a standalone module - +while you certainly can read them in order, you can also jump to whichever +section addresses your current needs. If you need tips on troubleshooting the +YAML file syntax rules, please look at the :doc:`YAML Format Tutorial `. + +.. container:: card-deck + + .. container:: card + + .. container:: + :tagname: a + :attributes: href=phases.html + title="Phases and their Interfaces" + + .. container:: card-header section-card + + Phases and their Interfaces + + .. container:: card-body + + .. container:: card-text + + For each phase that appears in a problem, a corresponding entry + should be present in the input file(s). We'll start by describing + the entries for phases of various types, and then look at how to + define interfaces between phases. + + .. container:: card + + .. container:: + :tagname: a + :attributes: href=yaml-species.html + title="Elements and Species" + + .. container:: card-header section-card + + Elements and Species + + .. container:: card-body + + .. container:: card-text + + For each species declared as part of a phase description, both the + species and the elements that it is comprised of must be defined. + Here, we describe how both are defined. + + .. container:: card + + .. container:: + :tagname: a + :attributes: href=reactions.html + title="Reactions" + + .. container:: card-header section-card + + Reactions + + .. container:: card-body + + .. container:: card-text + + Cantera supports a number of different types of reactions, including + several types of homogeneous reactions, surface reactions, and + electrochemical reactions. For each, there is a corresponding entry + type. Here, we describe how to declare each type of reaction and + provide the necessary parameters to calculate the reaction rate for + each. + +Additional Information +====================== + +.. container:: card-deck + + .. container:: card + + .. container:: + :tagname: a + :attributes: href=yaml-format.html + title="YAML Format Tutorial" + + .. container:: card-header section-card + + YAML Format Tutorial + + .. container:: card-body + + .. container:: card-text + + This module gives an overview of the syntax and format of Cantera + YAML files + + .. container:: card + + .. container:: + :tagname: a + :attributes: href={{% ct_dev_docs sphinx/html/yaml/index.html %}} + title="YAML Format Reference" + + .. container:: card-header section-card + + YAML Format Reference + + .. container:: card-body + + .. container:: card-text + + The documentation of the YAML format, containing the specification + for each of the entry types discussed previously, for when you + require more detail. diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst new file mode 100644 index 000000000..e09ad8801 --- /dev/null +++ b/pages/tutorials/yaml/phases.rst @@ -0,0 +1,75 @@ +.. slug: phases +.. title: Phases and their Interfaces + +.. jumbotron:: + + .. raw:: html + +

Phases and their Interfaces

+ + .. class:: lead + + A description of how phases and interfaces are defined in YAML input files + +Phases +====== + +For each phase that appears in a problem, a corresponding entry should be +present in the input file(s). + +Phase Attributes +---------------- + +Phase Name +^^^^^^^^^^ + +Declaring the Elements +^^^^^^^^^^^^^^^^^^^^^^ + +Defining the Species +^^^^^^^^^^^^^^^^^^^^ + +Declaring the Reactions +^^^^^^^^^^^^^^^^^^^^^^^ + +The Kinetics Model +^^^^^^^^^^^^^^^^^^ + +The Transport Model +^^^^^^^^^^^^^^^^^^^ + +The Initial State +^^^^^^^^^^^^^^^^^ + +Interfaces +========== + +Now that we have seen how to define bulk, three-dimensional phases, we can +describe the procedure to define an interface between phases. Cantera presently +implements a simple model for an interface that treats it as a two-dimensional +ideal solution of interfacial species. + +.. _sec-phase-options: + +Special Processing Options +========================== + +.. container:: container + + .. container:: row + + .. container:: col-4 text-center offset-4 + + .. container:: btn btn-primary + :tagname: a + :attributes: href=defining-phases.html + + Return: Defining Phases + + .. container:: col-4 text-right + + .. container:: btn btn-primary + :tagname: a + :attributes: href=yaml-species.html + + Next: Elements and Species diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst new file mode 100644 index 000000000..74203fa77 --- /dev/null +++ b/pages/tutorials/yaml/reactions.rst @@ -0,0 +1,78 @@ +.. slug: reactions +.. title: Reactions +.. has_math: true + +.. jumbotron:: + + .. raw:: html + +

Reactions

+ + .. class:: lead + + A description of how reactions are defined in YAML input files + +Common Attributes +================= + +All of the entry types that define reactions share some common features. These +are described first, followed by descriptions of the individual reaction types +in the following sections. + +The Reaction Equation +~~~~~~~~~~~~~~~~~~~~~ + +The reaction equation determines the reactant and product stoichiometry. + +The ID String +------------- + +.. _sec-reaction-options: + +Options +------- + +Certain conditions are normally flagged as errors by Cantera. In some cases, +they may not be errors, and the options field can be used to specify how they +should be handled. + +Reaction Orders +--------------- + + +.. container:: container + + .. container:: row + + .. container:: col-4 text-left + + .. container:: btn btn-primary + :tagname: a + :attributes: href=yaml-species.html + title="Elements and Species" + + Previous: Elements and Species + + .. container:: col-4 text-center + + .. container:: btn btn-primary + :tagname: a + :attributes: href=defining-phases.html + title="Defining Phases" + + Return: Defining Phases + + .. container:: col-4 text-right + + .. container:: btn btn-primary + :tagname: a + :attributes: href=yaml-format.html + title="YAML Format Tutorial" + + Next: YAML Format Tutorial + +.. rubric:: References + +.. [#Westbrook1981] C. K. Westbrook and F. L. Dryer. Simplified reaction + mechanisms for the oxidation of hydrocarbon fuels in flames. *Combustion + Science and Technology* **27**, pp. 31--43. 1981. diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst new file mode 100644 index 000000000..5fa82f59c --- /dev/null +++ b/pages/tutorials/yaml/species.rst @@ -0,0 +1,62 @@ +.. slug: yaml-species +.. title: Elements and Species +.. has_math: true + +.. jumbotron:: + + .. raw:: html + +

Elements and Species

+ + .. class:: lead + + A description of how elements and species are defined in YAML input files + +Elements +======== + +Species +======= + +Species Name +~~~~~~~~~~~~ + +Elemental Composition +~~~~~~~~~~~~~~~~~~~~~ + +Thermodynamic Properties +~~~~~~~~~~~~~~~~~~~~~~~~ + +Species Transport Coefficients +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. container:: container + + .. container:: row + + .. container:: col-4 text-left + + .. container:: btn btn-primary + :tagname: a + :attributes: href=phases.html + title="Phases and Interfaces" + + Previous: Phases and Interfaces + + .. container:: col-4 text-center + + .. container:: btn btn-primary + :tagname: a + :attributes: href=defining-phases.html + title="Defining Phases" + + Return: Defining Phases + + .. container:: col-4 text-right + + .. container:: btn btn-primary + :tagname: a + :attributes: href=reactions.html + title=Reactions + + Next: Reactions diff --git a/pages/tutorials/yaml/yaml-format.rst b/pages/tutorials/yaml/yaml-format.rst new file mode 100644 index 000000000..4931f2b53 --- /dev/null +++ b/pages/tutorials/yaml/yaml-format.rst @@ -0,0 +1,68 @@ +.. slug: yaml-format +.. title: YAML File Structure + +.. jumbotron:: + + .. raw:: html + +

YAML Format Tutorial

+ + .. class:: lead + + Here we describe the syntax and structure of Cantera YAML files. + +Syntax +====== + +Comments +-------- + +Strings +------- + +Sequences +--------- + +Dimensional Values +================== + +Error Handling +============== + +Syntax Errors +------------- + +Cantera Errors +-------------- + + +.. container:: container + + .. container:: row + + .. container:: col-4 text-left + + .. container:: btn btn-primary + :tagname: a + :attributes: href=reactions.html + title="Reactions" + + Previous: Reactions + + .. container:: col-4 text-center + + .. container:: btn btn-primary + :tagname: a + :attributes: href=defining-phases.html + title="Defining Phases" + + Return: Defining Phases + + .. container:: col-4 text-right + + .. container:: btn btn-primary + :tagname: a + :attributes: href={{% ct_dev_docs sphinx/html/yaml/index.html %}} + title="YAML Format Reference" + + Next: YAML Format Reference From a08949ec50365f42585c733e7f505084f3ffcbe3 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 16 Sep 2019 16:58:09 -0400 Subject: [PATCH 05/45] Add rudimentary YAML syntax tutorial --- pages/tutorials/yaml/yaml-format.rst | 79 +++++++++++++++++++++++++++- 1 file changed, 77 insertions(+), 2 deletions(-) diff --git a/pages/tutorials/yaml/yaml-format.rst b/pages/tutorials/yaml/yaml-format.rst index 4931f2b53..6292d2df0 100644 --- a/pages/tutorials/yaml/yaml-format.rst +++ b/pages/tutorials/yaml/yaml-format.rst @@ -14,15 +14,90 @@ Syntax ====== -Comments --------- +Cantera YAML files use a subset of the `YAML 1.2 +`__ specification. Cantera YAML files +consist of individual values, which may be strings, numbers or booleans, that +are then composed as elements of nested mappings and sequences. Strings ------- +Strings may be generally written without qoutes, but may be enclosed in single +quotes or double quotes if needed in order to avoid certain parsing ambiguties. + +.. code:: yaml + + A string + Another 'string' + "A string: that requires quotes" + +Numbers +------- + +Numbers can be written as integers, decimal values, or using E-notation + +.. code:: yaml + + 3 + 3.14 + 6.022e23 + +Booleans +-------- + Sequences --------- +A sequence of multiple items is specified by separating the items by commas and +enclosing them in square brackets. The individual items can have +any type -- strings, integers, floating-point numbers (or even entries or other +lists). + +.. code:: yaml + + elements: [O, H, C, N, Ar] + temperature-ranges: [200.0, 1000.0, 3500.0] + +(block style, use of indentation) + +Mappings +-------- + +(flow style and block style) +(main yaml file is actually a mapping) +(cantera requires all mapping keys to be strings) +(nested mappings) + + + +Comments +-------- + +The character ``#`` is the comment character. Everything to the right of this +character on a line is ignored: + +.. code:: yaml + + # set the default units + units: + length: cm # use centimeters for length + quantity: mol # use moles for quantity + +Top-level entries +----------------- + +Entries have fields that can be assigned values. A species entry is shown below +that has fields ``name`` and ``composition``: + +.. code:: yaml + + - name: H2O + composition: {H: 2, O: 1} + +Most entries have some fields that are required; these must be assigned values, +or else processing of the file will abort and an error message will be +printed. Other fields may be optional, and take default values if not assigned. + Dimensional Values ================== From 8cf7f6dae69183db82559487739f2efd103c11e9 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Wed, 9 Oct 2019 16:55:54 -0400 Subject: [PATCH 06/45] Add documentation for YAML phase declarations --- pages/tutorials/yaml/phases.rst | 378 +++++++++++++++++++++++++++++-- pages/tutorials/yaml/species.rst | 2 + shortcodes/yaml_dev.tmpl | 1 + 3 files changed, 358 insertions(+), 23 deletions(-) create mode 100644 shortcodes/yaml_dev.tmpl diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index e09ad8801..87fecd02f 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -15,44 +15,376 @@ Phases ====== For each phase that appears in a problem, a corresponding entry should be -present in the input file(s). +present in the input file(s). The phase entry specifies the elements and species +present in the phases, and the models to be used for computing thermodynamic, +kinetic, and transport properties. -Phase Attributes + +Naming the Phase ---------------- -Phase Name -^^^^^^^^^^ +The ``name`` entry is a string that identifies the phase. It must be unique +within the file among all phase definitions of any type. Phases are referenced +by name when importing them. The ``name`` is also used to identify the phase +within multiphase mixtures or at phase boundaries. + + +Setting the Thermodynamic Model +------------------------------- + +The thermodynamic model used to represent a phase is specified in the ``thermo`` +field. Supported models are: + + - `binary-solution-tabulated <{{% yaml_dev phases binary-solution-tabulated %}}>`__ + - `compound-lattice <{{% yaml_dev phases compound-lattice %}}>`__ + - `constant-density <{{% yaml_dev phases constant-density %}}>`__ + - `Debye-Huckel <{{% yaml_dev phases debye-huckel %}}>`__ + - `edge <{{% yaml_dev phases edge %}}>`__ + - `fixed-chemical-potential <{{% yaml_dev phases fixed-chemical-potential %}}>`__ + - `fixed-stoichiometry <{{% yaml_dev phases fixed-stoichiometry %}}>`__ + - `HMW-electrolyte <{{% yaml_dev phases hmw-electrolyte %}}>`__ + - `ideal-gas <{{% yaml_dev phases ideal-gas %}}>`__ + - `ideal-gas-VPSS <{{% yaml_dev phases ideal-gas-vpss %}}>`__ + - `ideal-molal-solution <{{% yaml_dev phases ideal-molal-solution %}}>`__ + - `ideal-condensed <{{% yaml_dev phases ideal-condensed %}}>`__ + - `ideal-solution-VPSS <{{% yaml_dev phases ideal-solution-vpss %}}>`__ + - `ideal-surface <{{% yaml_dev phases ideal-surface %}}>`__ + - `ions-from-neutral-molecule <{{% yaml_dev phases ions-from-neutral-molecule %}}>`__ + - `lattice <{{% yaml_dev phases lattice %}}>`__ + - `liquid-water-IAPWS95 <{{% yaml_dev phases liquid-water-iapws95 %}}>`__ + - `Margules <{{% yaml_dev phases margules %}}>`__ + - `Maskell-solid-solution <{{% yaml_dev phases maskell-solid-solution %}}>`__ + - `electron-cloud <{{% yaml_dev phases electron-cloud %}}>`__ + - `pure-fluid <{{% yaml_dev phases pure-fluid %}}>`__ + - `Redlich-Kister <{{% yaml_dev phases redlich-kister %}}>`__ + - `Redlich-Kwong <{{% yaml_dev phases redlich-kwong %}}>`__ + +Some thermodynamic models use additional fields in the ``phase`` entry, which +are described in the linked documentation. + Declaring the Elements -^^^^^^^^^^^^^^^^^^^^^^ +---------------------- + +In most cases, it is not necessary to specify the elements present in a phase. +If no ``elements`` field is present, elements will be added automatically using +the definitions of the standard chemical elements based on the composition of +the species present in the phase. + +If non-standard elements such as isotopes need to be represented, or the +ordering of elements within the phase is important, the elements in the phase +may be declared in the optional ``elements`` entry. + +If all of the elements to be added are either standard chemical elements or +defined in the ``elements`` section of the current input file (see +:ref:`sec-yaml-elements`), the elements can be specified as a list of element +symbols, e.g.: + +.. code:: yaml + + elements: [H, C, O, Ar] + +To add elements from other top-level sections, from a different file, or from +multiple such sources, a list of single-key mappings can be used +where the key of each mapping specifies the source and the value is a list of +element names. The keys can be: + +- The name of a section within the current file. +- The name of an input file and a section in that file, separated by a slash, + e.g. ``myfile.yaml/my_elements``. If a relative path is specified, the + directory containing the current file is searched first, followed by the + Cantera data path. +- The name ``default`` to reference the standard chemical elements. + +Example: + +.. code:: yaml + + elements: + - default: [C, H, Ar] + - isotopes: [O18] + - myelements.yaml/uranium: [U235, U238] + +The order of the elements specified in the input file determines the order of +the elements in the phase when it is imported by Cantera. + + +Declaring the Species +--------------------- + +If the species present in the phase corresponds to those species defined in the +``species`` section of the input file, the ``species`` field may be omitted, and +those species will be added to the phase automatically. As a more explicit +alternative, the ``species`` field may be set to the string ``all``. + +To include specific species from the ``species`` section of the input file, the +``species`` entry can be a list of species names from that section, e.g.: + +.. code:: yaml + + species: [H2, O2, H2O] + +If species are defined in multiple input file sections, the ``species`` entry +can be a list of single-key mappings, where the key of each mapping specifies +the source and the value is either the string ``all`` or a list of species +names. Each key can be either the name of a section within the current input +file or the name of a different file and a section in that file, separated by a +slash. If a relative path is specified, the directory containing the current +file is searched first, followed by the Cantera data path. Example: + +.. code:: yaml + + species: + - species: [O2, N2] + - more_species: all + - subdir/myfile.yaml/species: [NO2, N2O] + +The order of species specified in the input file determines the order of the +species in the phase when it is imported by Cantera. + +Species containing elements that are not declared within the phase may be +skipped by setting the ``skip-undeclared-elements`` field to ``true``. For +example, to add all species from the ``species`` section that contain only +hydrogen or oxygen, the phase definition could contain: + +.. code:: yaml + + phases: + - name: hydrogen-and-oxygen + elements: [H, O] + species: all + skip-undeclared-elements: true + + +Setting the Kinetics Model +-------------------------- + +The kinetics model to be used, if any, is specified in the ``kinetics`` field. +Supported model strings are: + + - `gas <{{% ct_docs doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details %}}>`__ + - `surface <{{% ct_docs doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details %}}>`__ + - `edge <{{% ct_docs doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details %}}>`__ + +If omitted, no kinetics model will be used. -Defining the Species -^^^^^^^^^^^^^^^^^^^^ Declaring the Reactions -^^^^^^^^^^^^^^^^^^^^^^^ +----------------------- + +If a kinetics model has been specified, reactions may be added to the phase. By +default, all reactions from the ``reactions`` section of the input file will be +added. Equivalently, the ``reactions`` entry may be specified as the string +``all``. + +To disable automatic addition of reactions from the ``reactions`` section, the +``reactions`` entry may be set to ``none``. This may be useful if reactions will +be added programmatically after the phase is constructed. The ``reactions`` +field must be set to ``none`` if a kinetics model has been specified but there +is no ``reactions`` section in the input file. + +To include only those reactions from the ``reactions`` section where all of the +species involved are declared as being in the phase, the ``reactions`` entry +can be set to the string ``declared-species``. + +To include reactions from multiple sections or other files, the ``reactions`` +entry can be given as a list of section names, for example: + +.. code:: yaml + + reactions: + - OH_submechanism + - otherfile.yaml/C1-reactions + - otherfile.yaml/C2-reactions + +To include reactions from multiple sections or other files while only including +reactions involving declared species, a list of single-key mappings can be used, +where the key is the section name (or file and section name) and the value is +either the string ``all`` or the string ``declared-species``. For example: + +.. code:: yaml + + reactions: + - OH_submechanism: all + - otherfile.yaml/C1-reactions: all + - otherfile.yaml/C2-reactions: declared-species + +To permit reactions containing third-body efficiencies for species not present +in the phase, the additional field ``skip-undeclared-third-bodies`` may be added +to the phase entry with the value ``true``. + +Setting the Transport Model +--------------------------- + +To enable transport property calculation, the transport model to be used can be +specified in the ``transport`` field. Supported models are: + + - `high-pressure <{{% ct_docs doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details %}}>`__ + - `ionized-gas <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details %}}>`__ + - `mixture-averaged <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__ + - `mixture-averaged-CK <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__ + - `multicomponent <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__ + - `multicomponent-CK <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__ + - `unity-Lewis-number <{{% ct_docs doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details %}}>`__ + - `water <{{% ct_docs doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details %}}>`__ + + +Setting the Initial State +------------------------- + +The state of a phase can be set using two properties to set the thermodynamic +state, plus the composition. This state is specified as a mapping in the +``state`` field of ``phase`` entry. + +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`` + +Examples: + +.. code:: yaml + + state: + T: 300 K + P: 101325 Pa + X: {O2: 1.0, N2: 3.76} + + state: + density: 100 kg/m^3 + T: 298 + Y: + CH4: 0.2 + C3H8: 0.1 + CO2: 0.7 + + +Examples +-------- + +The following input file defines two equivalent gas phases including all +reactions and species defined in the input file, (with species and reaction data +elided). In the second case, the phase definition is simplified by having the +elements added based on the species definitions, taking the species definitions +from the default `species` section, and reactions from the default `reactions` +section. + +.. code:: yaml + + phases: + - name: gas1 + thermo: ideal-gas + elements: [O, H, N, Ar] + species: [H2, H, O, O2, OH, H2O, HO2, H2O2, N2, AR] + kinetics: gas + reactions: all + transport: mixture-averaged + state: + T: 300.0 + P: 1.01325e+05 + - name: gas2 + thermo: ideal-gas + kinetics: gas + transport: mixture-averaged + state: {T: 300.0, 1 atm} + + species: + - H2: ... + - H: ... + ... + - AR: ... + + reactions: + ... + +An input file defining an interface and its adjacent bulk phases, with full +species data elided: + +.. code:: yaml + + phases: + - name: graphite + thermo: lattice + species: + - graphite-species: all + state: {T: 300, P: 101325, X: {C6: 1.0, LiC6: 1e-5}} + density: 2.26 g/cm^3 -The Kinetics Model -^^^^^^^^^^^^^^^^^^ + - name: electrolyte + thermo: lattice + species: [{electrolyte-species: all}] + density: 1208.2 kg/m^3 + state: + T: 300 + P: 101325 + X: {Li+(e): 0.08, PF6-(e): 0.08, EC(e): 0.28, EMC(e): 0.56} -The Transport Model -^^^^^^^^^^^^^^^^^^^ + - name: anode-surface + thermo: ideal-surface + kinetics: surface + reactions: [graphite-anode-reactions] + species: [{anode-species: all}] + site-density: 1.0 mol/cm^2 + state: {T: 300, P: 101325} -The Initial State -^^^^^^^^^^^^^^^^^ + graphite-species: + - name: C6 + ... + - name: LiC6 + ... -Interfaces -========== + electrolyte-species: + - name: Li+(e) + ... + - name: PF6-(e) + ... + - name: EC(e) + ... + - name: EMC(e) + ... -Now that we have seen how to define bulk, three-dimensional phases, we can -describe the procedure to define an interface between phases. Cantera presently -implements a simple model for an interface that treats it as a two-dimensional -ideal solution of interfacial species. + anode-species: + - name: (int) + ... -.. _sec-phase-options: + graphite-anode-reactions: + - equation: LiC6 <=> Li+(e) + C6 + rate-constant: [5.74, 0.0, 0.0] + beta: 0.4 -Special Processing Options -========================== .. container:: container diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index 5fa82f59c..bc569c1de 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -12,6 +12,8 @@ A description of how elements and species are defined in YAML input files +.. _sec-yaml-elements: + Elements ======== diff --git a/shortcodes/yaml_dev.tmpl b/shortcodes/yaml_dev.tmpl new file mode 100644 index 000000000..89019a25b --- /dev/null +++ b/shortcodes/yaml_dev.tmpl @@ -0,0 +1 @@ +{{ '/' if site.config['BASE_URL'] == site.config['SITE_URL'] else site.config['BASE_URL'] }}documentation/dev/sphinx/html/yaml/{{ _args[0] }}.html{{'#'+_args[1] if _args|length == 2 else link }} From 2425aa6da7b45bbdbbf7e2ff21044f11da2a3431 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 10 Oct 2019 17:37:22 -0400 Subject: [PATCH 07/45] more succinct "state" docs --- pages/tutorials/yaml/phases.rst | 38 +++++++++------------------------ 1 file changed, 10 insertions(+), 28 deletions(-) diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index 87fecd02f..d74a89cbf 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -245,34 +245,16 @@ values. Where necessary, the values will be automatically normalized. - ``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`` +The thermodynamic state can be set in terms of two of the following properties, +with the valid property pairs deplending on the phase model: + +- ``temperature`` or ``T`` +- ``pressure`` or ``P`` +- ``enthalpy`` or ``H`` +- ``entropy`` or ``S`` +- ``int-energy``, ``internal-energy`` or ``U`` +- ``specific-volume`` or ``V`` +- ``density`` or ``D`` Examples: From 061b787be0fa4dc9a5586dd246e20b074d926ab0 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 10 Oct 2019 17:38:39 -0400 Subject: [PATCH 08/45] Add docs for YAML elements and species entries --- pages/tutorials/yaml/species.rst | 150 ++++++++++++++++++++++++++++++- 1 file changed, 146 insertions(+), 4 deletions(-) diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index bc569c1de..59623821b 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -17,20 +17,162 @@ Elements ======== +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 speciying the corresponding atomic symbols when specifying the +composition of species. + +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. + +An element entry has the following fields: + +- ``symbol``: The symbol to be used for the element, e.g. when specifying the + composition of a 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. + +An example ``elements`` section: + +.. code:: yaml + + elements: + - symbol: C13 + atomic-weight: 13.003354826 + atomic-number: 12 + - symbol: O-18 + atomic-weight: 17.9991603 + + Species ======= +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 ``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: + +.. code:: 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: + +.. code:: 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 -~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ + +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: + + - `NASA7 <{{% yaml_dev species sec-yaml-nasa7 %}}>`__ + - `NASA9 <{{% yaml_dev species nasa-9-coefficient-polynomials %}}>`__ + - `Shomate <{{% yaml_dev species shomate-polynomials %}}>`__ + - `constant-cp <{{% yaml_dev species constant-heat-capacity %}}>`__ + - `piecewise-Gibbs <{{% yaml_dev species piecewise-gibbs %}}>`__ + +The fields used by each model are described and examples provided in the linked +documentation. + +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: + + - `constant-volume <{{% yaml_dev species sec-yaml-eos-constant-volume %}}>`__ + - `density-temperature-polynomial <{{% yaml_dev species density-temperature-polynomial %}}>`__ + - `HKFT <{{% yaml_dev species hkft %}}>`__ + - `ideal-gas <{{% yaml_dev species sec-yaml-eos-ideal-gas %}}>`__ + - `ions-from-neutral-molecule <{{% yaml_dev species ions-from-neutral-molecule %}}>`__ + - `liquid-water-IAPWS95 <{{% yaml_dev species liquid-water-iapws95 %}}>`__ + - `molar-volume-temperature-polynomial <{{% yaml_dev species piecewise-gibbs %}}>`__ + - `Redlich-Kwong <{{% yaml_dev species redlich-kwong %}}>`__ + +The fields used by each model are described and examples provided in the linked +documentation. 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 only model type specifically handled is ``gas``. The parameters used +depend on the transport model specified at the phase level. The full set of +possible parameters is described in the `API documentation +<{{% yaml_dev species gas-transport %}}>`__. + +An example of a ``transport`` entry: + +.. code:: yaml + + transport: + model: gas + geometry: linear + well-depth: 107.4 + diameter: 3.458 + polarizability: 1.6 + rotational-relaxation: 3.8 + .. container:: container From 12db5934b2a01fc491d1709d8ce40869625cb13c Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 11 Oct 2019 06:20:08 -0400 Subject: [PATCH 09/45] Remove reference to never-implemented "skip" option for reactions --- pages/tutorials/cti/reactions.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/pages/tutorials/cti/reactions.rst b/pages/tutorials/cti/reactions.rst index eba29284e..13d6551f1 100644 --- a/pages/tutorials/cti/reactions.rst +++ b/pages/tutorials/cti/reactions.rst @@ -114,15 +114,6 @@ Certain conditions are normally flagged as errors by Cantera. In some cases, they may not be errors, and the options field can be used to specify how they should be handled. -``skip`` - The ``'skip'`` option can be used to temporarily remove this reaction from - the phase or interface that imports it, just as if the reaction entry were - commented out. The advantage of using skip instead of commenting it out is - that a warning message is printed each time a phase or interface definition - tries to import it. This serves as a reminder that this reaction is not - included, which can easily be forgotten when a reaction is "temporarily" - commented out of an input file. - ``duplicate`` Normally, when a reaction is imported into a phase, it is checked to see that it is not a duplicate of another reaction already present in the phase, From 3e86a5017d289d99c4ce55a1f5aa6c72a6e4256b Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 11:59:11 -0400 Subject: [PATCH 10/45] Make local copy of dev docs available --- README.md | 6 ++++-- api-docs/dev/.gitignore | 4 ++++ conf.py | 1 + 3 files changed, 9 insertions(+), 2 deletions(-) create mode 100644 api-docs/dev/.gitignore diff --git a/README.md b/README.md index dd4f0c8d7..eb1132f21 100644 --- a/README.md +++ b/README.md @@ -10,8 +10,10 @@ site is built using the [Nikola](https://getnikola.com) static site generator. 3. Clone the Cantera Jupyter examples: `git clone https://github.com/Cantera/cantera-jupyter.git` 4. Clone the Cantera website source: `git clone https://github.com/Cantera/cantera-website.git` 5. Enter the website repo: `cd cantera-website` -6. Inside the website repo, install the required packages: `pip install -r requirements.txt` -7. Build the website and open in browser: `nikola auto -b` +6. Copy the current development documentation: `curl -O https://cantera.org/documentation/dev/dev-docs.tar.bz2` +7. Extract the dev docs: `tar jxf dev-docs.tar.bz2 --strip-components=1 -C api-docs/dev` +8. Inside the website repo, install the required packages: `pip install -r requirements.txt` +9. Build the website and open in browser: `nikola auto -b` ## To add a language of examples diff --git a/api-docs/dev/.gitignore b/api-docs/dev/.gitignore new file mode 100644 index 000000000..5e7d2734c --- /dev/null +++ b/api-docs/dev/.gitignore @@ -0,0 +1,4 @@ +# Ignore everything in this directory +* +# Except this file +!.gitignore diff --git a/conf.py b/conf.py index ad1ef80cf..7df4450c2 100644 --- a/conf.py +++ b/conf.py @@ -272,6 +272,7 @@ # This is the "production" version of this dictionary DOCS_FOLDERS = { + "api-docs/dev": "documentation/dev", "api-docs/docs-2.0": "documentation/docs-2.0", "api-docs/docs-2.1": "documentation/docs-2.1", "api-docs/docs-2.2": "documentation/docs-2.2", From 0619a5edfe4856545af4c3aaf5137844679e1767 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 11:59:48 -0400 Subject: [PATCH 11/45] Add documentation for YAML reaction definitions --- pages/tutorials/yaml/reactions.rst | 185 +++++++++++++++++++++++++++-- 1 file changed, 174 insertions(+), 11 deletions(-) diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst index 74203fa77..945dd7fee 100644 --- a/pages/tutorials/yaml/reactions.rst +++ b/pages/tutorials/yaml/reactions.rst @@ -15,30 +15,193 @@ Common Attributes ================= -All of the entry types that define reactions share some common features. These -are described first, followed by descriptions of the individual reaction types -in the following sections. +Cantera supports a number of different types of reactions, including several +types of homogeneous reactions, surface reactions, and electrochemical +reactions. The reaction entries for all reaction types some common features. +These general fields of a reaction entry are described first, followed by fields +used for specific reaction types. The Reaction Equation -~~~~~~~~~~~~~~~~~~~~~ +--------------------- -The reaction equation determines the reactant and product stoichiometry. +The reaction equation, specified in the ``equation`` field of the reaction +entry, determines the reactant and product stoichiometry. All tokens (species +names, stoichiometric coefficients, `+`, and `<=>`) in the reaction equation +must be separated with spaces. Some examples of correctly and incorrectly +formatted reaction equations are shown below: -The ID String +.. code:: yaml + + - equation: 2 CH2 <=> CH + CH3 # OK + - equation: 2 CH2<=>CH + CH3 # error - spaces required around '<=>'' + - equation: 2CH2 <=> CH + CH3 # error - space required between '2' and 'CH2' + - equation: CH2 + CH2 <=> CH + CH3 # OK + - equation: 2 CH2 <=> CH+CH3 # error - spaces required around '+' + +Whether the reaction is reversible or not is determined by the form of the +equality sign in the reaction equation. If either ``<=>`` or ``=`` is found, +then the reaction is regarded as reversible, and the reverse rate will be +computed based on the equilibrium constant. If, on the other hand, ``=>`` is +found, the reaction will be treated as irreversible. + +Reaction type ------------- +The type of the rate coefficient parameterization may be specified in the +``type`` field of the ``reaction`` entry. Available reaction types are: + + - `elementary <{{% yaml_dev reactions elementary %}}>`__ + - `three-body <{{% yaml_dev reactions three-body %}}>`__ + - `falloff <{{% yaml_dev reactions falloff %}}>`__ + - `chemically-activated <{{% yaml_dev reactions chemically-activated %}}>`__ + - `pressure-dependent-Arrhenius <{{% yaml_dev reactions pressure-dependent-arrhenius %}}>`__ + - `Chebyshev <{{% yaml_dev reactions chebyshev %}}>`__ + +Additional parameters defining the rate constant for each of these reaction +types are described in the documentation linked above. + +The default parameterization is ``elementary``. Reactions involving surface +species are automatically identified as `interface <{{% yaml_dev reactions +interface %}}>`__ reactions, and reactions involving charge transfer are +automatically identified as `electrochemical <{{% yaml_dev reactions +electrochemical %}}>`__ reactions. + +Arrhenius Expressions +--------------------- + +Most reaction types in Cantera are parameterized by one or more modified +Arrhenius expressions, e.g. + +.. math:: + + k_f(T) = A T^b \exp(-E_a/\bar{R}T) + +Rates in this form can be written as YAML mappings, e.g. + +.. code:: yaml + + {A: 1.0e13, b: 0, E: 7.3 kcal/mol} + +The units of the pre-exponential factor :math:`A` can be specified explicitly if +desired. If not specified, they will be determined based on the ``quantity``, +``length``, and ``time`` units specified in the governing ``units`` fields. +Since the units of :math:`A` depend on the reaction order, the units of each +reactant concentration (dependent on phase type and dimensionality), and the +units of the rate of progress (different for homogeneous and heterogeneous +reactions), it is usually best not to specify units for :math:`A`, in which case +they will be computed taking all of these factors into account. + +Note: if :math:`b \ne 0`, then the term :math:`T^b` should have units of +:math:`K^b`, which would change the units of :math:`A`. This is not done, +however, so the units associated with :math:`A` are really the units for +:math:`k_f` . One way to formally express this is to replace :math:`T^b` by the +non-dimensional quantity :math:`[T/(1\;\mathrm{K})]^b`. + .. _sec-reaction-options: -Options -------- +Duplicate Reactions +------------------- + +When a reaction is imported into a phase, it is checked to see that it is not a +duplicate of another reaction already present in the phase, and normally an +error results if a duplicate is found. But in some cases, it may be appropriate +to include duplicate reactions, for example if a reaction can proceed through +two distinctly different pathways, each with its own rate expression. Another +case where duplicate reactions can be used is if it is desired to implement a +reaction rate coefficient of the form: + +.. math:: + + k_f(T) = \sum_{n=1}^{N} A_n T^{b_n} \exp(-E_n/\hat{R}T) + +While Cantera does not provide such a form for reaction rates, it can be +implemented by defining *N* duplicate reactions, and assigning one rate +coefficient in the sum to each reaction. By adding the field: + +.. code:: yaml + + duplicate: true + +to a reaction entry, then the reaction not only *may* have a duplicate, it +*must*. Any reaction that specifies that it is a duplicate, but cannot be paired +with another reaction in the phase that qualifies as its duplicate generates an +error. + +Negative Pre-exponential Factors +-------------------------------- -Certain conditions are normally flagged as errors by Cantera. In some cases, -they may not be errors, and the options field can be used to specify how they -should be handled. +If some of the terms in the above sum have negative :math:`A_n`, this scheme +fails, since Cantera normally does not allow negative pre-exponential factors. +But if there are duplicate reactions such that the total rate is positive, then +the fact that negative :math:`A` parameters are acceptable can be indicated by +adding the field: + +.. code:: yaml + + negative-A: true Reaction Orders --------------- +Explicit reaction orders different from the stoichiometric coefficients are +sometimes used for non-elementary reactions. For example, consider the global +reaction: + +.. math:: + + \mathrm{C_8H_{18} + 12.5 O_2 \rightarrow 8 CO_2 + 9 H_2O} + +the forward rate constant might be given as [#Westbrook1981]_: + +.. math:: + + k_f = 4.6 \times 10^{11} [\mathrm{C_8H_{18}}]^{0.25} [\mathrm{O_2}]^{1.5} + \exp\left(\frac{30.0\,\mathrm{kcal/mol}}{RT}\right) + +This reaction could be defined as: + +.. code:: yaml + + - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O + rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} + orders: {C8H18: 0.25, O2: 1.5} + +Special care is required in this case since the units of the pre-exponential +factor depend on the sum of the reaction orders, which may not be an integer. + +Note that you can change reaction orders only for irreversible reactions. + + +Negative Reaction Orders +~~~~~~~~~~~~~~~~~~~~~~~~ + +Normally, reaction orders are required to be positive. However, in some cases +negative reaction orders provide better fits for experimental data. In these +cases, the default behavior may be overridden by adding the ``negative-orders`` +field to the reaction entry, e.g.: + +.. code:: yaml + + - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O + rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} + orders: {C8H18: -0.25, O2: 1.75} + negative-orders: true + + +Non-reactant Orders +~~~~~~~~~~~~~~~~~~~ + +Some global reactions could have reactions orders for non-reactant species. In +this case, the ``nonreactant-orders`` field must be added to the reaction entry: + +.. code:: yaml + + - equation: C8H18 + 12.5 O2 => 8 CO2 + 9 H2O + rate-constant: {A: 4.6e11, b: 0.0, Ea: 30.0 kcal/mol} + orders: {C8H18: -0.25, CO: 0.15} + negative-orders: true + nonreactant-orders: true + .. container:: container From 75db4351f05d557376fc9aa825c0e2d84354346f Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 13:37:13 -0400 Subject: [PATCH 12/45] Fix href target search to work for development API docs Sphinx now generates HTML containing additional CSS class names for this text, e.g. "sig-name descname", so the old search pattern no longer works. --- plugins/parse_docs.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/plugins/parse_docs.py b/plugins/parse_docs.py index 16d2f2fc9..669dc26b5 100644 --- a/plugins/parse_docs.py +++ b/plugins/parse_docs.py @@ -63,10 +63,11 @@ def process_targets(dirname, base_dir, docs_folder): elem_id = elem.get("id") parts = elem_id.split(".") try: - title = elem.xpath('code[@class="descname"]/text()')[0] - except IndexError: + title = elem.xpath('code[contains(concat(" ", @class, " "), " descname ")]/text()')[0] + except IndexError as err: self.logger.error( - "Unknown title for class: {}".format(tostring(elem)) + "Unknown title for class: {}\n{}".format(err, + tostring(elem)) ) title = parts[-1] From 8610c1d21e4604da403a1c0afcfa3ab65c20bd48 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 16:35:11 -0400 Subject: [PATCH 13/45] Remove unused references from CTI tutorial --- pages/tutorials/cti/phases.rst | 13 ------------- pages/tutorials/cti/reactions.rst | 18 ------------------ pages/tutorials/cti/species.rst | 4 ---- 3 files changed, 35 deletions(-) diff --git a/pages/tutorials/cti/phases.rst b/pages/tutorials/cti/phases.rst index afc1dfd50..4cc464343 100644 --- a/pages/tutorials/cti/phases.rst +++ b/pages/tutorials/cti/phases.rst @@ -405,16 +405,3 @@ If we import this into Matlab, for example, we get a gas mixture containing the :attributes: href=cti-species.html Next: Elements and Species - -.. rubric:: References - -.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran - chemical kinetics package for the analysis of gasphase chemical - kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989. - -.. [#dl68] G. Dixon-Lewis. Flame structure and flame reaction kinetics, - II: Transport phenomena in multicomponent systems. *Proc. Roy. Soc. A*, - 307:111--135, 1968. - -.. [#Kee2017] R. J. Kee, M. E. Coltrin, P. Glarborg, and H. Zhu. *Chemically Reacting Flow: - Theory and Practice*. 2nd Ed. John Wiley and Sons, 2017. diff --git a/pages/tutorials/cti/reactions.rst b/pages/tutorials/cti/reactions.rst index 13d6551f1..7f9f59619 100644 --- a/pages/tutorials/cti/reactions.rst +++ b/pages/tutorials/cti/reactions.rst @@ -305,24 +305,6 @@ Other Examples .. rubric:: References -.. [#Gilbert1983] R. G. Gilbert, K. Luther, and - J. Troe. *Ber. Bunsenges. Phys. Chem.*, 87:169, 1983. - -.. [#Lindemann1922] F. Lindemann. *Trans. Faraday Soc.*, 17:598, 1922. - -.. [#Smith1997] Gregory P. Smith, David M. Golden, Michael Frenklach, Nigel - W. Moriarty, Boris Eiteneer, Mikhail Goldenberg, C. Thomas Bowman, Ronald - K. Hanson, Soonho Song, William C. Gardiner, Jr., Vitali V. Lissianski, , and - Zhiwei Qin. GRI-Mech version 3.0, 1997. see - http://www.me.berkeley.edu/gri_mech. - -.. [#Stewart1989] P. H. Stewart, C. W. Larson, and D. Golden. - *Combustion and Flame*, 75:25, 1989. - -.. [#Kee1989] R. J. Kee, F. M. Rupley, and J. A. Miller. Chemkin-II: A Fortran - chemical kinetics package for the analysis of gas-phase chemical - kinetics. Technical Report SAND89-8009, Sandia National Laboratories, 1989. - .. [#Westbrook1981] C. K. Westbrook and F. L. Dryer. Simplified reaction mechanisms for the oxidation of hydrocarbon fuels in flames. *Combustion Science and Technology* **27**, pp. 31--43. 1981. diff --git a/pages/tutorials/cti/species.rst b/pages/tutorials/cti/species.rst index f5e872f29..19b3b625f 100644 --- a/pages/tutorials/cti/species.rst +++ b/pages/tutorials/cti/species.rst @@ -281,7 +281,3 @@ no attached units string. .. [#Kee1986] R. J. Kee, G. Dixon-Lewis, J. Warnatz, M. E. Coltrin, and J. A. Miller. A FORTRAN Computer Code Package for the Evaluation of Gas-Phase, Multicomponent Transport Properties. Technical Report SAND86-8246, Sandia National Laboratories, 1986. - -.. [#Mcbride2002] B. J. McBride, M. J. Zehe, S. Gordon. "NASA Glenn Coefficients - for Calculating Thermodynamic Properties of Individual Species," - NASA/TP-2002-211556, Sept. 2002. From 7c0a9121d0d6f993b5c7bfc5b8f334c9282986e3 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 19:19:34 -0400 Subject: [PATCH 14/45] Complete the YAML format tutorial --- pages/tutorials/yaml/defining-phases.rst | 5 +- pages/tutorials/yaml/yaml-format.rst | 266 +++++++++++++++++++++-- 2 files changed, 248 insertions(+), 23 deletions(-) diff --git a/pages/tutorials/yaml/defining-phases.rst b/pages/tutorials/yaml/defining-phases.rst index 55d07c7f2..9420c461e 100644 --- a/pages/tutorials/yaml/defining-phases.rst +++ b/pages/tutorials/yaml/defining-phases.rst @@ -111,8 +111,9 @@ Additional Information .. container:: card-text - This module gives an overview of the syntax and format of Cantera - YAML files + This module describes the basics of the YAML format as used by + Cantera, how dimensional values are represented, and how to + understand error messages that occur while reading input files. .. container:: card diff --git a/pages/tutorials/yaml/yaml-format.rst b/pages/tutorials/yaml/yaml-format.rst index 6292d2df0..2e2b347b5 100644 --- a/pages/tutorials/yaml/yaml-format.rst +++ b/pages/tutorials/yaml/yaml-format.rst @@ -1,5 +1,5 @@ .. slug: yaml-format -.. title: YAML File Structure +.. title: YAML Format Tutorial .. jumbotron:: @@ -9,7 +9,10 @@ .. class:: lead - Here we describe the syntax and structure of Cantera YAML files. + Here we describe the syntax and structure of Cantera YAML files, how + dimensional values in Cantera YAML files are handled, and how to + understand some of the error messages that may be encountered when reading + these input files. Syntax ====== @@ -45,30 +48,102 @@ Numbers can be written as integers, decimal values, or using E-notation Booleans -------- +Boolean values in YAML are written as the words ``true`` or ``false``. + Sequences --------- A sequence of multiple items is specified by separating the items by commas and -enclosing them in square brackets. The individual items can have -any type -- strings, integers, floating-point numbers (or even entries or other -lists). +enclosing them in square brackets. The individual items can have any type -- +strings, integers, floating-point numbers (or even entries or other lists). .. code:: yaml elements: [O, H, C, N, Ar] temperature-ranges: [200.0, 1000.0, 3500.0] -(block style, use of indentation) +Sequences can also be written in "block" style, using one line for each item in +the sequence, with each line starting with a dash: + +.. code:: yaml + + elements: + - O + - H + - C + - N + - Ar + +Sequences can also be nested. The following examples are all equivalent: + +.. code:: yaml + + data: [[1, 2], [3, 4]] + + data: + - + - 1 + - 2 + - + - 3 + - 4 + + data: + - - 1 + - 2 + - - 3 + - 4 + Mappings -------- -(flow style and block style) -(main yaml file is actually a mapping) -(cantera requires all mapping keys to be strings) -(nested mappings) +A mapping is a container consisting of key--value pairs. The keys in a mapping +must be unique. Like sequences, there are two ways to write a mapping. In the +"flow" style, the mapping is enclosed in curly brackets, colons (followed by +spaces) are used to separate keys and values, and key--value pairs are separated +by commas: + +.. code:: yaml + composition: {H: 2, C: 1, O: 1} +In the "block" style, each key is written on a new line, followed by a colon. +The value can be placed either on the same line, or on the following line, +indented one level: + +.. code:: yaml + + composition: + H: 2 + C: + 1 + O: 1 + +All keys in Cantera YAML files are treated as strings. A Cantera YAML file is +itself a mapping, usually in the block style. We refer to the keys in this +top-level mapping as the "sections" of the input file. + +Sequences of Mappings +--------------------- + +A common structure in Cantera input files is a nested sequence of mappings. This +can be written in the "block" style as: + +.. code:: yaml + + - equation: O2 + CO <=> O + CO2 + rate-constant: {A: 2.5e+12, b: 0, Ea: 47800} + - equation: O2 + CH2O <=> HO2 + HCO + rate-constant: {A: 1.0e+14, b: 0, Ea: 40000} + - equation: H + O2 + M <=> HO2 + M + type: three-body + rate-constant: {A: 2.8e+18, b: -0.86, Ea: 0} + efficiencies: {AR: 0, C2H6: 1.5, CO: 0.75, CO2: 1.5, H2O: 0, N2: 0, O2: 0} + +The keys in each mapping need not be the same. In this example, each of the +three mappings in the sequence has ``equation`` and ``rate-constant`` keys, +while only the third entry has ``type`` and ``efficiencies`` keys. Comments -------- @@ -83,33 +158,182 @@ character on a line is ignored: length: cm # use centimeters for length quantity: mol # use moles for quantity -Top-level entries ------------------ +Dimensional Values +================== + +Many fields have numerical values that represent dimensional quantities---a +pressure, or a density, for example. If these are entered without specifying the +units, the default units (set by the ``units`` directive) will be used. However, +it is also possible to specify the units for each individual dimensional +quantity (unless stated otherwise). All that is required is to write the units +after the value, separated by a space: + +.. code:: yaml + + pressure: 1.0e5 # default is Pascals + pressure: 1.0 bar # this is equivalent + density: 4.0 g/cm^3 + density: 4000.0 # kg/m^3 -Entries have fields that can be assigned values. A species entry is shown below -that has fields ``name`` and ``composition``: +Compound unit strings may be used, as long as a few rules are followed: + +1. Units in the denominator follow ``/``. +2. Units in the numerator follow ``*``, except for the first one. +3. Numerical exponents follow the unit string with a ``^`` character. + +Examples of compound units: .. code:: yaml - - name: H2O - composition: {H: 2, O: 1} + A: 1.0e20 cm^6/mol^2/s # OK + h: 6.626e-34 J*s # OK + density: 3.0 g*cm^-3 # OK + A: 1.0e20 cm6/mol/s # error (missing '^') + A: 1.0e20 cm^6/mol^2-s # error ('s' should be in denominator) + density: 3.0g/cm^3 # error (missing space between value and units) -Most entries have some fields that are required; these must be assigned values, -or else processing of the file will abort and an error message will be -printed. Other fields may be optional, and take default values if not assigned. +See the `Units API <{{% ct_dev_docs sphinx/html/yaml/general.html#units %}}>`__ +documentation for additional details, including the full set of supported units. -Dimensional Values -================== +Default units +------------- + +Default units that apply to a whole input file or some portion thereof can be +set using ``units`` mapping. A ``units`` mapping placed at the top level of an +input file applies to the entire file. A ``units`` mapping placed as a member of +another mapping applies to that mapping and any nested mappings or sequences, and overrides higher-level ``units`` mappings: + +.. code:: yaml + + units: {length: cm, mass: kg} + section1: + units: {length: m} + density: 4000 # interpreted as 4000 kg/m^3 + section2: + density: 0.1 # interpreted as 0.1 kg/cm^3 + section3: + - units: {mass: mg} # must be the first item in the list + - name: species1 + density: 5e4 # interpreted as 5e4 mg/cm^3 + +Default units may be set for ``mass``, ``length``, ``time``, ``quantity``, +``pressure``, ``energy``, and ``activation-energy``. Error Handling ============== +During processing of an input file, errors may be encountered. These could be +syntax errors, or could be ones that are flagged as errors by Cantera due to +some apparent inconsistency in the data---an unphysical value, a species that +contains an undeclared element, a reaction that contains an undeclared species, +missing species or element definitions, multiple definitions of elements, +species, or reactions, and so on. + Syntax Errors ------------- +Syntax errors are caught by the YAML parser, and must be corrected before +proceeding further. If a syntax error is encountered, Cantera will raise an +exception which includes the location of the error. Additional information such +as a traceback showing where in the code the input file was being read may be +printed as well. + +For example, consider the following input file, which is intended to create a +gas with the species and reactions of GRI-Mech 3.0, but is missing the colon +which is needed after the ``thermo`` key: + +.. code:: yaml + + phases: + - name: gas + thermo ideal-gas + kinetics: gas + elements: [H, O] + species: [{gri30.yaml/species: all}] + reactions: [gri30.yaml/reactions] + +When this definition is imported into an application, an error message like the +following would be printed to the screen, and execution of the program or script +would terminate: + +.. code:: python + + Traceback (most recent call last): + File "", line 1, in + File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__ + self._init_yaml(infile, phaseid, phases, yaml) + File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml + root = AnyMapFromYamlFile(stringify(infile)) + cantera._cantera.CanteraError: + *********************************************************************** + InputFileError thrown by AnyMap::fromYamlFile: + Error on line 4 of ./gas.yaml: + illegal map value + | Line | + | 1 | phases: + | 2 | - name: gas + | 3 | thermo ideal-gas + > 4 > kinetics: gas + ^ + | 5 | elements: [H, O] + | 6 | species: [{gri30.yaml/species: all}] + | 7 | reactions: [gri30.yaml/reactions] + *********************************************************************** + +The top part of the error message shows the chain of functions that were called +before the error was encountered. For the most part, these are internal Cantera +functions not of direct concern here. The relevant part of this error message is +the part between the lines of asterisks. This message says that the YAML parser +ran into a problem on line 4 of ``gas.yaml``. In many cases, including this one, +the parser will fail somewhere *after* the actual problem with the input file, +since it must continue parsing until it finds something that cannot possibly be +valid YAML syntax. In this case, the problem from the parser's perspective is +that the key which started on line 3 continues across a new line before it finds +a colon that can be considered as the separator. Since a key can't be broken +across lines like this, the parser indicates the error at the point where it +found the colon. By looking back from the indicated point of the error, we can +see that the problem is the missing colon in the previous line. + Cantera Errors -------------- +Now let's consider the other class of errors, ones that Cantera itself +detects. Continuing the example above, suppose that the missing colon is +corrected, and the input file processed again. Again an error message results, +but this time it is from Cantera: + +.. code:: python + + Traceback (most recent call last): + File "", line 1, in + File "/some/path/cantera/base.pyx", line 25, in cantera._cantera._SolutionBase.__cinit__ + self._init_yaml(infile, phaseid, phases, yaml) + File "/some/path/cantera/base.pyx", line 49, in cantera._cantera._SolutionBase._init_yaml + root = AnyMapFromYamlFile(stringify(infile)) + cantera._cantera.CanteraError: + *********************************************************************** + CanteraError thrown by Phase::addSpecies: + Species 'C' contains an undefined element 'C'. + *********************************************************************** + +The problem is that the phase definition specifies that all species are to be +imported from the ``gri30`` mechanism, but only the elements H and O are +declared. The ``gri30`` mechanism contains species composed of the elements H, +O, C, N, and Ar. If the definition is modified to declare these additional +elements: + +.. code:: yaml + + phases: + - name: gas + thermo: ideal-gas + kinetics: gas + elements: [H, O, C, N, Ar] + species: [{gri30.yaml/species: all}] + reactions: [gri30.yaml/reactions] + +it may be imported successfully. + .. container:: container From de1a0d4a6348635c5e723489442dae18783512c3 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 20:29:10 -0400 Subject: [PATCH 15/45] Remove incorrect documentation regarding "stoichiometric liquid" I don't think the CTI `stoichiometric_liquid` class has ever supported a transport model. --- pages/science/phases.rst | 5 ----- 1 file changed, 5 deletions(-) diff --git a/pages/science/phases.rst b/pages/science/phases.rst index dcc382260..f5bbb8e72 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -47,11 +47,6 @@ homogeneous reactions, since the composition is fixed.) A stoichiometric solid can be defined in the CTI format using the :cti:class:`stoichiometric_solid` entry. -Stoichiometric Liquid ---------------------- - -A stoichiometric liquid differs from a stoichiometric solid in only one respect: the transport -manager computes the viscosity as well as the thermal conductivity. Interfaces ########## From 2a83ee1ee1d26232f81fcc4fc8301d5c15f71a43 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 22:05:06 -0400 Subject: [PATCH 16/45] Add links to relevant YAML docs from "Science" section --- pages/science/phases.rst | 13 ++++++++--- pages/science/reactions.rst | 40 ++++++++++++++++++++++---------- pages/science/species.rst | 30 +++++++++++++++++------- pages/tutorials/yaml/species.rst | 3 +++ 4 files changed, 63 insertions(+), 23 deletions(-) diff --git a/pages/science/phases.rst b/pages/science/phases.rst index f5bbb8e72..e44c3e39c 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -25,7 +25,9 @@ It supports all of the options in the widely-used model described by Kee et al. [#Kee1989]_, plus some additional options for species thermodynamic properties and reaction rate expressions. -Ideal gas mixtures can be defined in the CTI format using the :cti:class:`ideal_gas` entry. +Ideal gas mixtures can be defined in the CTI format using the +:cti:class:`ideal_gas` entry, or in the YAML format by specifying `ideal-gas <{{% +yaml_dev phases ideal-gas %}}>`__ in the ``thermo`` field. .. _sec-transport-models: @@ -45,7 +47,9 @@ condensed phase that can participate in heterogeneous reactions. (Of course, the homogeneous reactions, since the composition is fixed.) A stoichiometric solid can be defined in the CTI format using the -:cti:class:`stoichiometric_solid` entry. +:cti:class:`stoichiometric_solid` entry, or in the YAML format by specifying +`fixed-stoichiometry <{{% yaml_dev phases fixed-stoichiometry %}}>`__ in the +``thermo`` field. Interfaces @@ -69,7 +73,10 @@ to the surface concentration :math:`C_k` by where :math:`n_k` is the number of sites covered or blocked by species :math:`k`. -An interface can be defined in the CTI format using the :cti:class:`ideal_interface` entry. +An interface can be defined in the CTI format using the +:cti:class:`ideal_interface` entry, or in the YAML format by specifying +`ideal-surface <{{% yaml_dev phases ideal-surface %}}>`__ in the ``thermo`` +field. .. rubric:: References diff --git a/pages/science/reactions.rst b/pages/science/reactions.rst index a67e01f5e..28d2016f9 100644 --- a/pages/science/reactions.rst +++ b/pages/science/reactions.rst @@ -36,7 +36,8 @@ and the forward reaction rate calculated as: R_f = [\mathrm{A}] [\mathrm{B}] k_f An elementary reaction can be defined in the CTI format using the -:cti:class:`reaction` entry. +:cti:class:`reaction` entry, or in the YAML format using the `elementary <{{% +yaml_dev reactions elementary %}}>`__ reaction ``type``. Three-Body Reactions -------------------- @@ -76,7 +77,8 @@ collision efficiency can be absorbed into the rate coefficient :math:`k_f(T)`, t efficiency is 1.0. A three-body reaction may be defined in the CTI format using the -:cti:class:`three_body_reaction` entry. +:cti:class:`three_body_reaction` entry, or in the YAML format using the +`three-body <{{% yaml_dev reactions three-body %}}>`__ reaction ``type``. Falloff Reactions ----------------- @@ -121,7 +123,8 @@ reactions. The function :math:`F(T, P_r)` is the falloff function, and is specified by assigning an embedded entry to the ``falloff`` field. A falloff reaction may be defined in the CTI format using the -:cti:class:`falloff_reaction` entry. +:cti:class:`falloff_reaction` entry, or in the YAML format using the `falloff +<{{% yaml_dev reactions falloff %}}>`__ reaction ``type``. The Troe Falloff Function ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -142,9 +145,11 @@ al. [#Gilbert1983]_: N = 0.75 - 1.27\; \log_{10} F_{cent} A Troe falloff function may be specified in the CTI format using the -:cti:class:`Troe` directive. The first three parameters, :math:`(A, T_3, T_1)`, -are required. The fourth parameter, :math:`T_2`, is optional; if omitted, the -last term of the falloff function is not used. +:cti:class:`Troe` directive, or in the YAML format using the `Troe +<{{% yaml_dev reactions falloff %}}>`__ field in the reaction entry. The first +three parameters, :math:`(A, T_3, T_1)`, are required. The fourth parameter, +:math:`T_2`, is optional; if omitted, the last term of the falloff function is +not used. .. _sec-sri-falloff: @@ -165,7 +170,8 @@ In keeping with the nomenclature of Kee et al. [#Kee1989]_, we will refer to thi the "SRI" falloff function. An SRI falloff function may be specified in the CTI format using the -:cti:class:`SRI` directive. +:cti:class:`SRI` directive, or in the YAML format using the `SRI +<{{% yaml_dev reactions falloff %}}>`__ field in the entry. Chemically-Activated Reactions ------------------------------ @@ -196,7 +202,9 @@ and the optional blending function :math:`F` may described by any of the parameterizations allowed for falloff reactions. Chemically-activated reactions can be defined in the CTI format using the -:cti:class:`chemically_activated_reaction` entry. +:cti:class:`chemically_activated_reaction` entry, or in the YAML format using +the `chemically-activated <{{% yaml_dev reactions chemically-activated %}}>`__ +reaction ``type``. Pressure-Dependent Arrhenius Rate Expressions (P-Log) @@ -225,7 +233,9 @@ pressure. For pressures outside the given range, the rate expression at the near pressure is used. P-log reactions can be defined in the CTI format using the -:cti:class:`pdep_arrhenius` entry. +:cti:class:`pdep_arrhenius` entry, or in the YAML format using the +`pressure-dependent-Arrhenius <{{% yaml_dev reactions +pressure-dependent-arrhenius %}}>`__ reaction ``type``. Chebyshev Reaction Rate Expressions ----------------------------------- @@ -263,7 +273,8 @@ Note that the Chebyshev polynomials are not defined outside the interval temperatures and pressure for which they are defined is strongly discouraged. Chebyshev reactions can be defined in the CTI format using the -:cti:class:`chebyshev_reaction` entry. +:cti:class:`chebyshev_reaction` entry, or in the YAML format using the +`Chebyshev <{{% yaml_dev reactions chebyshev %}}>`__ reaction ``type``. Surface Reactions ----------------- @@ -288,7 +299,9 @@ dependencies from species :math:`\mathrm{k}`. Surface reactions can be defined in the CTI format using the :cti:class:`surface_reaction` entry, with coverage information provided using the ``coverage`` keyword argument supplied to the :cti:class:`Arrhenius` -directive. +directive. In the YAML format, surface reactions are identified by the presence +of surface species and support several `additional options <{{% yaml_dev +reactions interface %}}>`__. Sticking Coefficients @@ -318,7 +331,10 @@ the sum of all the surface reactant stoichiometric coefficients, and :math:`W` is the molecular weight of the gas phase species. .. TODO: Link to :cti:class:`stick` after 2.5.0 release adds that to the docs -Sticking reactions can be defined in the CTI format using the `stick` entry. + +Sticking reactions can be defined in the CTI format using the `stick` entry, or +in the YAML format by specifying the rate constant in the reaction's +`sticking-coefficient <{{% yaml_dev reactions interface %}}>`__ field. Additional Options ------------------ diff --git a/pages/science/species.rst b/pages/science/species.rst index 9c6d7b099..efb92b3a0 100644 --- a/pages/science/species.rst +++ b/pages/science/species.rst @@ -21,7 +21,9 @@ that definitions of elements are not often needed, since Cantera has definitions for the standard chemical elements. Explicit element definitions are usually only needed for isotopes. -An element can be defined in the CTI format using the :cti:class:`element` entry. +An element can be defined in the CTI format using the :cti:class:`element` +entry, or in the YAML format by adding entries to the :ref:`elements +` section of the input file. Species @@ -29,7 +31,9 @@ Species For each species, a species definition is required. -A species can be defined in the CTI format using the :cti:class:`species` entry. +A species can be defined in the CTI format using the :cti:class:`species` entry, +or in the YAML format by adding an entry to the :ref:`species +` section of the input file. Species Name @@ -90,8 +94,10 @@ Transport property models in general require coefficients that express the effect of each species on the transport properties of the phase. Currently, ideal-gas transport property models are implemented. + Transport properties can be defined in the CTI format using the -:cti:class:`gas_transport` entry. +:cti:class:`gas_transport` entry, or in the YAML format using the `transport +` field of a ``species`` entry. .. _sec-thermo-models: @@ -136,7 +142,9 @@ version of the NASA equilibrium program, which uses 9 coefficients for each temperature region. A NASA-7 parameterization can be defined in the CTI format using the -:cti:class:`NASA` entry. +:cti:class:`NASA` entry, or in the YAML format by specifying `NASA7 <{{% +yaml_dev species sec-yaml-nasa7 %}}>`__ as the ``model`` in the species +``thermo`` field. The NASA 9-Coefficient Polynomial Parameterization @@ -163,7 +171,9 @@ the following equations: + a_3 T + \frac{a_4}{2} T^2 + \frac{a_5}{3} T^3 + \frac{a_6}{4} T^4 + a_8 A NASA-9 parameterization can be defined in the CTI format using the -:cti:class:`NASA9` entry. +:cti:class:`NASA9` entry, or in the YAML format by specifying `NASA9 <{{% +yaml_dev species nasa-9-coefficient-polynomials %}}>`__ as the ``model`` in the +species ``thermo`` field. The Shomate Parameterization @@ -188,7 +198,9 @@ coefficients :math:`A` through :math:`G` should be entered precisely as shown th attached. Unit conversions to SI will be handled internally. A Shomate parameterization can be defined in the CTI format using the -:cti:class:`Shomate` entry. +:cti:class:`Shomate` entry, or in the YAML format by specifying `Shomate <{{% +yaml_dev species shomate-polynomials %}}>`__ as the ``model`` in the species +``thermo`` field. Constant Heat Capacity ---------------------- @@ -210,8 +222,10 @@ The parameterization uses four constants: :math:`T_0, \hat{c}_p^0(T_0), \hat{h}^0(T_0), \hat{s}^0(T)`. The default value of :math:`T_0` is 298.15 K; the default value for the other parameters is 0.0. -A constant heat capacity parameterization can be defined in the CTI format -using the :cti:class:`const_cp` entry. +A constant heat capacity parameterization can be defined in the CTI format using +the :cti:class:`const_cp` entry, or in the YAML format by specifying +`constant-cp <{{% yaml_dev species constant-heat-capacity %}}>`__ as the +``model`` in the species ``thermo`` field. .. rubric:: References diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index 59623821b..b9bce8912 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -50,6 +50,7 @@ An example ``elements`` section: - symbol: O-18 atomic-weight: 17.9991603 +.. _sec-yaml-species: Species ======= @@ -149,6 +150,8 @@ parameterization used specified by the ``model`` field of the The fields used by each model are described and examples provided in the linked documentation. +.. _sec-yaml-species-transport: + Species Transport Coefficients ------------------------------ From ff9665e5c7560d6ff2751634f4cbbc757e8baf33 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 14 Oct 2019 22:13:35 -0400 Subject: [PATCH 17/45] Link YAML users' guide from dev docs page --- pages/documentation/dev-docs.html | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/pages/documentation/dev-docs.html b/pages/documentation/dev-docs.html index 2c48a1427..39b78837a 100644 --- a/pages/documentation/dev-docs.html +++ b/pages/documentation/dev-docs.html @@ -111,9 +111,14 @@

Search the documentation

Other Documentation
+
+ + YAML Input File Users' Guide + +
- YAML Input File Reference + YAML Input File API Reference
From 4b059c5945fe5c6fbd602447e16da9e9c93798c6 Mon Sep 17 00:00:00 2001 From: "Bryan W. Weber" Date: Mon, 11 Nov 2019 12:19:59 -0500 Subject: [PATCH 18/45] Add YAML API docs to ref_targets The YAML API is mostly not functions, but handled as Sphinx sections. So they are added to ref_targets --- pages/science/phases.rst | 7 +++--- plugins/process_ref_targets.py | 42 ++++++++++++++++++++++++++++++---- 2 files changed, 41 insertions(+), 8 deletions(-) diff --git a/pages/science/phases.rst b/pages/science/phases.rst index e44c3e39c..3a019c797 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -26,8 +26,8 @@ It supports all of the options in the widely-used model described by Kee et al. and reaction rate expressions. Ideal gas mixtures can be defined in the CTI format using the -:cti:class:`ideal_gas` entry, or in the YAML format by specifying `ideal-gas <{{% -yaml_dev phases ideal-gas %}}>`__ in the ``thermo`` field. +:cti:class:`ideal_gas` entry, or in the YAML format by specifying +:ref:`ideal-gas ` in the ``thermo`` field. .. _sec-transport-models: @@ -48,8 +48,7 @@ homogeneous reactions, since the composition is fixed.) A stoichiometric solid can be defined in the CTI format using the :cti:class:`stoichiometric_solid` entry, or in the YAML format by specifying -`fixed-stoichiometry <{{% yaml_dev phases fixed-stoichiometry %}}>`__ in the -``thermo`` field. +:ref:`fixed-stoichiometry ` in the ``thermo`` field. Interfaces diff --git a/plugins/process_ref_targets.py b/plugins/process_ref_targets.py index 96cb2665e..90c8bd9be 100644 --- a/plugins/process_ref_targets.py +++ b/plugins/process_ref_targets.py @@ -19,6 +19,10 @@ from docutils.core import Publisher from copy import copy +from pathlib import Path + +HERE = Path(__file__).parent + class ProcessRefTargets(Task): """Find and process targets in reST files.""" @@ -75,7 +79,10 @@ def tl_ch(): "name": source, "task_dep": ["process_ref_targets:timeline_changes"], "actions": [ - (process_targets, [self.site, self.logger, source, post]), + ( + process_targets, + [self.site, self.logger, source, post.permalink()], + ), (update_cache, [self.site]), ], "uptodate": [config_changed(deps_dict, "process_ref_targets")] @@ -83,6 +90,33 @@ def tl_ch(): } yield task + # These are YAML API docs. However, they are parsed here because they aren't + # the typical Sphinx-generated documentation for functions and classes, most + # of the text is broken out into sections with ref targets. Note that the + # permalink is hard-coded here to point to the dev documentation that will + # need to be updated when 2.5.0 is released. + yaml_docs_path = HERE.parent.parent.joinpath("cantera", "doc", "sphinx", "yaml") + if yaml_docs_path.exists(): + for rest_file in yaml_docs_path.glob("**/*.rst"): + permalink = ( + "/documentation/dev/sphinx/html/yaml/" + + rest_file.with_suffix(".html").name + ) + yield { + "basename": self.name, + "name": str(rest_file), + "task_dep": ["process_ref_targets:timeline_changes"], + "actions": [ + ( + process_targets, + [self.site, self.logger, str(rest_file), permalink], + ), + (update_cache, [self.site]), + ], + } + else: + self.logger.warn("Could not find the API documentation for the YAML format") + def update_cache(site): """Update the Nikola build cache.""" @@ -101,7 +135,7 @@ def update_cache(site): site.cache.set("anon_ref_targets", site.anon_ref_targets) -def process_targets(site, logger, source, post): +def process_targets(site, logger, source, permalink): """Process the target locations in the reST files.""" site.processing_targets = True reader = Reader() @@ -151,7 +185,7 @@ def process_targets(site, logger, source, post): dup=name, other=site.ref_targets[name][0] ) ) - site.anon_ref_targets[name] = post.permalink(), labelid + site.anon_ref_targets[name] = permalink, labelid def clean_astext(node): """Like node.astext(), but ignore images. @@ -169,4 +203,4 @@ def clean_astext(node): sectname = clean_astext(node[0]) else: continue - site.ref_targets[name] = post.permalink(), labelid, sectname + site.ref_targets[name] = permalink, labelid, sectname From 6e5eaa80e332e9abafa9484edd03db30295f36c7 Mon Sep 17 00:00:00 2001 From: "Bryan W. Weber" Date: Mon, 11 Nov 2019 12:59:57 -0500 Subject: [PATCH 19/45] Get the YAML API docs by scraping GitHub Since we clone the 2.4 branch of the repo that doesn't have these docs --- plugins/process_ref_targets.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/plugins/process_ref_targets.py b/plugins/process_ref_targets.py index 90c8bd9be..9ac4dc79f 100644 --- a/plugins/process_ref_targets.py +++ b/plugins/process_ref_targets.py @@ -20,6 +20,8 @@ from copy import copy from pathlib import Path +import tempfile +import requests HERE = Path(__file__).parent @@ -95,7 +97,26 @@ def tl_ch(): # of the text is broken out into sections with ref targets. Note that the # permalink is hard-coded here to point to the dev documentation that will # need to be updated when 2.5.0 is released. - yaml_docs_path = HERE.parent.parent.joinpath("cantera", "doc", "sphinx", "yaml") + temp_dir = tempfile.mkdtemp() + # HERE.parent.parent.joinpath("cantera", "doc", "sphinx", "yaml") + yaml_docs_path = Path(temp_dir) + url_base = "https://raw.githubusercontent.com/Cantera/cantera/master/doc/sphinx/yaml/{}.rst" + for name in [ + "elements", + "general", + "index", + "phases", + "reactions", + "species", + ]: + url = url_base.format(name) + try: + r = requests.get(url) + yaml_docs_path.joinpath("{}.rst".format(name)).write_bytes(r.content) + except: + self.logger.warn( + "Could not download YAML API file: {}.rst".format(name) + ) if yaml_docs_path.exists(): for rest_file in yaml_docs_path.glob("**/*.rst"): permalink = ( @@ -115,7 +136,11 @@ def tl_ch(): ], } else: - self.logger.warn("Could not find the API documentation for the YAML format") + self.logger.warn( + "Could not find the API documentation for the YAML format: {}".format( + yaml_docs_path + ) + ) def update_cache(site): From ff3b3ff988d47e5bd864525a0c0048445a89e956 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Mon, 9 Dec 2019 17:45:44 -0500 Subject: [PATCH 20/45] Use ref targets for YAML documentation --- pages/science/phases.rst | 2 +- pages/science/reactions.rst | 33 +++++++++++---------- pages/science/species.rst | 21 ++++++-------- pages/tutorials/yaml/phases.rst | 46 +++++++++++++++--------------- pages/tutorials/yaml/reactions.rst | 20 ++++++------- pages/tutorials/yaml/species.rst | 30 +++++++++---------- shortcodes/yaml_dev.tmpl | 1 - 7 files changed, 74 insertions(+), 79 deletions(-) delete mode 100644 shortcodes/yaml_dev.tmpl diff --git a/pages/science/phases.rst b/pages/science/phases.rst index 3a019c797..a882ee1d3 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -74,7 +74,7 @@ where :math:`n_k` is the number of sites covered or blocked by species :math:`k` An interface can be defined in the CTI format using the :cti:class:`ideal_interface` entry, or in the YAML format by specifying -`ideal-surface <{{% yaml_dev phases ideal-surface %}}>`__ in the ``thermo`` +:ref:`ideal-surface ` in the ``thermo`` field. diff --git a/pages/science/reactions.rst b/pages/science/reactions.rst index 28d2016f9..62925950f 100644 --- a/pages/science/reactions.rst +++ b/pages/science/reactions.rst @@ -36,8 +36,8 @@ and the forward reaction rate calculated as: R_f = [\mathrm{A}] [\mathrm{B}] k_f An elementary reaction can be defined in the CTI format using the -:cti:class:`reaction` entry, or in the YAML format using the `elementary <{{% -yaml_dev reactions elementary %}}>`__ reaction ``type``. +:cti:class:`reaction` entry, or in the YAML format using the +:ref:`elementary ` reaction ``type``. x Three-Body Reactions -------------------- @@ -78,7 +78,7 @@ efficiency is 1.0. A three-body reaction may be defined in the CTI format using the :cti:class:`three_body_reaction` entry, or in the YAML format using the -`three-body <{{% yaml_dev reactions three-body %}}>`__ reaction ``type``. +:ref:`three-body ` reaction ``type``. Falloff Reactions ----------------- @@ -123,8 +123,8 @@ reactions. The function :math:`F(T, P_r)` is the falloff function, and is specified by assigning an embedded entry to the ``falloff`` field. A falloff reaction may be defined in the CTI format using the -:cti:class:`falloff_reaction` entry, or in the YAML format using the `falloff -<{{% yaml_dev reactions falloff %}}>`__ reaction ``type``. +:cti:class:`falloff_reaction` entry, or in the YAML format using the +:ref:`falloff ` reaction ``type``. The Troe Falloff Function ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -145,8 +145,8 @@ al. [#Gilbert1983]_: N = 0.75 - 1.27\; \log_{10} F_{cent} A Troe falloff function may be specified in the CTI format using the -:cti:class:`Troe` directive, or in the YAML format using the `Troe -<{{% yaml_dev reactions falloff %}}>`__ field in the reaction entry. The first +:cti:class:`Troe` directive, or in the YAML format using the +:ref:`Troe ` field in the reaction entry. The first three parameters, :math:`(A, T_3, T_1)`, are required. The fourth parameter, :math:`T_2`, is optional; if omitted, the last term of the falloff function is not used. @@ -170,8 +170,8 @@ In keeping with the nomenclature of Kee et al. [#Kee1989]_, we will refer to thi the "SRI" falloff function. An SRI falloff function may be specified in the CTI format using the -:cti:class:`SRI` directive, or in the YAML format using the `SRI -<{{% yaml_dev reactions falloff %}}>`__ field in the entry. +:cti:class:`SRI` directive, or in the YAML format using the +:ref:`SRI ` field in the entry. Chemically-Activated Reactions ------------------------------ @@ -203,8 +203,7 @@ parameterizations allowed for falloff reactions. Chemically-activated reactions can be defined in the CTI format using the :cti:class:`chemically_activated_reaction` entry, or in the YAML format using -the `chemically-activated <{{% yaml_dev reactions chemically-activated %}}>`__ -reaction ``type``. +the :ref:`chemically-activated ` reaction ``type``. Pressure-Dependent Arrhenius Rate Expressions (P-Log) @@ -234,8 +233,8 @@ pressure is used. P-log reactions can be defined in the CTI format using the :cti:class:`pdep_arrhenius` entry, or in the YAML format using the -`pressure-dependent-Arrhenius <{{% yaml_dev reactions -pressure-dependent-arrhenius %}}>`__ reaction ``type``. +:ref:`pressure-dependent-Arrhenius ` +reaction ``type``. Chebyshev Reaction Rate Expressions ----------------------------------- @@ -274,7 +273,7 @@ temperatures and pressure for which they are defined is strongly discouraged. Chebyshev reactions can be defined in the CTI format using the :cti:class:`chebyshev_reaction` entry, or in the YAML format using the -`Chebyshev <{{% yaml_dev reactions chebyshev %}}>`__ reaction ``type``. +:ref:`Chebyshev ` reaction ``type``. Surface Reactions ----------------- @@ -300,8 +299,8 @@ Surface reactions can be defined in the CTI format using the :cti:class:`surface_reaction` entry, with coverage information provided using the ``coverage`` keyword argument supplied to the :cti:class:`Arrhenius` directive. In the YAML format, surface reactions are identified by the presence -of surface species and support several `additional options <{{% yaml_dev -reactions interface %}}>`__. +of surface species and support several +:ref:`additional options `. Sticking Coefficients @@ -334,7 +333,7 @@ is the molecular weight of the gas phase species. Sticking reactions can be defined in the CTI format using the `stick` entry, or in the YAML format by specifying the rate constant in the reaction's -`sticking-coefficient <{{% yaml_dev reactions interface %}}>`__ field. +:ref:`sticking-coefficient ` field. Additional Options ------------------ diff --git a/pages/science/species.rst b/pages/science/species.rst index efb92b3a0..9d0173a77 100644 --- a/pages/science/species.rst +++ b/pages/science/species.rst @@ -96,8 +96,8 @@ ideal-gas transport property models are implemented. Transport properties can be defined in the CTI format using the -:cti:class:`gas_transport` entry, or in the YAML format using the `transport -` field of a ``species`` entry. +:cti:class:`gas_transport` entry, or in the YAML format using the +:ref:`transport ` field of a ``species`` entry. .. _sec-thermo-models: @@ -142,9 +142,8 @@ version of the NASA equilibrium program, which uses 9 coefficients for each temperature region. A NASA-7 parameterization can be defined in the CTI format using the -:cti:class:`NASA` entry, or in the YAML format by specifying `NASA7 <{{% -yaml_dev species sec-yaml-nasa7 %}}>`__ as the ``model`` in the species -``thermo`` field. +:cti:class:`NASA` entry, or in the YAML format by specifying +:ref:`NASA7 ` as the ``model`` in the species ``thermo`` field. The NASA 9-Coefficient Polynomial Parameterization @@ -171,9 +170,8 @@ the following equations: + a_3 T + \frac{a_4}{2} T^2 + \frac{a_5}{3} T^3 + \frac{a_6}{4} T^4 + a_8 A NASA-9 parameterization can be defined in the CTI format using the -:cti:class:`NASA9` entry, or in the YAML format by specifying `NASA9 <{{% -yaml_dev species nasa-9-coefficient-polynomials %}}>`__ as the ``model`` in the -species ``thermo`` field. +:cti:class:`NASA9` entry, or in the YAML format by specifying +:ref:`NASA9 ` as the ``model`` in the species ``thermo`` field. The Shomate Parameterization @@ -198,8 +196,8 @@ coefficients :math:`A` through :math:`G` should be entered precisely as shown th attached. Unit conversions to SI will be handled internally. A Shomate parameterization can be defined in the CTI format using the -:cti:class:`Shomate` entry, or in the YAML format by specifying `Shomate <{{% -yaml_dev species shomate-polynomials %}}>`__ as the ``model`` in the species +:cti:class:`Shomate` entry, or in the YAML format by specifying +:ref:`Shomate ` as the ``model`` in the species ``thermo`` field. Constant Heat Capacity @@ -224,8 +222,7 @@ default value for the other parameters is 0.0. A constant heat capacity parameterization can be defined in the CTI format using the :cti:class:`const_cp` entry, or in the YAML format by specifying -`constant-cp <{{% yaml_dev species constant-heat-capacity %}}>`__ as the -``model`` in the species ``thermo`` field. +:ref:`constant-cp ` as the ``model`` in the species ``thermo`` field. .. rubric:: References diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index d74a89cbf..6fdf23dd6 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -35,29 +35,29 @@ Setting the Thermodynamic Model The thermodynamic model used to represent a phase is specified in the ``thermo`` field. Supported models are: - - `binary-solution-tabulated <{{% yaml_dev phases binary-solution-tabulated %}}>`__ - - `compound-lattice <{{% yaml_dev phases compound-lattice %}}>`__ - - `constant-density <{{% yaml_dev phases constant-density %}}>`__ - - `Debye-Huckel <{{% yaml_dev phases debye-huckel %}}>`__ - - `edge <{{% yaml_dev phases edge %}}>`__ - - `fixed-chemical-potential <{{% yaml_dev phases fixed-chemical-potential %}}>`__ - - `fixed-stoichiometry <{{% yaml_dev phases fixed-stoichiometry %}}>`__ - - `HMW-electrolyte <{{% yaml_dev phases hmw-electrolyte %}}>`__ - - `ideal-gas <{{% yaml_dev phases ideal-gas %}}>`__ - - `ideal-gas-VPSS <{{% yaml_dev phases ideal-gas-vpss %}}>`__ - - `ideal-molal-solution <{{% yaml_dev phases ideal-molal-solution %}}>`__ - - `ideal-condensed <{{% yaml_dev phases ideal-condensed %}}>`__ - - `ideal-solution-VPSS <{{% yaml_dev phases ideal-solution-vpss %}}>`__ - - `ideal-surface <{{% yaml_dev phases ideal-surface %}}>`__ - - `ions-from-neutral-molecule <{{% yaml_dev phases ions-from-neutral-molecule %}}>`__ - - `lattice <{{% yaml_dev phases lattice %}}>`__ - - `liquid-water-IAPWS95 <{{% yaml_dev phases liquid-water-iapws95 %}}>`__ - - `Margules <{{% yaml_dev phases margules %}}>`__ - - `Maskell-solid-solution <{{% yaml_dev phases maskell-solid-solution %}}>`__ - - `electron-cloud <{{% yaml_dev phases electron-cloud %}}>`__ - - `pure-fluid <{{% yaml_dev phases pure-fluid %}}>`__ - - `Redlich-Kister <{{% yaml_dev phases redlich-kister %}}>`__ - - `Redlich-Kwong <{{% yaml_dev phases redlich-kwong %}}>`__ + - :ref:`binary-solution-tabulated ` + - :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:`liquid-water-IAPWS95 ` + - :ref:`Margules ` + - :ref:`Maskell-solid-solution ` + - :ref:`electron-cloud ` + - :ref:`pure-fluid ` + - :ref:`Redlich-Kister ` + - :ref:`Redlich-Kwong ` Some thermodynamic models use additional fields in the ``phase`` entry, which are described in the linked documentation. diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst index 945dd7fee..ff4cd71d0 100644 --- a/pages/tutorials/yaml/reactions.rst +++ b/pages/tutorials/yaml/reactions.rst @@ -50,21 +50,21 @@ Reaction type The type of the rate coefficient parameterization may be specified in the ``type`` field of the ``reaction`` entry. Available reaction types are: - - `elementary <{{% yaml_dev reactions elementary %}}>`__ - - `three-body <{{% yaml_dev reactions three-body %}}>`__ - - `falloff <{{% yaml_dev reactions falloff %}}>`__ - - `chemically-activated <{{% yaml_dev reactions chemically-activated %}}>`__ - - `pressure-dependent-Arrhenius <{{% yaml_dev reactions pressure-dependent-arrhenius %}}>`__ - - `Chebyshev <{{% yaml_dev reactions chebyshev %}}>`__ + - :ref:`elementary ` + - :ref:`three-body ` + - :ref:`falloff ` + - :ref:`chemically-activated ` + - :ref:`pressure-dependent-Arrhenius ` + - :ref:`Chebyshev ` Additional parameters defining the rate constant for each of these reaction types are described in the documentation linked above. The default parameterization is ``elementary``. Reactions involving surface -species are automatically identified as `interface <{{% yaml_dev reactions -interface %}}>`__ reactions, and reactions involving charge transfer are -automatically identified as `electrochemical <{{% yaml_dev reactions -electrochemical %}}>`__ reactions. +species are automatically identified as :ref:`interface ` +reactions, and reactions involving charge transfer are +automatically identified as :ref:`electrochemical ` +reactions. Arrhenius Expressions --------------------- diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index b9bce8912..7550846f6 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -120,11 +120,11 @@ entry. The parameterization used to provide this information is specified by the ``model`` field of the ``thermo`` field. The models available are: - - `NASA7 <{{% yaml_dev species sec-yaml-nasa7 %}}>`__ - - `NASA9 <{{% yaml_dev species nasa-9-coefficient-polynomials %}}>`__ - - `Shomate <{{% yaml_dev species shomate-polynomials %}}>`__ - - `constant-cp <{{% yaml_dev species constant-heat-capacity %}}>`__ - - `piecewise-Gibbs <{{% yaml_dev species piecewise-gibbs %}}>`__ + - :ref:`NASA7 ` + - :ref:`NASA9 ` + - :ref:`Shomate ` + - :ref:`constant-cp ` + - :ref:`piecewise-Gibbs ` The fields used by each model are described and examples provided in the linked documentation. @@ -138,14 +138,14 @@ 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: - - `constant-volume <{{% yaml_dev species sec-yaml-eos-constant-volume %}}>`__ - - `density-temperature-polynomial <{{% yaml_dev species density-temperature-polynomial %}}>`__ - - `HKFT <{{% yaml_dev species hkft %}}>`__ - - `ideal-gas <{{% yaml_dev species sec-yaml-eos-ideal-gas %}}>`__ - - `ions-from-neutral-molecule <{{% yaml_dev species ions-from-neutral-molecule %}}>`__ - - `liquid-water-IAPWS95 <{{% yaml_dev species liquid-water-iapws95 %}}>`__ - - `molar-volume-temperature-polynomial <{{% yaml_dev species piecewise-gibbs %}}>`__ - - `Redlich-Kwong <{{% yaml_dev species redlich-kwong %}}>`__ + - :ref:`constant-volume ` + - :ref:`density-temperature-polynomial ` + - :ref:`HKFT ` + - :ref:`ideal-gas ` + - :ref:`ions-from-neutral-molecule ` + - :ref:`liquid-water-IAPWS95 ` + - :ref:`molar-volume-temperature-polynomial ` + - :ref:`Redlich-Kwong ` The fields used by each model are described and examples provided in the linked documentation. @@ -161,8 +161,8 @@ transport properties of a phase. These parameters are provided in the parameterization used specified by the ``model`` field of the ``transport`` field. The only model type specifically handled is ``gas``. The parameters used depend on the transport model specified at the phase level. The full set of -possible parameters is described in the `API documentation -<{{% yaml_dev species gas-transport %}}>`__. +possible parameters is described in the :ref:`API documentation +`. An example of a ``transport`` entry: diff --git a/shortcodes/yaml_dev.tmpl b/shortcodes/yaml_dev.tmpl deleted file mode 100644 index 89019a25b..000000000 --- a/shortcodes/yaml_dev.tmpl +++ /dev/null @@ -1 +0,0 @@ -{{ '/' if site.config['BASE_URL'] == site.config['SITE_URL'] else site.config['BASE_URL'] }}documentation/dev/sphinx/html/yaml/{{ _args[0] }}.html{{'#'+_args[1] if _args|length == 2 else link }} From 6b408bee9c2fe711341d592905748e00107404da Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 10 Dec 2019 00:01:20 -0500 Subject: [PATCH 21/45] Fix references to reST sections with capitalized names All names are normalized to lowercase within docutils --- plugins/ref.py | 1 + 1 file changed, 1 insertion(+) diff --git a/plugins/ref.py b/plugins/ref.py index a946058dc..23de209b1 100644 --- a/plugins/ref.py +++ b/plugins/ref.py @@ -34,6 +34,7 @@ def _ref_link(rawtext, text, options={}, content=[]): return True, True, None, None, None has_explicit_title, title, target = split_explicit_title(text) + target = target.lower() if ref_role.site.cache.get("ref_targets") is not None: ref_targets = ref_role.site.cache.get("ref_targets").copy() From 156f15f2e0a622dbd3b35c1e3f38341ecee0e045 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 10 Dec 2019 00:18:33 -0500 Subject: [PATCH 22/45] Fix duplicated labels in YAML docs --- pages/science/reactions.rst | 2 +- pages/tutorials/yaml/phases.rst | 5 ++--- pages/tutorials/yaml/reactions.rst | 2 +- pages/tutorials/yaml/species.rst | 6 +++--- 4 files changed, 7 insertions(+), 8 deletions(-) diff --git a/pages/science/reactions.rst b/pages/science/reactions.rst index 62925950f..58923de48 100644 --- a/pages/science/reactions.rst +++ b/pages/science/reactions.rst @@ -37,7 +37,7 @@ and the forward reaction rate calculated as: An elementary reaction can be defined in the CTI format using the :cti:class:`reaction` entry, or in the YAML format using the -:ref:`elementary ` reaction ``type``. x +:ref:`elementary ` reaction ``type``. Three-Body Reactions -------------------- diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index 6fdf23dd6..a239851c1 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -76,9 +76,8 @@ ordering of elements within the phase is important, the elements in the phase may be declared in the optional ``elements`` entry. If all of the elements to be added are either standard chemical elements or -defined in the ``elements`` section of the current input file (see -:ref:`sec-yaml-elements`), the elements can be specified as a list of element -symbols, e.g.: +defined in the :ref:`elements ` section of the current +input file, the elements can be specified as a list of element symbols, e.g.: .. code:: yaml diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst index ff4cd71d0..0caaa4733 100644 --- a/pages/tutorials/yaml/reactions.rst +++ b/pages/tutorials/yaml/reactions.rst @@ -97,7 +97,7 @@ however, so the units associated with :math:`A` are really the units for :math:`k_f` . One way to formally express this is to replace :math:`T^b` by the non-dimensional quantity :math:`[T/(1\;\mathrm{K})]^b`. -.. _sec-reaction-options: +.. _sec-yaml-reaction-options: Duplicate Reactions ------------------- diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index 7550846f6..5544c18ac 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -12,7 +12,7 @@ A description of how elements and species are defined in YAML input files -.. _sec-yaml-elements: +.. _sec-yaml-guide-elements: Elements ======== @@ -50,7 +50,7 @@ An example ``elements`` section: - symbol: O-18 atomic-weight: 17.9991603 -.. _sec-yaml-species: +.. _sec-yaml-guide-species: Species ======= @@ -150,7 +150,7 @@ parameterization used specified by the ``model`` field of the The fields used by each model are described and examples provided in the linked documentation. -.. _sec-yaml-species-transport: +.. _sec-yaml-guide-species-transport: Species Transport Coefficients ------------------------------ From 9835fafd400b201b4ea294d213bc5da1eeb0707c Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 10 Dec 2019 10:42:06 -0500 Subject: [PATCH 23/45] Change CSS for literal strings to make them stand out more --- themes/cantera/assets/css/custom.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/themes/cantera/assets/css/custom.css b/themes/cantera/assets/css/custom.css index dcd83a3a2..ae9f73536 100644 --- a/themes/cantera/assets/css/custom.css +++ b/themes/cantera/assets/css/custom.css @@ -28,10 +28,11 @@ a.release-notes:hover { background-color: #c80202; color: #ffffff; } .row { margin: 0 0 20px; } -tt { +.docutils.literal { font-family: SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace; + font-weight: bold; font-size: 1em; - font-size: 87.5%; + color: #444; word-break: break-word; } From d0b558bb9e541973896d9748988ff13802d6958c Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 10 Dec 2019 10:47:05 -0500 Subject: [PATCH 24/45] Fix math formatting in Python / Matlab tutorials --- pages/tutorials/MatlabTutorial.rst | 1 + pages/tutorials/PythonTutorial.rst | 1 + 2 files changed, 2 insertions(+) diff --git a/pages/tutorials/MatlabTutorial.rst b/pages/tutorials/MatlabTutorial.rst index cd3b34dbf..d5703137e 100644 --- a/pages/tutorials/MatlabTutorial.rst +++ b/pages/tutorials/MatlabTutorial.rst @@ -1,4 +1,5 @@ .. slug: matlab-tutorial +.. has_math: true .. title: Matlab Tutorial .. jumbotron:: diff --git a/pages/tutorials/PythonTutorial.rst b/pages/tutorials/PythonTutorial.rst index 3ea8932a1..5dc8082df 100644 --- a/pages/tutorials/PythonTutorial.rst +++ b/pages/tutorials/PythonTutorial.rst @@ -1,4 +1,5 @@ .. slug: python-tutorial +.. has_math: true .. title: Python Tutorial .. jumbotron:: From e0b39abd54e3f2affe027b3e9d1c8351b28b6436 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 2 Jan 2020 12:56:01 -0500 Subject: [PATCH 25/45] Use one blank line before section headers --- pages/science/phases.rst | 1 - pages/science/reactions.rst | 2 -- pages/science/species.rst | 4 ---- pages/tutorials/yaml/phases.rst | 8 -------- pages/tutorials/yaml/reactions.rst | 2 -- pages/tutorials/yaml/species.rst | 1 - pages/tutorials/yaml/yaml-format.rst | 1 - 7 files changed, 19 deletions(-) diff --git a/pages/science/phases.rst b/pages/science/phases.rst index a882ee1d3..c3d75dd51 100644 --- a/pages/science/phases.rst +++ b/pages/science/phases.rst @@ -50,7 +50,6 @@ A stoichiometric solid can be defined in the CTI format using the :cti:class:`stoichiometric_solid` entry, or in the YAML format by specifying :ref:`fixed-stoichiometry ` in the ``thermo`` field. - Interfaces ########## diff --git a/pages/science/reactions.rst b/pages/science/reactions.rst index 58923de48..b405748e2 100644 --- a/pages/science/reactions.rst +++ b/pages/science/reactions.rst @@ -205,7 +205,6 @@ Chemically-activated reactions can be defined in the CTI format using the :cti:class:`chemically_activated_reaction` entry, or in the YAML format using the :ref:`chemically-activated ` reaction ``type``. - Pressure-Dependent Arrhenius Rate Expressions (P-Log) ----------------------------------------------------- @@ -302,7 +301,6 @@ directive. In the YAML format, surface reactions are identified by the presence of surface species and support several :ref:`additional options `. - Sticking Coefficients ~~~~~~~~~~~~~~~~~~~~~ diff --git a/pages/science/species.rst b/pages/science/species.rst index 9d0173a77..367cc1a38 100644 --- a/pages/science/species.rst +++ b/pages/science/species.rst @@ -25,7 +25,6 @@ An element can be defined in the CTI format using the :cti:class:`element` entry, or in the YAML format by adding entries to the :ref:`elements ` section of the input file. - Species ======= @@ -35,7 +34,6 @@ A species can be defined in the CTI format using the :cti:class:`species` entry, or in the YAML format by adding an entry to the :ref:`species ` section of the input file. - Species Name ------------ @@ -145,7 +143,6 @@ A NASA-7 parameterization can be defined in the CTI format using the :cti:class:`NASA` entry, or in the YAML format by specifying :ref:`NASA7 ` as the ``model`` in the species ``thermo`` field. - The NASA 9-Coefficient Polynomial Parameterization -------------------------------------------------- @@ -173,7 +170,6 @@ A NASA-9 parameterization can be defined in the CTI format using the :cti:class:`NASA9` entry, or in the YAML format by specifying :ref:`NASA9 ` as the ``model`` in the species ``thermo`` field. - The Shomate Parameterization ---------------------------- diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index a239851c1..bd15a0be5 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -19,7 +19,6 @@ present in the input file(s). The phase entry specifies the elements and species present in the phases, and the models to be used for computing thermodynamic, kinetic, and transport properties. - Naming the Phase ---------------- @@ -28,7 +27,6 @@ within the file among all phase definitions of any type. Phases are referenced by name when importing them. The ``name`` is also used to identify the phase within multiphase mixtures or at phase boundaries. - Setting the Thermodynamic Model ------------------------------- @@ -62,7 +60,6 @@ field. Supported models are: Some thermodynamic models use additional fields in the ``phase`` entry, which are described in the linked documentation. - Declaring the Elements ---------------------- @@ -107,7 +104,6 @@ Example: The order of the elements specified in the input file determines the order of the elements in the phase when it is imported by Cantera. - Declaring the Species --------------------- @@ -154,7 +150,6 @@ hydrogen or oxygen, the phase definition could contain: species: all skip-undeclared-elements: true - Setting the Kinetics Model -------------------------- @@ -167,7 +162,6 @@ Supported model strings are: If omitted, no kinetics model will be used. - Declaring the Reactions ----------------------- @@ -227,7 +221,6 @@ specified in the ``transport`` field. Supported models are: - `unity-Lewis-number <{{% ct_docs doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details %}}>`__ - `water <{{% ct_docs doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details %}}>`__ - Setting the Initial State ------------------------- @@ -272,7 +265,6 @@ Examples: C3H8: 0.1 CO2: 0.7 - Examples -------- diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst index 0caaa4733..0eaf8112a 100644 --- a/pages/tutorials/yaml/reactions.rst +++ b/pages/tutorials/yaml/reactions.rst @@ -171,7 +171,6 @@ factor depend on the sum of the reaction orders, which may not be an integer. Note that you can change reaction orders only for irreversible reactions. - Negative Reaction Orders ~~~~~~~~~~~~~~~~~~~~~~~~ @@ -187,7 +186,6 @@ field to the reaction entry, e.g.: orders: {C8H18: -0.25, O2: 1.75} negative-orders: true - Non-reactant Orders ~~~~~~~~~~~~~~~~~~~ diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index 5544c18ac..12f96307a 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -107,7 +107,6 @@ Examples: composition: {Y: 1, Ba: 2, Cu: 3, O: 6.5} # stoichiometric YBCO composition: {} # A surface species representing an empty site - Thermodynamic Properties ------------------------ diff --git a/pages/tutorials/yaml/yaml-format.rst b/pages/tutorials/yaml/yaml-format.rst index 2e2b347b5..ef19e237e 100644 --- a/pages/tutorials/yaml/yaml-format.rst +++ b/pages/tutorials/yaml/yaml-format.rst @@ -94,7 +94,6 @@ Sequences can also be nested. The following examples are all equivalent: - - 3 - 4 - Mappings -------- From 620161aa2586e83da5bb03d1d7b7142c6e47b311 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 2 Jan 2020 13:03:07 -0500 Subject: [PATCH 26/45] Re-order composition and state paragraphs --- pages/tutorials/yaml/phases.rst | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index bd15a0be5..204d98212 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -228,15 +228,6 @@ The state of a phase can be set using two properties to set the thermodynamic state, plus the composition. This state is specified as a mapping in the ``state`` field of ``phase`` entry. -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 in terms of two of the following properties, with the valid property pairs deplending on the phase model: @@ -248,6 +239,15 @@ with the valid property pairs deplending on the phase model: - ``specific-volume`` or ``V`` - ``density`` or ``D`` +The composition can be set using one of the following fields, depending on the +phase type. The composition is specified as a mapping of species names to +values. Where necessary, the values will be automatically normalized. + +- ``mass-fractions`` or ``Y`` +- ``mole-fractions`` or ``X`` +- ``coverages`` +- ``molalities`` or ``M`` + Examples: .. code:: yaml From 684026f44f866c27453edace7a8981b314cc02b4 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 2 Jan 2020 16:30:09 -0500 Subject: [PATCH 27/45] Add ck2yaml tutorial --- pages/tutorials/ck2yaml-tutorial.rst | 257 +++++++++++++++++++++++++++ pages/tutorials/input-files.rst | 95 ++++++---- 2 files changed, 318 insertions(+), 34 deletions(-) create mode 100644 pages/tutorials/ck2yaml-tutorial.rst diff --git a/pages/tutorials/ck2yaml-tutorial.rst b/pages/tutorials/ck2yaml-tutorial.rst new file mode 100644 index 000000000..bc1bab347 --- /dev/null +++ b/pages/tutorials/ck2yaml-tutorial.rst @@ -0,0 +1,257 @@ +.. title: Converting Chemkin Format Files +.. slug: ck2yaml-tutorial +.. has_math: true + +.. jumbotron:: + + .. raw:: html + +

Converting Chemkin-format files

+ + .. class:: lead + + If you want to convert a Chemkin-format file to YAML format, or you're + having errors when you try to do so, this section will help. + +ck2yaml +------- + +Many existing reaction mechanism files are in "CK format," by which we mean +the input file format developed for use with the Chemkin-II software package +as specified in the report describing the Chemkin software [SAND89]_. + +Cantera comes with a converter utility program ``ck2yaml`` (or ``ck2yaml.py``) +that converts CK format into Cantera format. This program should be run from +the command line first to convert any CK files you plan to use into Cantera +format (YAML format). *(New in Cantera 2.5)* + +Usage: + +.. code:: bash + + ck2yaml [--input=] + [--thermo=] + [--transport=] + [--surface=] + [--name=] + [--output=] + [--permissive] + +Each of the terms in square brackets is an option that can be passed on the +command line to ``ck2yaml``. + +- ``--input``: This is the chemistry input file, containing a list of all the + element names that are used, a list of all the species names, and a list of + all the reactions to be considered between the species. This file can also + optionally contain thermodynamic information for the species. + +- ``--thermo``: If the ``--input`` file does not contain the thermodynamic data, + a separate file containing this information must be specified to the + `--thermo`` option. + +- ``--transport``: The ``--input`` file can also optionally contain transport + information for the species. If it does not, and the user wishes to use a part + of Cantera that relies on some transport properties, the ``--transport`` + option must be used to specify the file containing all the transport data for + the species. + +- ``--surface``: For surface mechanisms, this file defines the surface species + and reactions occurring on the surface. Gas phase species and reactions are + defined in the file specified by the ``--input`` option. + +- ``--name```: This specifies the name of the phase in the resulting YAML file. + The default is ``gas``. + +- ``--output``: Specifies the output file name. By default, the output file name + is the input file name with the extension changed to ``.yaml``. + +- ``--permissive``: This option allows certain recoverable parsing errors (e.g. + duplicate thermo data) to be ignored. + +Example: + +.. code:: bash + + ck2yaml --input=chem.inp --thermo=therm.dat --transport=tran.dat + +If the ``ck2yaml`` script is not on your path but the Cantera Python module is, +``ck2yaml`` can also be used by running: + +.. code:: bash + + python -m cantera.ck2yaml --input=chem.inp --thermo=therm.dat --transport=tran.dat + +An input file containing only species definitions (which can be referenced from +phase definitions in other input files) can be created by specifying only a +thermo file. + +Many existing CK format files cause errors in ``ck2yaml`` when they are +processed. Some of these errors may be avoided by specifying the +``--permissive`` option. This option allows certain recoverable parsing errors +(e.g., duplicate transport or thermodynamic data) to be ignored. Other errors +may be caused by incorrect formatting of lines in one or more of the input +files. + +Debugging common errors in CK files +----------------------------------- + +When ``ck2yaml`` encounters an error, it attempts to print the surrounding +information to help you to locate the error. Many of the most common errors +are due to an inconsistency of the input files from their standard, as defined +in the report for Chemkin referenced above. These errors include: + +* Each section of the input files must be started with a keyword representing that + section and ending with the keyword ``END``. Keywords that may begin a section + include: + + - ``ELEMENTS`` or ``ELEM`` + - ``SPECIES`` or ``SPEC`` + - ``THERMO`` or ``THERMO ALL`` + - ``REACTIONS`` or ``REAC`` + - ``TRANSPORT`` + +* The thermodynamic data is read in a fixed format. This means that each + column of the input has a particular meaning. *Many common errors are + generated because information is missing or in the wrong column. Check + thoroughly for extraneous or missing spaces.* The format for each + thermodynamic entry should be as follows:: + + N2 N 2 G200.000 6000.000 1000.00 1 + 2.95258000E+00 1.39690000E-03-4.92632000E-07 7.86010000E-11-4.60755000E-15 2 + -9.23949000E+02 5.87189000E+00 3.53101000E+00-1.23661000E-04-5.02999000E-07 3 + 2.43531000E-09-1.40881000E-12-1.04698000E+03 2.96747000E+00 4 + + The following table is adapted from the Chemkin manual [SAND89]_ to describe the + column positioning of each required part of the entry. Empty columns should be + filled with spaces. + + +---------+-------------------------------------+--------+ + |Line No. | Contents | Column | + +=========+=====================================+========+ + | 1 | Species Name | 1–18 | + +---------+-------------------------------------+--------+ + | 1 | Date (Optional) | 19–24 | + +---------+-------------------------------------+--------+ + | 1 | Atomic Symbols and formula | 25–44 | + +---------+-------------------------------------+--------+ + | 1 | Phase of species (S, L, G) | 45 | + +---------+-------------------------------------+--------+ + | 1 | Low temperature | 46–55 | + +---------+-------------------------------------+--------+ + | 1 | High temperature | 56–65 | + +---------+-------------------------------------+--------+ + | 1 | Common temperature | 66–73 | + +---------+-------------------------------------+--------+ + | 1 | Additional Atomic Symbols | 74–78 | + +---------+-------------------------------------+--------+ + | 1 | The integer ``1`` | 80 | + +---------+-------------------------------------+--------+ + | 2 | Coefficients :math:`a_1` | 1–75 | + | | to :math:`a_5` for the upper | | + | | temperature interval | | + +---------+-------------------------------------+--------+ + | 2 | The integer ``2`` | 80 | + +---------+-------------------------------------+--------+ + | 3 | Coefficients :math:`a_6,\ a_7` | 1–75 | + | | for the upper temperature interval, | | + | | and :math:`a_1,\ a_2,\ a_3` for | | + | | the lower temperature interval | | + +---------+-------------------------------------+--------+ + | 3 | The integer ``3`` | 80 | + +---------+-------------------------------------+--------+ + | 4 | Coefficients :math:`a_4` through | 1–60 | + | | :math:`a_7` for the lower | | + | | temperature interval | | + +---------+-------------------------------------+--------+ + | 4 | The integer ``4`` | 80 | + +---------+-------------------------------------+--------+ + + The first 18 columns are reserved for the species name. The name assigned + to the species in the thermodynamic data must be the same as the species + name defined in the ``SPECIES`` section. If the species name is shorter + than 18 characters, the rest of the characters should be filled by spaces. + The next six columns (columns 19–24) are typically used to write a date; + they are not used further. The next 20 columns (25–44) are used to + specify the elemental composition of the species. In column 45, the phase + of the species (``S``, ``L``, or ``G`` for solid, liquid, or gas + respectively) should be specified. The next 28 columns are reserved for + the temperatures that delimit the ranges of the polynomials specified on + the next several lines. The first two temperatures have a width of 10 + columns each (46–55 and 56–65), and represent the lowest temperature and + highest temperature for which the polynomials are valid. The last + temperature has a width of 8 columns (66–73) and is the "common" + temperature, where the switch from low to high occurs. The next 5 columns + (74–78) are reserved for atomic symbols and are usually left blank for + the default behavior. Column 79 is blank and finally, the row is ended in + column 80 with the integer ``1``. + + The next three lines of the thermodynamic entry have a similar format. + They contain the coefficients of the polynomial described in + :ref:`sec-thermo-models` for the NASA 7-coefficient polynomial formulation. + The second row of the thermo entry (the first after the information row) + contains the first five coefficients that apply the the temperature range + between the midpoint and the upper limit. 15 columns are alloted for each + coefficient (for a total of 75 columns), with no spaces between them. + Although the entry above shows spaces between positive coefficients, it is + to be noted that this is done only for formatting consistency with other + lines that contain negative numbers. After the coefficients, four spaces + in columns 76–79 are followed by the integer ``2`` in column 80. On the + next line, the last two coefficients for the upper temperature range and + the first three coefficients for the lower temperature range are + specified. Once again, this takes up the first 75 columns, columns 76–79 + are blank, and the integer ``3`` is in column 80. Finally, on the last + line of a particular entry, the last four coefficients of the lower + temperature range are specified in columns 1–60, 19 blank spaces are + present, and the integer ``4`` is in column 80. The 19 blank spaces in the + last line are part of the standard. However, since the original Chemkin + interpreter ignored those spaces, researchers began using that space to + store additional information that was not necessary for the input file. + Although these numbers create an error in ``ck2yaml`` if present, they are + harmless and can be ignored by using the ``--permissive`` option. + +* It may be the case that scientific formatted numbers are missing the ``E``. + In this case, numbers often show up as ``1.1+01``, when they should be + ``1.1E+01``. You can fix this with a simple Regular Expression find and + replace:: + + Find: (\d+\.\d+)([+-]\d+) + Replace: \1E\2 + +* The transport data file also has a specified format, as described in + [SAND98]_, although the format is not as strict as for the thermodynamic + entries. In particular, the first 15 columns of a line are reserved for + the species name. *One common source of errors is a species that is present + in the transport data file, but not in the thermodynamic data or in + the species list; or a species that is present in the species list but + not the transport data file.* The rest of the columns on a given line have + no particular format, but must be present in the following order: + + +------------------+------------------------------------------------------------+ + | Parameter Number | Parameter Name | + +==================+============================================================+ + | 1 | An integer with value 0, 1, or 2 indicating | + | | monatomic, linear, or non-linear molecular geometry. | + +------------------+------------------------------------------------------------+ + | 2 | The Lennard-Jones potential well depth | + | | :math:`\varepsilon/k_B` in Kelvin | + +------------------+------------------------------------------------------------+ + | 3 | The Lennard-Jones collision diameter :math:`\sigma` | + | | in Angstrom | + +------------------+------------------------------------------------------------+ + | 4 | The dipole moment :math:`\mu` in Debye | + +------------------+------------------------------------------------------------+ + | 5 | The polarizability :math:`\alpha` in Angstroms cubed | + +------------------+------------------------------------------------------------+ + | 6 | The rotational relaxation collision number | + | | :math:`Z_{rot}` at 298 K | + +------------------+------------------------------------------------------------+ + + Another common error is if all 6 of these numbers are not present for every + species. + +.. [SAND89] See R. J. Kee, F. M. Rupley, and J. A. Miller, Sandia National + Laboratories Report SAND89-8009 (1989). + http://www.osti.gov/scitech/biblio/5681118 + +.. [SAND98] See R. J. Kee, G. Dixon-Lewis, J. Warnatz, M. E. Coltrin, J. A. Miller, + H. K. Moffat, Sandia National Laboratories Report SAND86-8246B (1998). diff --git a/pages/tutorials/input-files.rst b/pages/tutorials/input-files.rst index 7faa64623..1b592b282 100644 --- a/pages/tutorials/input-files.rst +++ b/pages/tutorials/input-files.rst @@ -18,6 +18,8 @@ The required input files can be provided via one of several methods: - Use one of the pre-existing input files provided with Cantera - Convert a pre-existing mechanism from Chemkin (CK) format to Cantera (CTI) format +- Convert a pre-existing mechanism from Chemkin (CK) format to YAML format *(New + in Cantera 2.5)* - Create your own CTI file, either from scratch (not recommended) or by editing an existing file - Create your own YAML file from scratch or by editing an existing file *(New in Cantera 2.5)* @@ -59,61 +61,86 @@ There are three primary options for creating a new Cantera input file: .. container:: container - .. container:: card-deck + .. row:: - .. container:: card + .. container:: card-deck - .. container:: - :tagname: a - :attributes: href=ck2cti-tutorial.html - title="Chemkin File Conversion" + .. container:: card - .. container:: card-header section-card + .. container:: + :tagname: a + :attributes: href=ck2cti-tutorial.html + title="Chemkin File Conversion (CTI)" - Conversion from Chemkin + .. container:: card-header section-card - .. container:: card-body + Conversion from Chemkin to CTI - .. container:: card-text + .. container:: card-body - Convert a Chemkin-formatted ('CK') file to the Cantera input format. + .. container:: card-text - .. container:: card + Convert a Chemkin-formatted ('CK') file to the Cantera input + format (CTI). - .. container:: - :tagname: a - :attributes: href="cti/defining-phases.html" - title="Defining Phases in CTI" + .. container:: card - .. container:: card-header section-card + .. container:: + :tagname: a + :attributes: href=ck2yaml-tutorial.html + title="Chemkin File Conversion (YAML)" - Create a new CTI file + .. container:: card-header section-card - .. container:: card-body + Conversion from Chemkin to YAML - .. container:: card-text + .. container:: card-body - Create a completely new mechanism, by defining new species, - phases, and/or reactions, using the CTI format. + .. container:: card-text - .. container:: card + Convert a Chemkin-formatted ('CK') file to the Cantera YAML + format. *(New in Cantera 2.5)* - .. container:: - :tagname: a - :attributes: href="yaml/defining-phases.html" - title="Defining Phases in YAML" + .. row:: - .. container:: card-header section-card + .. container:: card-deck - Create a new YAML file + .. container:: card - .. container:: card-body + .. container:: + :tagname: a + :attributes: href="cti/defining-phases.html" + title="Defining Phases in CTI" - .. container:: card-text + .. container:: card-header section-card - Create a completely new mechanism, by defining new species, - phases, and/or reactions, using the YAML format. - *(New in Cantera 2.5)* + Create a new CTI file + + .. container:: card-body + + .. container:: card-text + + Create a completely new mechanism, by defining new species, + phases, and/or reactions, using the CTI format. + + .. container:: card + + .. container:: + :tagname: a + :attributes: href="yaml/defining-phases.html" + title="Defining Phases in YAML" + + .. container:: card-header section-card + + Create a new YAML file + + .. container:: card-body + + .. container:: card-text + + Create a completely new mechanism, by defining new species, + phases, and/or reactions, using the YAML format. + *(New in Cantera 2.5)* Understanding Input File Syntax =============================== From 954df62d86602905a8ae5d62a82cbf1ad6fc4a64 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 2 Jan 2020 17:48:15 -0500 Subject: [PATCH 28/45] Add basic tutorial for cti2yaml and ctml2yaml --- pages/tutorials/input-files.rst | 23 ++++++ pages/tutorials/legacy2yaml-tutorial.rst | 95 ++++++++++++++++++++++++ 2 files changed, 118 insertions(+) create mode 100644 pages/tutorials/legacy2yaml-tutorial.rst diff --git a/pages/tutorials/input-files.rst b/pages/tutorials/input-files.rst index 1b592b282..653dd0f77 100644 --- a/pages/tutorials/input-files.rst +++ b/pages/tutorials/input-files.rst @@ -142,6 +142,29 @@ There are three primary options for creating a new Cantera input file: phases, and/or reactions, using the YAML format. *(New in Cantera 2.5)* + .. row:: + + .. container:: card-deck + + .. container:: card + + .. container:: + :tagname: a + :attributes: href="legacy2yaml.html" + title="Converting CTI and XML input files to YAML" + + .. container:: card-header section-card + + Convert CTI and XML input files to YAML + + .. container:: card-body + + .. container:: card-text + + Convert existing Cantera mechanisms in the legacy CTI or XML + formats to the YAML format. *(New in Cantera 2.5)* + + Understanding Input File Syntax =============================== diff --git a/pages/tutorials/legacy2yaml-tutorial.rst b/pages/tutorials/legacy2yaml-tutorial.rst new file mode 100644 index 000000000..6c368a8b7 --- /dev/null +++ b/pages/tutorials/legacy2yaml-tutorial.rst @@ -0,0 +1,95 @@ +.. title: Converting CTI and XML input files to YAML +.. slug: legacy2yaml +.. has_math: true + +.. jumbotron:: + + .. raw:: html + +

Converting CTI and XML input files to YAML

+ + .. class:: lead + + If you want to convert an existing, legacy CTI or XML input file to the + YAML format, this section will help. + +cti2yaml +-------- + +Cantera comes with a converter utility ``cti2yaml`` (or ``cti2yaml.py``) that +converts legacy CTI format mechanisms into the new YAML format introduced in +Cantera 2.5. This program can be run from the command line to convert files to +the YAML format. *(New in Cantera 2.5)* + +Usage: + +.. code:: bash + + cti2yaml [-h] input [output] + +The ``input`` argument is required, and specifies the name of the input file to +be converted. The optional ``output`` argument specifies the name of the new +output file. If ``output`` is not specified, then the output file will have the +same name as the input file, with the extension replaced with ``.yaml``. + +Example: + +.. code:: bash + + cti2yaml mymech.cti + +will generate the output file ``mymech.yaml``. + +If the ``cti2yaml`` script is not on your path, but the Cantera Python module +is, ``cti2yaml`` can be used by running: + +.. code:: bash + + python -m cantera.cti2yaml mymech.cti + +It is not necessary to use ``cti2yaml`` to convert any of the CTI input files +included with Cantera. YAML versions of these files are already included with +Cantera. + +For input files where you have both the CTI and XML versions, ``cti2yaml`` is +recommended over ``ctml2yaml``. And in cases where the mechanism was originally +converted from a CK-format mechanism, it is recommended to use ``ck2yaml`` if +the original input files are available. + +ctml2yaml +--------- + +Cantera comes with a converter utility ``ctml2yaml`` (or ``ctml2yaml.py``) that +converts legacy XML (CTML) format mechanisms into the new YAML format introduced +in Cantera 2.5. This program can be run from the command line to convert files +to the YAML format. *(New in Cantera 2.5)* + +Usage: + +.. code:: bash + + ctml2yaml [-h] input [output] + +The ``input`` argument is required, and specifies the name of the input file to +be converted. The optional ``output`` argument specifies the name of the new +output file. If ``output`` is not specified, then the output file will have the +same name as the input file, with the extension replaced with ``.yaml``. + +Example: + +.. code:: bash + + ctml2yaml mymech.xml + +will generate the output file ``mymech.yaml``. + +If the ``ctml2yaml`` script is not on your path, but the Cantera Python module +is, ``ctml2yaml`` can be used by running: + +.. code:: bash + + python -m cantera.cti2yaml mymech.xml + +It is not necessary to use ``ctml2yaml`` to convert any of the XML input files +included with Cantera. YAML versions of these files are already included with +Cantera. From 9ad31449c3ce42a8d13af7fd9763cc89c0ad8ac9 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Fri, 3 Jan 2020 12:29:17 -0500 Subject: [PATCH 29/45] Add short descriptions for all models listed in the YAML tutorial --- pages/tutorials/yaml/phases.rst | 106 ++++++++++++++++++++--------- pages/tutorials/yaml/reactions.rst | 21 ++++-- pages/tutorials/yaml/species.rst | 39 +++++++---- 3 files changed, 113 insertions(+), 53 deletions(-) diff --git a/pages/tutorials/yaml/phases.rst b/pages/tutorials/yaml/phases.rst index 204d98212..2419b2765 100644 --- a/pages/tutorials/yaml/phases.rst +++ b/pages/tutorials/yaml/phases.rst @@ -33,29 +33,54 @@ Setting the Thermodynamic Model The thermodynamic model used to represent a phase is specified in the ``thermo`` field. Supported models are: - - :ref:`binary-solution-tabulated ` - - :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:`liquid-water-IAPWS95 ` - - :ref:`Margules ` - - :ref:`Maskell-solid-solution ` - - :ref:`electron-cloud ` - - :ref:`pure-fluid ` - - :ref:`Redlich-Kister ` - - :ref:`Redlich-Kwong ` +- :ref:`binary-solution-tabulated `: A + binary mixture where the excess enthalpy and entropy are interpolated; *New in + Cantera 2.5.0* between tabulated values as a function of mole fraction +- :ref:`compound-lattice `: A phase that is comprised + of a fixed additive combination of other lattice phases +- :ref:`constant-density `: A phase with a fixed + density, regardless of composition; *Deprecated in Cantera 2.5.0* +- :ref:`Debye-Huckel `: A dilute liquid electrolyte which + obeys the Debye-Hückel formulation for nonideality +- :ref:`edge `: A one-dimensional edge between two surfaces +- :ref:`fixed-chemical-potential `: An + incompressible, single-species phase with a fixed value for the chemical + potential +- :ref:`fixed-stoichiometry `: An incompressible, + single-species phase +- :ref:`HMW-electrolyte `: A dilute or concentrated + liquid electrolyte which obeys the Pitzer formulation for nonideality +- :ref:`ideal-gas `: A mixture which obeys the ideal gas law +- :ref:`ideal-gas-VPSS `: An ideal gas; Uses "variable + pressure standard state" methods for calculating thermodynamic properties +- :ref:`ideal-molal-solution `: An ideal solution + based on the mixing-rule assumption that all molality-based activity + coefficients are equal to one +- :ref:`ideal-condensed ` +- :ref:`ideal-solution-VPSS `: An ideal solution; + Uses "variable pressure standard state" methods for calculating thermodynamic + properties +- :ref:`ideal-surface `: A surface between two bulk + phases +- :ref:`ions-from-neutral-molecule `: A + phase for representing ionic species based on another phase where those ions + are components of neutral molecules +- :ref:`lattice `: A simple model for an incompressible + lattice of solid atoms +- :ref:`liquid-water-IAPWS95 `: An implementation + of the IAPWS95 equation of state for water, for the liquid region only +- :ref:`Margules `: A model that employs the Margules + approximation for the excess Gibbs free energy +- :ref:`Maskell-solid-solution `: A condensed, + binary, non-ideal solution +- :ref:`electron-cloud `: A phase representing free + electrons in a metal +- :ref:`pure-fluid `: A phase representing one of several + pure substances including liquid, vapor, two-phase, and supercritical regions +- :ref:`Redlich-Kister `: A model that employs the + Redlich-Kister approximation for the excess Gibbs free energy +- :ref:`Redlich-Kwong `: A multi-species mixture obeying + the Redlich-Kwong equation of state. Some thermodynamic models use additional fields in the ``phase`` entry, which are described in the linked documentation. @@ -156,9 +181,9 @@ Setting the Kinetics Model The kinetics model to be used, if any, is specified in the ``kinetics`` field. Supported model strings are: - - `gas <{{% ct_docs doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details %}}>`__ - - `surface <{{% ct_docs doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details %}}>`__ - - `edge <{{% ct_docs doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details %}}>`__ +- `gas <{{% ct_docs doxygen/html/de/dae/classCantera_1_1GasKinetics.html#details %}}>`__ +- `surface <{{% ct_docs doxygen/html/d1/d72/classCantera_1_1InterfaceKinetics.html#details %}}>`__ +- `edge <{{% ct_docs doxygen/html/d0/df0/classCantera_1_1EdgeKinetics.html#details %}}>`__ If omitted, no kinetics model will be used. @@ -212,14 +237,27 @@ Setting the Transport Model To enable transport property calculation, the transport model to be used can be specified in the ``transport`` field. Supported models are: - - `high-pressure <{{% ct_docs doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details %}}>`__ - - `ionized-gas <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details %}}>`__ - - `mixture-averaged <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__ - - `mixture-averaged-CK <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__ - - `multicomponent <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__ - - `multicomponent-CK <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__ - - `unity-Lewis-number <{{% ct_docs doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details %}}>`__ - - `water <{{% ct_docs doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details %}}>`__ +- `high-pressure <{{% ct_docs doxygen/html/d9/d63/classCantera_1_1HighPressureGasTransport.html#details %}}>`__: + A model for high-pressure gas transport properties based on a method of + corresponding states +- `ionized-gas <{{% ct_docs doxygen/html/d4/d65/classCantera_1_1IonGasTransport.html#details %}}>`__: + A model implementing the Stockmayer-(n,6,4) model for transport of ions in + a gas +- `mixture-averaged <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__: + The mixture-averaged transport model for ideal gases +- `mixture-averaged-CK <{{% ct_docs doxygen/html/d9/d17/classCantera_1_1MixTransport.html#details %}}>`__: + The mixture-averaged transport model for ideal gases, using polynomial + fits corresponding to Chemkin-II +- `multicomponent <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__: + The multicomponent transport model for ideal gases +- `multicomponent-CK <{{% ct_docs doxygen/html/df/d7c/classCantera_1_1MultiTransport.html#details %}}>`__: + The multicomponent transport model for ideal gases, using polynomial fits + corresponding to Chemkin-II +- `unity-Lewis-number <{{% ct_docs doxygen/html/d3/dd6/classCantera_1_1UnityLewisTransport.html#details %}}>`__: + A transport model for ideal gases, where diffusion coefficients for all + species are set so that the Lewis number is 1 +- `water <{{% ct_docs doxygen/html/df/d1f/classCantera_1_1WaterTransport.html#details %}}>`__: + A transport model for pure water applicable in both liquid and vapor phases Setting the Initial State ------------------------- diff --git a/pages/tutorials/yaml/reactions.rst b/pages/tutorials/yaml/reactions.rst index 0eaf8112a..114aa9542 100644 --- a/pages/tutorials/yaml/reactions.rst +++ b/pages/tutorials/yaml/reactions.rst @@ -50,12 +50,21 @@ Reaction type The type of the rate coefficient parameterization may be specified in the ``type`` field of the ``reaction`` entry. Available reaction types are: - - :ref:`elementary ` - - :ref:`three-body ` - - :ref:`falloff ` - - :ref:`chemically-activated ` - - :ref:`pressure-dependent-Arrhenius ` - - :ref:`Chebyshev ` +- :ref:`elementary `: A reaction with a rate constant + parameterized by a modified Arrhenius expression +- :ref:`three-body `: A reaction involving a third-body + collision +- :ref:`falloff `: A pressure-dependent reaction where the + rate depends on the third-body concentration at low pressure but not at high + pressure +- :ref:`chemically-activated `: A + pressure-dependent reaction where the rate depends on the third-body + concentration at high pressure but not at low pressure +- :ref:`pressure-dependent-Arrhenius `: A + reaction rate parameterized by logarithmically interpolating between modified + Arrhenius expressions at different pressures +- :ref:`Chebyshev `: A reaction rate parameterized by a + bivariate Chebyshev polynomial in pressure and temperature Additional parameters defining the rate constant for each of these reaction types are described in the documentation linked above. diff --git a/pages/tutorials/yaml/species.rst b/pages/tutorials/yaml/species.rst index 12f96307a..3e405df02 100644 --- a/pages/tutorials/yaml/species.rst +++ b/pages/tutorials/yaml/species.rst @@ -119,11 +119,16 @@ entry. The parameterization used to provide this information is specified by the ``model`` field of the ``thermo`` field. The models available are: - - :ref:`NASA7 ` - - :ref:`NASA9 ` - - :ref:`Shomate ` - - :ref:`constant-cp ` - - :ref:`piecewise-Gibbs ` +- :ref:`NASA7 `: 7-coefficient NASA polynomials in one or two + temperature regions +- :ref:`NASA9 `: 9-coefficient NASA polynomials in one or more + temperature regions +- :ref:`Shomate `: Shomate polynomials in one or two + temperature regions +- :ref:`constant-cp `: Constant heat capacity +- :ref:`piecewise-Gibbs `: Interpolation between + tabulated Gibbs free energies using a constant heat capacity in each + temperature interval The fields used by each model are described and examples provided in the linked documentation. @@ -137,14 +142,22 @@ the ``equation-of-state`` field of each ``species`` entry, with the type of parameterization used specified by the ``model`` field of the ``equation-of-state`` field. The models available are: - - :ref:`constant-volume ` - - :ref:`density-temperature-polynomial ` - - :ref:`HKFT ` - - :ref:`ideal-gas ` - - :ref:`ions-from-neutral-molecule ` - - :ref:`liquid-water-IAPWS95 ` - - :ref:`molar-volume-temperature-polynomial ` - - :ref:`Redlich-Kwong ` +- :ref:`constant-volume `: A fixed value of mass + density, molar density, or molar volume +- :ref:`density-temperature-polynomial `: + Mass density parameterized using a cubic polynomial in temperature +- :ref:`HKFT `: The Helgeson-Kirkham-Flowers-Tanger model for + aqueous species +- :ref:`ideal-gas `: A species following the ideal gas + law +- :ref:`ions-from-neutral-molecule `: Used with + the `ions-from-neutral-molecule` phase model +- :ref:`liquid-water-IAPWS95 `: The IAPWS95 + equation of state for water, applied only in the liquid region +- :ref:`molar-volume-temperature-polynomial `: + Molar volume parameterized using a cubic polynomial in temperature +- :ref:`Redlich-Kwong `: + A species which follows the Redlich-Kwong equation of state The fields used by each model are described and examples provided in the linked documentation. From 8b82b1fe985a63848bc4c5aa7797799f20ba5b13 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Tue, 7 Jan 2020 11:01:57 -0500 Subject: [PATCH 30/45] Document dependency on ruamel.yaml --- pages/compiling/dependencies.rst | 7 +++++++ pages/compiling/installation-reqs.rst | 12 ++++++++---- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/pages/compiling/dependencies.rst b/pages/compiling/dependencies.rst index ca4c98bbb..3289cf0fc 100644 --- a/pages/compiling/dependencies.rst +++ b/pages/compiling/dependencies.rst @@ -138,6 +138,13 @@ Optional Programs * Required version >=0.23 to build the Python module. Must be installed for the same Python where SCons is installed. +* `Ruamel.yaml `__ + + * Required to convert input files from Chemkin, CTI, and XML to the YAML + format + * Known to work with versions 0.15.42, 0.15.87, and 0.16.5 + * Expected to work with versions >= 0.15.0 + * `3to2 `__ * Used to convert Python examples to Python 2 syntax. diff --git a/pages/compiling/installation-reqs.rst b/pages/compiling/installation-reqs.rst index 65c4379f6..bc0b8a3fb 100644 --- a/pages/compiling/installation-reqs.rst +++ b/pages/compiling/installation-reqs.rst @@ -84,7 +84,7 @@ Conda Requirements .. code:: bash - conda create --name cantera python=3 scons cython boost numpy + conda create --name cantera python=3 scons cython boost numpy ruamel_yaml conda activate cantera * (Optional) If you also want to build the documentation, after you've created the environment and @@ -230,7 +230,7 @@ Ubuntu & Debian * In addition to the general packages, building the Python 3 module also requires:: - cython python3 python3-dev python3-setuptools python3-numpy + cython python3 python3-dev python3-setuptools python3-numpy python3-ruamel.yaml * In addition to the general packages, building the Fortran module also requires:: @@ -274,7 +274,7 @@ Fedora & RHEL * In addition to the general packages, building the Python 3 module also requires:: - python3 python3-setuptools python3-devel Cython python3-numpy + python3 python3-setuptools python3-devel Cython python3-numpy python3-ruamel-yaml * In addition to the general packages, building the Fortran module also requires:: @@ -320,7 +320,7 @@ OpenSUSE & SUSE Linux Enterprise * In addition to the general packages, building the Python 3 module also requires:: - python-Cython python3 python3-devel python3-setuptools python3-numpy python3-numpy-devel + python-Cython python3 python3-devel python3-setuptools python3-numpy python3-numpy-devel python3-ruamel.yaml * In addition to the general packages, building the Fortran module also requires:: @@ -509,6 +509,10 @@ Windows Requirements and Python X.Y (indicated by ``cpXY`` in the file name), where X and Y are the major and minor versions of Python. + * Ruamel.yaml + + * `pip install ruamel.yaml` + * In addition to the general software, building the MATLAB toolbox also requires: * MATLAB version later than 2009a From 2ce56e8f3b337060df44864f5955b1236220fb63 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Wed, 8 Jan 2020 18:28:05 -0500 Subject: [PATCH 31/45] Clarify that main documentation page is for stable version --- pages/documentation/index.html | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/pages/documentation/index.html b/pages/documentation/index.html index 58a378742..81095758b 100644 --- a/pages/documentation/index.html +++ b/pages/documentation/index.html @@ -10,7 +10,9 @@

Documentation

Sometimes you just need a little more detail. You'll find documentation for - (almost) every function in Cantera right here. + (almost) every function in Cantera right here. This is the documentation for + the current stable release, Cantera 2.4.0. For other versions, see the links + at the bottom of the page.