More Sphinx / Doxygen updates

README.rst

@@ -76,7 +76,7 @@ Code of Conduct
 
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg
     :alt: conduct
-    :target: https://www.contributor-covenant.org/version/2/0/code-of-conduct.html
+    :target: https://www.contributor-covenant.org/version/2/0/code_of_conduct/
 
 In order to have a more open and welcoming community, Cantera adheres to a
 `code of conduct <CODE_OF_CONDUCT.md>`_ adapted from the `Contributor Covenant

doc/doxygen/Doxyfile

@@ -1297,7 +1297,7 @@ HTML_DYNAMIC_SECTIONS  = NO
 # Minimum value: 0, maximum value: 9999, default value: 100.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-HTML_INDEX_NUM_ENTRIES = 100
+HTML_INDEX_NUM_ENTRIES = 0
 
 # If the GENERATE_DOCSET tag is set to YES, additional index files will be
 # generated that can be used as input for Apple's Xcode 3 integrated development

doc/doxygen/DoxygenLayout.xml

@@ -3,12 +3,7 @@
   <!-- Navigation index tabs for HTML output -->
   <navindex>
     <tab type="mainpage" visible="yes" title="Developer API"/>
-    <tab type="pages" visible="yes" title="" intro=""/>
     <tab type="modules" visible="yes" title="" intro=""/>
-    <tab type="namespaces" visible="yes" title="">
-      <tab type="namespacelist" visible="yes" title="" intro=""/>
-      <tab type="namespacemembers" visible="yes" title="" intro=""/>
-    </tab>
     <tab type="interfaces" visible="yes" title="">
       <tab type="interfacelist" visible="yes" title="" intro=""/>
       <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
@@ -20,6 +15,10 @@
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
     </tab>
+    <tab type="namespaces" visible="yes" title="">
+      <tab type="namespacelist" visible="yes" title="" intro=""/>
+      <tab type="namespacemembers" visible="yes" title="" intro=""/>
+    </tab>
     <tab type="structs" visible="yes" title="">
       <tab type="structlist" visible="yes" title="" intro=""/>
       <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>
@@ -33,6 +32,7 @@
       <tab type="filelist" visible="yes" title="" intro=""/>
       <tab type="globals" visible="yes" title="" intro=""/>
     </tab>
+    <tab type="pages" visible="yes" title="" intro=""/>
     <tab type="examples" visible="yes" title="" intro=""/>
     <tab type="user" url="https://cantera.org" title="cantera.org"/>
   </navindex>

doc/doxygen/cantera.bib

@@ -1,3 +1,25 @@
+@incollection{bilger1979,
+    author = {R.~W.~Bilger},
+    title = {Turbulent Jet Diffusion Flames},
+    booktitle = {Energy and Combustion Science},
+    editor = {N.~A.~Chigier},
+    publisher = {Pergamon},
+    pages = {109-131},
+    url = {https://doi.org/10.1016/B978-0-08-024780-9.50011-3},
+    doi = {10.1016/B978-0-08-024780-9.50011-3},
+    isbn = {978-0-08-024780-9},
+    year = {1979}}
+@article{bisetti2012,
+    author = {F.~Bisetti and M.~El Morsli},
+    title = {Calculation and analysis of the mobility and diffusion coefficient
+        of thermal electrons in methane/air premixed flames},
+    journal = {Combustion and Flame},
+    volume = {159},
+    pages = {3518--3521},
+    number = {12},
+    url = {https://doi.org/10.1016/j.combustflame.2012.08.002},
+    doi = {10.1016/j.combustflame.2012.08.002},
+    year = {2012}}
 @article{blowers2004,
     author = {P.~Blowers and R.~Masel},
     journal = {AIChE Journal},
@@ -20,6 +42,14 @@ @article{chiflikian1995
     url = {https://dx.doi.org/10.1063/1.871019},
     volume = {2},
     year = {1995}}
+@book{denbigh1981,
+    author = {K.~Denbigh},
+    title = {The Principles of Chemical Equilibrium},
+    publisher = {Cambridge University Press},
+    address = {Cambridge},
+    edition = {Fourth},
+    isbn = {0-521-23682-7},
+    year = {1981}}
 @article{dixon-lewis1968,
     author = {G.~Dixon-Lewis},
     title = {Flame structure and flame reaction kinetics II. Transport phenomena in multicomponent systems},
@@ -82,6 +112,31 @@ @article{han2015
     url = {https://dx.doi.org/10.1080/13647830.2015.1090018},
     volume = {19},
     year = {2015}}
+@article{harvie1980,
+    author = {C.~E.~Harvie and J.~H.~Weare},
+    title = {The prediction of mineral solubilities in natural waters: the
+        {Na}–{K}-{Mg}-{Ca}-{Cl}-{SO4}-{H2O} system from zero to high
+        concentration at 25° {C}},
+    journal = {Geochimica et Cosmochimica Acta},
+    volume = {44},
+    number = {7},
+    month = jul,
+    url = {https://doi.org/10.1016/0016-7037(80)90287-2},
+    doi = {10.1016/0016-7037(80)90287-2},
+    pages = {981--997},
+    year = {1980}}
+@article{johnson1992,
+    author = {J.~W.~Johnson and E.~H.~Oelkers and H.~C.~Helgeson},
+    title = {{SUPCRT92}: {A} software package for calculating the standard molal
+        thermodynamic properties of minerals, gases, aqueous species, and reactions
+        from 1 to 5000 bar and 0 to 1000°{C}},
+    journal = {Computers \& Geosciences},
+    volume = {18},
+    number = {7},
+    pages = {899--947},
+    url = {https://doi.org/10.1016/0098-3004(92)90029-Q},
+    doi = {10.1016/0098-3004(92)90029-Q},
+    year = {1992}}
 @techreport{kee1989,
     author = {R.~J.~Kee and F.~M.~Rupley and J.~A.~Miller},
     institution = {Sandia National Laboratories},
@@ -205,6 +260,16 @@ @article{monchick1961
     month = {11},
     doi = {10.1063/1.1732130},
     url = {https://doi.org/10.1063/1.1732130}}
+@article{nickalls1993,
+    author = {R.~W.~D.~Nickalls},
+    title = {A New Approach to Solving the Cubic: Cardan's Solution Revealed},
+    journal = {The Mathematical Gazette},
+    volume = {77},
+    number = {480},
+    pages = {354--359},
+    URL = {https://doi.org/10.2307/3619777},
+    doi = {10.2307/3619777},
+    year = {1993}}
 @article{niemeyer2017,
     author = {K.~E.~Niemeyer and N.~J.~Curtis and C.-J.~Sung},
     journal = {Journal of Computational Science},
@@ -214,6 +279,16 @@ @article{niemeyer2017
     url = {https://dx.doi.org/10.1016/j.cpc.2017.02.004},
     volume = {21},
     year = {2017}}
+@article{pedersen1993,
+    author = {T.~Pedersen and R.~.C.~Brown},
+    title = {Simulation of electric field effects in premixed methane flames},
+    journal = {Combustion and Flame},
+    volume = {94},
+    number = {4},
+    pages = {433--448},
+    url = {https://doi.org/10.1016/0010-2180(93)90125-M},
+    doi = {10.1016/0010-2180(93)90125-M},
+    year = {1993}}
 @article{perini2012,
     author = {F.~Perini and E.~Galligani and R.~D.~Reitz},
     journal = {Energy \& Fuels},
@@ -226,6 +301,17 @@ @article{perini2012
     url = {https://dx.doi.org/10.1021/ef300747n},
     volume = {26},
     year = {2012}}
+@article{pitzer1975,
+    author = {K.~S.~Pitzer},
+    title = {Thermodynamics of electrolytes. {V}. effects of higher-order electrostatic
+        terms},
+    journal = {Journal of Solution Chemistry},
+    volume = {4},
+    number = {3},
+    pages = {249--265},
+    url = {https://doi.org/10.1007/BF00646562},
+    doi = {10.1007/BF00646562},
+    year = {1975}}
 @book{poling2001,
     author = {B.~E.~Poling and J.~M.~Prausnitz and J.~P.~O'Connell},
     title = {The Properties of Gases and Liquids},
@@ -280,6 +366,16 @@ @article{sengers1986
     year = {1986},
     %doi = {10.1063/1.555763},
     }
+@article{silvester1977,
+    author = {L.~F.~Silvester and K.~S.~Pitzer},
+    title = {Thermodynamics of electrolytes. 8. High-temperature properties, including
+        enthalpy and heat capacity, with application to sodium chloride},
+    journal = {Journal of Physical Chemistry},
+    volume = {81},
+    number = {19},
+    pages = {1822--1828},
+    url = {https://doi.org/10.1021/j100534a007},
+    year = {1977}}
 @book{smith1982,
     author = {W.~R.~Smith and R.~W.~Missen},
     publisher = {Wiley},

include/cantera/oneD/IonFlow.h

@@ -21,11 +21,8 @@ namespace Cantera
  * The second stage evaluates drift flux from electric field calculated from
  * Poisson's equation, which is solved together with other equations. Poisson's
  * equation is coupled because the total charge densities depends on the species'
- * concentration.
- * Reference:
- * Pederson, Timothy, and R. C. Brown.
- * "Simulation of electric field effects in premixed methane flames."
- * Combustion and Flames 94.4(1993): 433-448.
+ * concentration. See Pedersen and Brown @cite pedersen1993 for details.
+ *
  * @ingroup flowGroup
  */
 class IonFlow : public StFlow
@@ -61,11 +58,7 @@ class IonFlow : public StFlow
     /**
      * Sometimes it is desired to carry out the simulation using a specified
      * electron transport profile, rather than assuming it as a constant (0.4).
-     * Reference:
-     * Bisetti, Fabrizio, and Mbark El Morsli.
-     * "Calculation and analysis of the mobility and diffusion coefficient
-     * of thermal electrons in methane/air premixed flames."
-     * Combustion and flame 159.12 (2012): 3518-3521.
+     * See Bisetti and El Morsli @cite bisetti2012.
      * If in the future the class GasTransport is improved, this method may
      * be discarded. This method specifies this profile.
     */

include/cantera/thermo/HMWSoln.h

@@ -435,8 +435,8 @@ class WaterProps;
  * dependence of these coefficients strongly influence the value of the excess
  * Enthalpy and excess Volumes of Pitzer solutions. Therefore, these are readily
  * measurable quantities. HMWSoln provides several different methods for putting
- * these dependencies into the coefficients. HMWSoln has an implementation
- * described by Silverter and Pitzer (1977), which was used to fit experimental
+ * these dependencies into the coefficients. HMWSoln has an implementation described
+ * by Silvester and Pitzer @cite silvester1977, which was used to fit experimental
  * data for NaCl over an extensive range, below the critical temperature of
  * water. They found a temperature functional form for fitting the 3 following
  * coefficients that describe the Pitzer parameterization for a single salt to
@@ -543,8 +543,8 @@ class WaterProps;
  * constant and density of the solvent. This seems to be a relatively well-
  * documented part of the theory. They theory below comes from Pitzer summation
  * (Pitzer) in the appendix. It's also mentioned in Bethke's book (Bethke), and
- * the equations are summarized in Harvie & Weare (1980). Within the code, @f$
- * \,^E\Theta_{ij}(I) @f$ is evaluated according to the algorithm described in
+ * the equations are summarized in Harvie & Weare @cite harvie1980. Within the code,
+ * @f$ \,^E\Theta_{ij}(I) @f$ is evaluated according to the algorithm described in
  * Appendix B [Pitzer] as
  *
  * @f[
@@ -1277,8 +1277,8 @@ class HMWSoln : public MolalityVPSSTP
     //!  activity coefficients at the current solution temperature,
     //!  pressure, and solution concentration.
     /*!
-     *  See Denbigh p. 278 for a thorough discussion. This class must be
-     *  overridden in classes which derive from MolalityVPSSTP. This function
+     *  See Denbigh p. 278 @cite denbigh1981 for a thorough discussion. This method must
+     *  be overridden in classes which derive from MolalityVPSSTP. This function
      *  takes over from the molar-based activity coefficient calculation,
      *  getActivityCoefficients(), in derived classes.
      *
@@ -2017,7 +2017,7 @@ class HMWSoln : public MolalityVPSSTP
     //! Calculate the lambda interactions.
     /*!
      * Calculate E-lambda terms for charge combinations of like sign, using
-     * method of Pitzer (1975). This implementation is based on Bethke,
+     * method of Pitzer @cite pitzer1975. This implementation is based on Bethke,
      * Appendix 2.
      *
      * @param is Ionic strength

include/cantera/thermo/MixtureFugacityTP.h

@@ -506,9 +506,7 @@ class MixtureFugacityTP : public ThermoPhase
      * a positive number (1 or 2). If it only finds the liquid branch solution,
      * it will return -1 or -2 instead of 1 or 2.
      * If it returns 0, then there is an error.
-     * The cubic equation is solved using Nickall's method
-     * (Ref: The Mathematical Gazette(1993), 77(November), 354--359,
-     *  https://www.jstor.org/stable/3619777)
+     * The cubic equation is solved using Nickalls' method @cite nickalls1993.
      *
      * @param   T         temperature (kelvin)
      * @param   pres      pressure (Pa)

include/cantera/thermo/MolalityVPSSTP.h

@@ -413,7 +413,7 @@ class MolalityVPSSTP : public VPStandardStateTP
      * These are mole-fraction based activity coefficients. In this
      * object, their calculation is based on translating the values
      * of the molality-based activity coefficients.
-     *  See Denbigh p. 278 for a thorough discussion.
+     *  See Denbigh p. 278 @cite denbigh1981 for a thorough discussion.
      *
      * The molar-based activity coefficients @f$ \gamma_k @f$ may be calculated
      * from the molality-based activity coefficients, @f$ \gamma_k^\triangle @f$
@@ -441,8 +441,8 @@ class MolalityVPSSTP : public VPStandardStateTP
     //! Get the array of non-dimensional molality based activity coefficients at
     //! the current solution temperature, pressure, and solution concentration.
     /*!
-     * See Denbigh p. 278 for a thorough discussion. This class must be
-     * overridden in classes which derive from MolalityVPSSTP. This function
+     * See Denbigh p. 278 @cite denbigh1981 for a thorough discussion. This method must
+     * be overridden in classes which derive from MolalityVPSSTP. This function
      * takes over from the molar-based activity coefficient calculation,
      * getActivityCoefficients(), in derived classes.
      *
@@ -546,8 +546,8 @@ class MolalityVPSSTP : public VPStandardStateTP
     //! coefficients at the current solution temperature, pressure, and solution
     //! concentration.
     /*!
-     * See Denbigh p. 278 for a thorough discussion. This class must be
-     * overridden in classes which derive from MolalityVPSSTP. This function
+     * See Denbigh p. 278 @cite denbigh1981 for a thorough discussion. This method must
+     * be overridden in classes which derive from MolalityVPSSTP. This function
      * takes over from the molar-based activity coefficient calculation,
      * getActivityCoefficients(), in derived classes.
      *

include/cantera/thermo/PDSS_HKFT.h

@@ -144,14 +144,14 @@ class PDSS_HKFT : public PDSS_Molar
     //! Main routine that actually calculates the Gibbs free energy difference
     //! between the reference state at Tr, Pr and T,P
     /*!
-     *  This is eEqn. 59 in Johnson et al. (1992).
+     *  This is Eqn. 59 in Johnson et al. @cite johnson1992.
      */
     double deltaG() const;
 
     //! Main routine that actually calculates the entropy difference
     //! between the reference state at Tr, Pr and T,P
     /*!
-     *  This is Eqn. 61 in Johnson et al. (1992). Actually, there appears to
+     *  This is Eqn. 61 in Johnson et al. @cite johnson1992. Actually, there appears to
      *  be an error in the latter. This is a correction.
      */
     double deltaS() const;
@@ -192,7 +192,8 @@ class PDSS_HKFT : public PDSS_Molar
 
     //! function g appearing in the formulation
     /*!
-     * Function g appearing in the Johnson et al formulation
+     * Function @f$ g @f$ (Eqn. 49) appearing in the Johnson et al. @cite johnson1992
+     * formulation.
      *
      * @param temp      Temperature kelvin
      * @param pres      Pressure (pascal)
@@ -206,8 +207,8 @@ class PDSS_HKFT : public PDSS_Molar
 
     //! Difference function f appearing in the formulation
     /*!
-     * Function f appearing in the Johnson et al formulation of omega_j
-     *   Eqn. 33 ref
+     * Function @f$ f @f$ (Eqn. 52) appearing in the Johnson et al. @cite johnson1992
+     * formulation of @f$ \omega_j @f$ (Eqn. 46).
      *
      * @param temp      Temperature kelvin
      * @param pres      Pressure (pascal)

include/cantera/thermo/Phase.h

@@ -19,18 +19,6 @@ namespace Cantera
 class Solution;
 class Species;
 
-/**
- * @defgroup phases Models of Phases of Matter
- *
- * These classes are used to represent the composition and state of a single
- * phase of matter. Together these classes form the basis for describing the
- * species and element compositions of a phase as well as the stoichiometry
- * of each species, and for describing the current state of the phase. They do
- * not in themselves contain Thermodynamic equation of state information.
- * However, they do comprise all of the necessary background functionality to
- * support thermodynamic calculations (see @ref thermoprops).
- */
-
 //! Class Phase is the base class for phases of matter, managing the species and
 //! elements in a phase, as well as the independent variables of temperature,
 //! mass density (compressible substances) or pressure (incompressible
@@ -101,7 +89,7 @@ class Species;
  *     Jacobian and some analytical Jacobians use non-conforming calculations.
  *     These can easily be changed to the set mole number setState functions.
  *
- * @ingroup phases
+ * @ingroup thermoprops
  */
 class Phase
 {

include/cantera/thermo/ThermoPhase.h

@@ -385,7 +385,6 @@ enum class ThermoBasis
  * the reverse rate constant.
  *
  * @ingroup thermoprops
- * @ingroup phases
  */
 class ThermoPhase : public Phase
 {
@@ -1554,8 +1553,7 @@ class ThermoPhase : public Phase
      * in the mixture, and @f$ Z_{\mathrm{mass},m,\mathrm{ox}} @f$ and
      * @f$ Z_{\mathrm{mass},m,\mathrm{fuel}} @f$ are the elemental mass fractions
      * of the oxidizer and fuel, or from the Bilger mixture fraction,
-     * which considers the elements C, S, H and O (R. W. Bilger, "Turbulent jet
-     * diffusion flames," Prog. Energy Combust. Sci., 109-131 (1979))
+     * which considers the elements C, S, H and O @cite bilger1979
      * @f[ Z_{\mathrm{Bilger}} = \frac{\beta-\beta_{\mathrm{ox}}}
      * {\beta_{\mathrm{fuel}}-\beta_{\mathrm{ox}}} @f]
      * with @f$ \beta = 2\frac{Z_C}{M_C}+2\frac{Z_S}{M_S}+\frac{1}{2}\frac{Z_H}{M_H}
@@ -1620,7 +1618,7 @@ class ThermoPhase : public Phase
     /*!
      * The equivalence ratio @f$ \phi @f$ is computed from
      * @f[ \phi = \frac{Z}{1-Z}\frac{1-Z_{\mathrm{st}}}{Z_{\mathrm{st}}} @f]
-     * where @f$ Z @f$ is the Bilger mixture fraction of the mixture
+     * where @f$ Z @f$ is the Bilger mixture fraction @cite bilger1979 of the mixture
      * given the specified fuel and oxidizer compositions
      * @f$ Z_{\mathrm{st}} @f$ is the mixture fraction at stoichiometric
      * conditions. Fuel and oxidizer compositions are given either as