From c458534fbee4c441eece3a191c93d2bc9516c702 Mon Sep 17 00:00:00 2001 From: Ray Speth Date: Thu, 4 Jan 2024 16:46:35 -0500 Subject: [PATCH] [Doc] Adopt more review suggestions for science docs Co-authored-by: Steven C. DeCaluwe --- doc/sphinx/develop/reactor-integration.md | 6 ++--- .../reference/kinetics/rate-constants.md | 18 +++++++-------- .../reference/kinetics/reaction-rates.md | 7 ++++-- doc/sphinx/reference/thermo/phase-thermo.md | 11 +++++---- doc/sphinx/reference/thermo/species-thermo.md | 23 +++++++++++-------- src/kinetics/PlogRate.cpp | 5 +++- 6 files changed, 41 insertions(+), 29 deletions(-) diff --git a/doc/sphinx/develop/reactor-integration.md b/doc/sphinx/develop/reactor-integration.md index b04f99fd05..d2bda4bdd3 100644 --- a/doc/sphinx/develop/reactor-integration.md +++ b/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. diff --git a/doc/sphinx/reference/kinetics/rate-constants.md b/doc/sphinx/reference/kinetics/rate-constants.md index 823dc067a0..5ada2ed91d 100644 --- a/doc/sphinx/reference/kinetics/rate-constants.md +++ b/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 diff --git a/doc/sphinx/reference/kinetics/reaction-rates.md b/doc/sphinx/reference/kinetics/reaction-rates.md index 6f9a06cfe4..14a62fd22f 100644 --- a/doc/sphinx/reference/kinetics/reaction-rates.md +++ b/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. diff --git a/doc/sphinx/reference/thermo/phase-thermo.md b/doc/sphinx/reference/thermo/phase-thermo.md index 8de6fb0f43..85d50e3f61 100644 --- a/doc/sphinx/reference/thermo/phase-thermo.md +++ b/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 diff --git a/doc/sphinx/reference/thermo/species-thermo.md b/doc/sphinx/reference/thermo/species-thermo.md index 5aa78345e7..4752134d47 100644 --- a/doc/sphinx/reference/thermo/species-thermo.md +++ b/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: diff --git a/src/kinetics/PlogRate.cpp b/src/kinetics/PlogRate.cpp index 832359506f..d8cd0d9b9f 100644 --- a/src/kinetics/PlogRate.cpp +++ b/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)); } }