Loading docs/source_docs/references/Chemistry_Chapter.rst +72 −0 Changes for docs/source_docs/references/Chemistry_Chapter.rst: 72 added lines, 0 removed lines. Original line number Diff line number Diff line Loading @@ -166,6 +166,78 @@ Example usage: python tools/Chemistry/optimize_usr_rates.py inputs mfix/src/usr/mfix_usr_reactions_rates_K.H Writing rates the stiff solvers can evaluate ============================================ The implicit chemistry integrators do not clip or renormalize their iterates, so a rate may be called with a slightly negative (or slightly greater than one) mass fraction, and so a slightly negative concentration. Rates must return a finite value for such inputs. Integer powers and products are already safe, but ``std::pow(c, 0.5)`` or ``std::sqrt(c)`` of a negative ``c`` is NaN, and a negative exponent is unbounded as ``c`` goes to zero. The header ``mfix_chem_safe_pow.H``, included by the template rates file, provides two families of helpers in the ``ChemMath`` namespace. They never produce NaN, Inf or a floating-point exception for finite input. .. list-table:: :header-rows: 1 :widths: 35 65 * - Function - Use * - ``ChemMath::clamped_pow(x, a)`` ``ChemMath::clamped_sqrt(x)`` - :math:`\max(x, 0)^a`, exact for :math:`x > 0`. Use for exponents :math:`a \ge 1` (for example first- or second-order mass action, or :math:`a = 1.4`), and for bases that never approach zero, such as temperature or pressure ratios. * - ``ChemMath::ramped_pow(x, a, x_c)`` ``ChemMath::ramped_sqrt(x, x_c)`` - The power smoothly attenuated to zero below the cutoff ``x_c``, and exact at and above it. Use for fractional exponents :math:`0 < a < 1` and negative exponents :math:`-3 < a < 0` on species that can deplete. The dividing line is the slope at zero. For :math:`a \ge 1` the slope of :math:`x^a` at zero is finite, so clamping is enough and the kinetics stay exact. For :math:`0 < a < 1` the slope is infinite as :math:`x \to 0`, which stalls the Newton iteration in the implicit solvers, and a negative exponent diverges. The ramped form multiplies by .. math:: R(s) = s^4 (5 - 4 s), \qquad s = \min(x / x_c, 1), which matches value and slope at :math:`s = 1`. For :math:`a > 0` the helper returns :math:`(x R)^a`, which behaves as :math:`x^{5a}` near zero; for :math:`a < 0` it returns :math:`R\, x^a`, which behaves as :math:`x^{4+a}`. Both go to zero with a finite slope (for :math:`a \ge 0.2` when :math:`a > 0`). The cutoff ``x_c`` is in the units of ``x`` and has no default. Choose it below any level at which the rate matters and well above round-off. The ramp changes the rate below ``x_c``. For example, :math:`10^{-4}\, mol \cdot m^{-3}` is about 2.5 ppm for a gas near atmospheric conditions, and a mass fraction cutoff might be :math:`10^{-8}`. Each helper has a ``*_and_deriv`` form returning a ``ChemMath::ValueAndDeriv`` with the value and its derivative with respect to ``x``, for analytical rate Jacobians. For example, a global step with fractional orders: .. code-block:: cpp amrex::Real const c_H2 = fluid.molar_concentration("H2"); // [mol/m^3] amrex::Real const c_O2 = fluid.molar_concentration("O2"); // [mol/m^3] // 0 < 0.25 < 1: ramp it; 1.5 >= 1: clamping is enough. reactions.rate("H2_oxidation") = k * ChemMath::ramped_pow(c_H2, 0.25, 1.e-4) * ChemMath::clamped_pow(c_O2, 1.5); Example rates UDFs ================== Loading Loading
docs/source_docs/references/Chemistry_Chapter.rst +72 −0 Changes for docs/source_docs/references/Chemistry_Chapter.rst: 72 added lines, 0 removed lines. Original line number Diff line number Diff line Loading @@ -166,6 +166,78 @@ Example usage: python tools/Chemistry/optimize_usr_rates.py inputs mfix/src/usr/mfix_usr_reactions_rates_K.H Writing rates the stiff solvers can evaluate ============================================ The implicit chemistry integrators do not clip or renormalize their iterates, so a rate may be called with a slightly negative (or slightly greater than one) mass fraction, and so a slightly negative concentration. Rates must return a finite value for such inputs. Integer powers and products are already safe, but ``std::pow(c, 0.5)`` or ``std::sqrt(c)`` of a negative ``c`` is NaN, and a negative exponent is unbounded as ``c`` goes to zero. The header ``mfix_chem_safe_pow.H``, included by the template rates file, provides two families of helpers in the ``ChemMath`` namespace. They never produce NaN, Inf or a floating-point exception for finite input. .. list-table:: :header-rows: 1 :widths: 35 65 * - Function - Use * - ``ChemMath::clamped_pow(x, a)`` ``ChemMath::clamped_sqrt(x)`` - :math:`\max(x, 0)^a`, exact for :math:`x > 0`. Use for exponents :math:`a \ge 1` (for example first- or second-order mass action, or :math:`a = 1.4`), and for bases that never approach zero, such as temperature or pressure ratios. * - ``ChemMath::ramped_pow(x, a, x_c)`` ``ChemMath::ramped_sqrt(x, x_c)`` - The power smoothly attenuated to zero below the cutoff ``x_c``, and exact at and above it. Use for fractional exponents :math:`0 < a < 1` and negative exponents :math:`-3 < a < 0` on species that can deplete. The dividing line is the slope at zero. For :math:`a \ge 1` the slope of :math:`x^a` at zero is finite, so clamping is enough and the kinetics stay exact. For :math:`0 < a < 1` the slope is infinite as :math:`x \to 0`, which stalls the Newton iteration in the implicit solvers, and a negative exponent diverges. The ramped form multiplies by .. math:: R(s) = s^4 (5 - 4 s), \qquad s = \min(x / x_c, 1), which matches value and slope at :math:`s = 1`. For :math:`a > 0` the helper returns :math:`(x R)^a`, which behaves as :math:`x^{5a}` near zero; for :math:`a < 0` it returns :math:`R\, x^a`, which behaves as :math:`x^{4+a}`. Both go to zero with a finite slope (for :math:`a \ge 0.2` when :math:`a > 0`). The cutoff ``x_c`` is in the units of ``x`` and has no default. Choose it below any level at which the rate matters and well above round-off. The ramp changes the rate below ``x_c``. For example, :math:`10^{-4}\, mol \cdot m^{-3}` is about 2.5 ppm for a gas near atmospheric conditions, and a mass fraction cutoff might be :math:`10^{-8}`. Each helper has a ``*_and_deriv`` form returning a ``ChemMath::ValueAndDeriv`` with the value and its derivative with respect to ``x``, for analytical rate Jacobians. For example, a global step with fractional orders: .. code-block:: cpp amrex::Real const c_H2 = fluid.molar_concentration("H2"); // [mol/m^3] amrex::Real const c_O2 = fluid.molar_concentration("O2"); // [mol/m^3] // 0 < 0.25 < 1: ramp it; 1.5 >= 1: clamping is enough. reactions.rate("H2_oxidation") = k * ChemMath::ramped_pow(c_H2, 0.25, 1.e-4) * ChemMath::clamped_pow(c_O2, 1.5); Example rates UDFs ================== Loading