Commit b39b0f32 authored by Jordan Musser's avatar Jordan Musser
Browse files

Document safe power helpers for reaction-rate UDFs (!250)

parent 795e197b
Loading
Loading
Loading
Loading
+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
@@ -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
==================