Merge pull request #179 from decaluwe/science_update

WIP: Reorganize Science section.

pages/science/index.rst

@@ -21,12 +21,11 @@
 
    <h2 class="display-4">Chemical Kinetic Theory</h2>
 
-These sections describe some of the theory underpinning the various ways that Cantera models phases
+These sections describe some of the fundamental scientific theory underpinning the ways that Cantera models phases
 of matter. This involves calculations for thermodynamic and transport properties and chemical
 reaction rates. The above information gives some insight into the basic constitutive models
-available in Cantera: capabilities for calculating the basic properties of
-phases of matter, which can be extended to model a wide range of science and
-technology applications.
+available in Cantera: capabilities for calculating the basic thermodynamic, chemical kinetic, and transport properties of phases of matter, which can be
+extended to model a wide range of science and technology applications.
 
 .. container:: container
    :tagname: section
@@ -37,56 +36,55 @@ technology applications.
 
          .. container::
             :tagname: a
-            :attributes: href=phases.html
-                         title=Phases
+            :attributes: href=thermodynamics.html
+                         title=Thermodynamics
 
             .. container:: card-header section-card
                :tagname: div
 
-               Phases
+               Thermodynamics
 
          .. container:: card-body
 
             .. container:: card-text
 
-               The theory behind some of Cantera's phase models.
+               The theory behind how Cantera calculates species and phase thermodynamic properties.
 
       .. container:: card
 
          .. container::
             :tagname: a
-            :attributes: href=science-species.html
-                         title=Species
+            :attributes: href=kinetics.html
+                         title=Kinetics
 
             .. container:: card-header section-card
                :tagname: div
 
-               Species
+               Kinetics and Reaction Rates
 
          .. container:: card-body
 
             .. container:: card-text
 
-               The models Cantera uses to calculate species properties (thermodynamic and
-               transport).
+               The models and equations that Cantera uses to calculate chemical reaction rates.
 
       .. container:: card
 
          .. container::
             :tagname: a
-            :attributes: href=reactions.html
-                         title=Reactions
+            :attributes: href=transport.html
+                         title=Transport
 
             .. container:: card-header section-card
                :tagname: div
 
-               Reactions
+               Transport
 
          .. container:: card-body
 
             .. container:: card-text
 
-               The models that Cantera uses to calculate chemical reaction rates.
+               The models that Cantera uses to calculate transport properties and rates.
 
 .. raw:: html
 

pages/science/reactions.rst → pages/science/kinetics.rst

@@ -1,4 +1,4 @@
-.. slug: reactions
+.. slug: kinetics
 .. has_math: true
 .. title: Modeling Chemical Reactions
 

pages/science/phases.rst → pages/science/phase-thermo.rst

@@ -1,12 +1,12 @@
-.. slug: phases
+.. slug: phase-thermo
 .. has_math: true
 .. title: Modeling Phases
 
 .. jumbotron::
 
    .. raw:: html
 
-      <h1 class="display-3">Modeling Phases in Cantera</h1>
+      <h1 class="display-3">Modeling Phase Thermodynamics in Cantera</h1>
 
    .. class:: lead
 
@@ -29,15 +29,6 @@ Ideal gas mixtures can be defined in the CTI format using the
 :cti:class:`ideal_gas` entry, or in the YAML format by specifying
 :ref:`ideal-gas <sec-yaml-ideal-gas>` in the ``thermo`` field.
 
-.. _sec-transport-models:
-
-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.
-
 Stoichiometric Solid
 --------------------
 
@@ -82,10 +73,3 @@ field.
 .. [#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.

pages/science/species.rst → pages/science/species-thermo.rst

@@ -1,12 +1,12 @@
-.. slug: science-species
+.. slug: species-thermo
 .. has_math: true
 .. title: Elements and Species
 
 .. jumbotron::
 
    .. raw:: html
 
-      <h1 class="display-3">Elements and Species</h1>
+      <h1 class="display-3">Elements and Species Thermodynamics</h1>
 
    .. class:: lead
 
@@ -73,31 +73,20 @@ defined to be composed solely of electrons.
 Thermodynamic Properties
 ------------------------
 
-The phase models discussed in the `Phases section </science/phases.html>`__
+The phase models discussed in the `Phases section </science/phases-thermo.html>`__
 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`;
-2. the molar enthalpy :math:`\hat{h}(T_0, P_0)` at :math:`P_0` and a reference
-   temperature :math:`T_0`;
-3. the absolute molar entropy :math:`\hat{s}(T_0, P_0)` at :math:`(T_0, P_0)`.
+1. the molar heat capacity at constant pressure :math:`\hat{c}^\circ_p(T)` for a
+   range of temperatures and a reference pressure :math:`p^\circ`;
+2. the molar enthalpy :math:`\hat{h}(T^\circ, p^\circ)` at :math:`p^\circ` and a reference
+   temperature :math:`T^\circ`;
+3. the absolute molar entropy :math:`\hat{s}(T^\circ, p^\circ)` at :math:`(T^\circ, p^\circ)`.
 
-See: :ref:`the Thermodynamic Models section <sec-thermo-models>`
-
-Species Transport Coefficients
-------------------------------
-
-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, or in the YAML format using the
-:ref:`transport <sec-yaml-species-transport>` field of a ``species`` entry.
+The superscript :math:`^\circ` here represents the *reference state*--a specified state (i.e. set of conditions :math:`T^\circ` and :math:`p^\circ` and fixed chemical composition) at which thermodynamic properties are known.
 
 .. _sec-thermo-models:
 
@@ -119,20 +108,20 @@ The NASA 7-Coefficient Polynomial Parameterization
 --------------------------------------------------
 
 The NASA 7-coefficient polynomial parameterization is used to compute the
-species reference-state thermodynamic properties :math:`\hat{c}^0_p(T)`,
-:math:`\hat{h}^0(T)`, and :math:`\hat{s}^0(T)`.
+species reference-state thermodynamic properties :math:`\hat{c}^\circ_p(T)`,
+:math:`\hat{h}^\circ(T)`, and :math:`\hat{s}^\circ(T)`.
 
-The NASA parameterization represents :math:`\hat{c}^0_p(T)` with a fourth-order
+The NASA parameterization represents :math:`\hat{c}^\circ_p(T)` with a fourth-order
 polynomial:
 
 .. math::
 
-   \frac{c_p^0(T)}{R} = a_0 + a_1 T + a_2 T^2 + a_3 T^3 + a_4 T^4
+   \frac{\hat{c}_p^\circ(T)}{\overline{R}} = a_0 + a_1 T + a_2 T^2 + a_3 T^3 + a_4 T^4
    
-   \frac{h^0 (T)}{R T} = a_0 + \frac{a_1}{2} T + \frac{a_2}{3} T^2 +
+   \frac{\hat{h}^\circ (T)}{\overline{R} T} = a_0 + \frac{a_1}{2} T + \frac{a_2}{3} T^2 +
                          \frac{a_3}{4} T^3 + \frac{a_4}{5} T^4 + \frac{a_5}{T}
 
-   \frac{s^0(T)}{R} = a_0 \ln T + a_1 T + \frac{a_2}{2} T^2 + \frac{a_3}{3} T^3 +
+   \frac{\hat{s}^\circ(T)}{\overline{R}} = a_0 \ln T + a_1 T + \frac{a_2}{2} T^2 + \frac{a_3}{3} T^3 +
                       \frac{a_4}{4} T^4 + a_6
 
 Note that this is the "old" NASA polynomial form, used in the original NASA
@@ -160,14 +149,14 @@ the following equations:
 
 .. math::
 
-   \frac{C_p^0(T)}{R} = a_0 T^{-2} + a_1 T^{-1} + a_2 + a_3 T
+   \frac{\hat{c}_p^\circ(T)}{\overline{R}} = a_0 T^{-2} + a_1 T^{-1} + a_2 + a_3 T
                   + a_4 T^2 + a_5 T^3 + a_6 T^4
 
-   \frac{H^0(T)}{R T} = - a_0 T^{-2} + a_1 \frac{\ln T}{T} + a_2
+   \frac{\hat{h}^\circ(T)}{\overline{R} T} = - a_0 T^{-2} + a_1 \frac{\ln T}{T} + a_2
        + \frac{a_3}{2} T + \frac{a_4}{3} T^2  + \frac{a_5}{4} T^3 +
        \frac{a_6}{5} T^4 + \frac{a_7}{T}
 
-   \frac{s^0(T)}{R} = - \frac{a_0}{2} T^{-2} - a_1 T^{-1} + a_2 \ln T
+   \frac{\hat{s}^\circ(T)}{\overline{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
 
 A common source for species data in the NASA9 format is the
@@ -184,12 +173,12 @@ The Shomate parameterization is:
 
 .. math::
 
-   \hat{c}_p^0(T) = A + Bt + Ct^2 + Dt^3 + \frac{E}{t^2}
+   \hat{c}_p^\circ(T) = A + Bt + Ct^2 + Dt^3 + \frac{E}{t^2}
 
-   \hat{h}^0(T) = At + \frac{Bt^2}{2} + \frac{Ct^3}{3} + \frac{Dt^4}{4} -
+   \hat{h}^\circ(T) = At + \frac{Bt^2}{2} + \frac{Ct^3}{3} + \frac{Dt^4}{4} -
                   \frac{E}{t} + F
 
-   \hat{s}^0(T) = A \ln t + B t + \frac{Ct^2}{2} + \frac{Dt^3}{3} -
+   \hat{s}^\circ(T) = A \ln t + B t + \frac{Ct^2}{2} + \frac{Dt^3}{3} -
                   \frac{E}{2t^2} + G
 
 where :math:`t = T / 1000 K`. It requires 7 coefficients :math:`A`, :math:`B`, :math:`C`, :math:`D`,
@@ -213,14 +202,14 @@ thermodynamic properties:
 
 .. math::
 
-   \hat{c}_p^0(T) = \hat{c}_p^0(T_0)
+   \hat{c}_p^\circ(T) = \hat{c}_p^\circ(T^\circ)
 
-   \hat{h}^0(T) = \hat{h}^0(T_0) + \hat{c}_p^0\cdot(T-T_0)
+   \hat{h}^\circ(T) = \hat{h}^\circ\left(T_0\right) + \hat{c}_p^\circ \left(T-T^\circ\right)
 
-   \hat{s}^0(T) = \hat{s}^0(T_0) + \hat{c}_p^0 \ln (T/T_0)
+   \hat{s}^\circ(T) = \hat{s}^\circ(T_0) + \hat{c}_p^\circ \ln{\left(\frac{T}{T^\circ}\right)}
 
-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
+The parameterization uses four constants: :math:`T^\circ, \hat{c}_p^\circ(T^\circ),
+\hat{h}^\circ(T^\circ), and \hat{s}^\circ(T)`. The default value of :math:`T^\circ` 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

pages/science/thermodynamics.rst

@@ -0,0 +1,81 @@
+.. slug: thermodynamics
+.. has_math: true
+.. title: Calculating phase and species thermodynamics
+
+.. jumbotron::
+
+   .. raw:: html
+
+      <h1 class="display-3">Calculating thermodynamic properties in Cantera</h1>
+
+   .. class:: lead
+
+      Here, we describe how Cantera uses species and phase information to calculate thermodynamic properties. 
+
+   Thermodynamic properties typically depend on information at both the species and phase levels. The user must specify thermodynamic models for both levels, and these selections must be compatible with one another. For instance: one cannot pair certain non-ideal species thermodyamic models with an ideal phase model.
+
+   - The user must specify a thermodynamic model for each species and provide inputs that inform how species properties are calculated. For example, the user specifies how the reference enthalpy and entropy values for each species are calcualted, as a function of temperature.
+   - The user also selects a phase model. This model describes how the species interact with one another to determine phase properties and species specific properties, for a given thermodynamic state. This includes general :math:`p`-:math:`\hat{v}`-:math:`T` behavior (for example, calculate the phase pressure for a given molar volume, temperature, and chemical composition), as well as how species-specific properties, such as internal energy, entropy, and others depend on the state variables
+
+Example: The Ideal Gas Model
+============================
+For a simple example: in the Ideal Gas model, one might use 7-parameter NASA polynomials to specify the species reference thermodynamic quantities.  These would be used to calculate the reference molar enthalpy :math:`\hat{h}_k^\circ(T)` and entropy :math:`\hat{s}_k^\circ(T)` for a given species :math:`k` as a function of temperature :math:`T`. See the `NASA Polynomials Species Thermo entry </science/science-species.html#the-nasa-7-coefficient-polynomial-parameterization>`__ for more information.
+
+At the phase level, the Ideal Gas Law provides the :math:`P`-:math:`\hat{v}`-:math:`T` relationship. The ideal gas law is an example of an equation of state. This is used, for example, to calculate the pressure as a function of molar volume :math:`\hat{v}`, and temperature, :math:`T`:
+
+.. math::
+   p = \frac{\overline{R}T}{\hat{v}}
+
+where :math:`\overline{R}` is the Universal Gas Constant. The `Maxwell relations <https://en.wikipedia.org/wiki/Maxwell_relations>`__ are used to derive other thermodynamic properties from the equation of state. With the Ideal Gas phase model, these reduce to rather simple forms. For example, for a species :math:`k`, the Ideal Gas molar internal energy :math:`\hat{u}_k` and entropy :math:`\hat{s}_k` are:
+
+.. math::
+   \hat{u}_k = \hat{h}^\circ_k(T) - p\hat{v}
+
+   \hat{s}_k = \hat{s}^\circ_k(T) - \overline{R}\ln\left(\frac{pX_k}{p^\circ}\right)
+
+where :math:`X_k` is the mole fraction of species :math:`k`, and where :math:`p^\circ` is the reference pressure at which the properties :math:`\hat{h}_k^\circ(T)` and :math:`\hat{s}_k^\circ(T)` are known.
+
+Please click either of the cards below for details on the species and phase models available in Cantera:
+
+.. container:: container
+   :tagname: section
+
+   .. container:: card-deck
+
+      .. container:: card
+
+         .. container::
+            :tagname: a
+            :attributes: href=species-thermo.html
+                         title=Species
+
+            .. container:: card-header section-card
+               :tagname: div
+
+               Species
+
+         .. container:: card-body
+
+            .. container:: card-text
+
+               The models and equations that Cantera uses to calculate species thermodynamic properties, such as the NASA 7-parameter polynomial form.
+
+      .. container:: card
+
+         .. container::
+            :tagname: a
+            :attributes: href=phase-thermo.html
+                         title=Phases
+
+            .. container:: card-header section-card
+               :tagname: div
+
+               Phases
+
+         .. container:: card-body
+
+            .. container:: card-text
+
+               The theory behind some of Cantera's phase models, such as the Ideal Gas Law.
+
+