[Doc] Adopt more review suggestions for science docs

Co-authored-by: Steven C. DeCaluwe <[email protected]>

Author: speth

doc/sphinx/develop/reactor-integration.md

@@ -88,9 +88,9 @@ function are:
 - `tout` is the desired integrator output time. CVODES will not necessarily reach this
   time when operating in "one step" mode, but it is used in the selection of the initial
   step size.
-- After execution, {ct}`CVodesIntegrator::m_y` will contain the computed solution
-  vector, and will later be used to update the {ct}`ReactorNet` to its time-integrated
-  state.
+- After execution, {ct}`CVodesIntegrator::m_y` will contain the computed system state
+  at the time reached by the integrator, and will later be used to update the
+  {ct}`ReactorNet` to its time-integrated state.
 - After execution, {ct}`CVodesIntegrator::m_tInteg` will contain the time reached by the
   integrator.
 - The `CV_ONE_STEP` option tells the solver to take a single internal step.

doc/sphinx/reference/kinetics/rate-constants.md

@@ -12,7 +12,7 @@ An Arrhenius rate is described by the
 $$  k_f = A T^b e^{-E_a / RT}  $$
 
 where $A$ is the pre-exponential factor, $T$ is the temperature, $b$ is the temperature
-exponent, $E_a$ is the activation energy, and $R$ is the gas constant.
+exponent, $E_a$ is the activation energy, and $R$ is the universal gas constant.
 
 :::{admonition} YAML Usage
 :class: tip
@@ -140,11 +140,11 @@ $$  \t{Si + SiH_4 (+M) \leftrightarrow Si_2H_4 (+M)}  $$
 
 Like falloff reactions, chemically-activated reactions are described by blending between
 a low-pressure and a high-pressure rate expression. The difference is that the forward
-rate constant is written as being proportional to the *low-pressure* rate constant:
+rate constant is written as proportional 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 $F$ may described by any of the parameterizations
+and the optional blending function $F$ may be described by any of the parameterizations
 allowed for falloff reactions.
 
 ```{admonition} YAML Usage
@@ -242,10 +242,11 @@ In some circumstances like thermodynamic sensitivity analysis, or modeling heter
 reactions from one catalyst surface to another, the enthalpy change of a reaction
 ($\Delta H$) can be modified. Due to the change in $\Delta H$, the activation energy of
 the reaction must be adjusted accordingly to provide accurate simulation results. To
-adjust the activation energy due to changes in the reaction enthalpy, the Blowers-Masel
+adjust the activation energy  due to changes in the reaction enthalpy, the Blowers-Masel
 rate expression is available. This approximation was proposed by {cite:t}`blowers2000`
 to automatically scale activation energy as the reaction enthalpy is changed. The
-activation energy estimation can be written as:
+_intrinsic activation energy_ $E_a^0$ is defined as the activation energy when
+$\Delta H = 0$. The activation energy can then be written as a function of $\Delta H$:
 
 $$
 E_a = \begin{cases}
@@ -260,10 +261,9 @@ where
 
 $$  V_P = 2 w \frac{w + E_a^0}{w - E_a^0},  $$
 
-$w$ is the average of the bond dissociation energy of the bond breaking and that being
-formed, $E_a^0$ is the intrinsic activation energy, and $\Delta H$ is the enthalpy
-change of the reaction. Note that the expression is insensitive to $w$ as long as $w \ge
-2 E_a^0$, so we can use an arbitrarily high value of $w = 1000\text{ kJ/mol}$.
+and $w$ is the average of the bond dissociation energy of the bond breaking and that
+being formed. Note that the expression is insensitive to $w$ as long as $w \ge 2 E_a^0$,
+so we can use an arbitrarily high value of $w = 1000\text{ kJ/mol}$.
 
 After $E_a$ is evaluated, the reaction rate can be calculated using the modified
 Arrhenius expression

doc/sphinx/reference/kinetics/reaction-rates.md

@@ -9,11 +9,14 @@ types.
 The basic reaction type is a homogeneous reaction with a pressure-independent
 rate coefficient and mass action kinetics. For example:
 
-$$  \t{A + B \rightleftharpoons C + D}  $$
+$$  a\t{A} + b\t{B} \rightleftharpoons c\t{C} + d\t{D}  $$
+
+where A and B are reactant species, C and D are product species, and $a, b, c, $ and $d$
+are stoichiometric coefficients.
 
 The forward reaction rate is then calculated as:
 
-$$  R_f = [\t{A}] [\t{B}] k_f  $$
+$$  R_f = [\t{A}]^a [\t{B}]^b k_f  $$
 
 where $k_f$ is the forward rate constant, calculated using one of the available rate
 parameterizations such as the [modified Arrhenius](sec-arrhenius-rate) form.

doc/sphinx/reference/thermo/phase-thermo.md

@@ -15,13 +15,13 @@ Ideal Gas Mixture
   Implemented by class {ct}`IdealGasPhase`.
 
 (sec-Redlich-Kwong-phase)=
-Redlich-Kwong Real Gas
+Redlich-Kwong Real Gas Mixture
 : A multi-species real gas following the Redlich-Kwong equation of state. Defined in the
   YAML format by specifying [`Redlich-Kwong`](sec-yaml-Redlich-Kwong) in the `thermo`
   field of the phase definition. Implemented by class {ct}`RedlichKwongMFTP`.
 
 (sec-Peng-Robinson-phase)=
-Peng-Robinson Real Gas
+Peng-Robinson Real Gas Mixture
 : A multi-species real gas following the Peng-Robinson equation of state. Defined in the
   YAML format by specifying [`Peng-Robinson`](sec-yaml-Peng-Robinson) in the `thermo`
   field of the phase definition. Implemented by class {ct}`PengRobinson`.
@@ -99,9 +99,10 @@ Ideal Molal Solution
 
 (sec-ideal-condensed-phase)=
 Ideal Condensed Phase
-: An ideal liquid or solid solution. Defined in the YAML format by specifying
-  [`ideal-condensed`](sec-yaml-ideal-condensed) in the `thermo` field of the
-  phase definition. Implemented by class {ct}`IdealSolidSolnPhase`.
+: An ideal liquid or solid solution based on the mixing-rule assumption that all molar
+  concentration-based activity coefficients are equal to one. Defined in the YAML format
+  by specifying [`ideal-condensed`](sec-yaml-ideal-condensed) in the `thermo` field of
+  the phase definition. Implemented by class {ct}`IdealSolidSolnPhase`.
 
 (sec-ideal-solution-VPSS-phase)=
 Ideal Condensed Phase with VPSS Species

doc/sphinx/reference/thermo/species-thermo.md

@@ -5,7 +5,7 @@ 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.
 
-Generally, the phase models require a parameterization of the standard state heat
+Generally, the phase models require a parameterization of the _standard state_ heat
 capacity, enthalpy, and entropy for each species at a fixed pressure $p^\circ$ as a
 function of $T$. In addition, phase models may require information describing how each
 species affects the equation of state, either in terms of the species standard molar
@@ -19,16 +19,21 @@ Many of Cantera's phase thermodynamic models are formulated to make use of the
 for individual species, defined at a standard pressure $p^\circ$ and for the composition
 specified by the phase model. For example, this could include a pure gas in the case of
 the ideal gas model, or an ion at infinite dilution in water in the case of aqueous
-solutions.
+solutions. The value of $p^\circ$ is not fixed by Cantera, and may vary among different
+sources of thermodynamic data.
 
 ```{caution}
-In some parts of the Cantera documentation, properties calculated at the standard
-pressure $p^\circ$ are referred to as *reference-state* thermodynamic properties, while
-properties calculated using the composition defining the standard state but at any
-pressure are referred to as *standard state* properties. This nomenclature is fairly
-unique to Cantera, based on the desire to distinguish these different steps in the
-calculation of the full thermodynamic properties, and is not often seen in other
-descriptions of solution thermodynamics.
+In some parts of the Cantera documentation, properties calculated at the user-specified
+standard pressure $p^\circ$ are referred to as *reference-state* thermodynamic
+properties, as they represent a well-known reference state and properties for all other
+states are calculated according to their departure from this known reference condition.
+In these same parts of the documentation, the term _standard-state properties_ refers to
+properties calculated using the composition defining the standard state but at the
+mixture's current pressure.
+
+This nomenclature is fairly unique to Cantera, based on the desire to distinguish these
+different steps in the calculation of the full thermodynamic properties, and is not
+often seen in other descriptions of solution thermodynamics.
 ```
 
 The necessary properties are:

src/kinetics/PlogRate.cpp

@@ -149,7 +149,10 @@ void PlogRate::validate(const string& equation, const Kinetics& kin)
     }
     if (err_reactions.size()) {
         throw InputFileError("PlogRate::validate", m_input,
-            "\nInvalid rate coefficient for reaction '{}'\n{}",
+            "\nInvalid rate coefficient for reaction '{}'\n{}\n"
+            "To fix this error, remove this reaction or contact the author of the\n"
+            "reaction/mechanism in question, because the rate expression is\n"
+            "mathematically unsound at the temperatures and pressures noted above.\n",
             equation, to_string(err_reactions));
     }
 }