Document per-class chemistry Jacobian types

Replace chemistry.integrator.jacobian_type with eulerian.jacobian_type and lagrangian.jacobian_type, describe how they combine in cells with particles and how the old key is migrated. Document the analytical option, and correct retry_swap_jacobian (default 0) and its description.

See https://mfix.netl.doe.gov/gitlab/exa/mfix/-/merge_requests/1943

Edited by Jordan Musser

Merge request reports

Loading
+53 −23
Changes for docs/source_docs/user_guide/inputs/chemical_reactions.rst: 53 added lines, 23 removed lines.
Original line number Diff line number Diff line
@@ -96,20 +96,33 @@ time to enable caching of the numerical approximation of the Jacobian matrix
is selected. The following inputs can be specified using the
prefix ``chemistry.integrator``:

+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
|                          | Description                                                         |   Type | Default   |
+========================+=====================================================================+========+===========+
+==========================+=====================================================================+========+===========+
| ode_max_steps            | The maximum number of substeps for the ODE integration.             | Int    | 150000    |
+------------------------+---------------------------------------------------------------------+--------+-----------+
| jacobian_type          | Select how to compute the Jacobian for the ODE iterative solver.    | String | Numerical |
|                        | This option is available for ``StiffSolver::BackwardEuler`` and     |        |           |
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| eulerian.jacobian_type   | Select how to compute the Jacobian of the Eulerian (fluid-phase)    | String | Numerical |
|                          | reaction terms. Available for ``StiffSolver::BackwardEuler`` and    |        |           |
|                          | ``StiffSolver::VODE``.                                              |        |           |
|                          |                                                                     |        |           |
|                          | Options (case-insensitive):                                         |        |           |
|                          |                                                                     |        |           |
|                          | * ``Numerical`` - first-order numerical approximation               |        |           |
|                        | * ``Broyden`` - Broyden's method (only for ``BackwardEuler``)       |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
|                          | * ``Analytical`` - assembled from the user-defined                  |        |           |
|                          |   ``EulerianReactionRates::rate_jacobian``                          |        |           |
|                          | * ``Broyden`` - Broyden's method (only for ``BackwardEuler``; must  |        |           |
|                          |   also be set for ``lagrangian.jacobian_type``)                     |        |           |
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| lagrangian.jacobian_type | Select how to compute the Jacobian of the Lagrangian (particle)     | String | Numerical |
|                          | reaction terms. Available for ``StiffSolver::BackwardEuler`` and    |        |           |
|                          | ``StiffSolver::VODE``.                                              |        |           |
|                          |                                                                     |        |           |
|                          | Options (case-insensitive):                                         |        |           |
|                          |                                                                     |        |           |
|                          | * ``Numerical`` - first-order numerical approximation               |        |           |
|                          | * ``Broyden`` - Broyden's method (only for ``BackwardEuler``; must  |        |           |
|                          |   also be set for ``eulerian.jacobian_type``)                       |        |           |
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| broyden_type             | When using the Broyden method in the Backward Euler ODE integrator, | String | Jacobian  |
|                          | select whether to approximate the Jacobian or its inverse.          |        |           |
|                          | This option is available only for ``StiffSolver::BackwardEuler``.   |        |           |
@@ -118,7 +131,7 @@ prefix ``chemistry.integrator``:
|                          |                                                                     |        |           |
|                          | * ``Jacobian``                                                      |        |           |
|                          | * ``Inverse``                                                       |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| broyden_initialization   | When using the Broyden method in the Backward Euler ODE integrator, | String | Identity  |
|                          | select whether to initialize the Jacobian or its inverse through the|        |           |
|                          | identity matrix or the numerical (finite-difference) approximation. |        |           |
@@ -127,43 +140,60 @@ prefix ``chemistry.integrator``:
|                          |                                                                     |        |           |
|                          | * ``Identity``                                                      |        |           |
|                          | * ``Numerical``                                                     |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| atol                     | Absolute tolerance for the ODE integration error test between       | Real   | 1.e-6     |
|                          | the solution and the fine-step solution.                            |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| rtol                     | Relative tolerance for the ODE integration error test between       | Real   | 1.e-6     |
|                          | the solution and the fine-step solution.                            |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| retry_atol               | Overwrites the absolute tolerance value atol in case the ODE        | Real   | -1        |
|                          | integration fails.                                                  |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| retry_rtol               | Overwrites the relative tolerance value rtol in case the ODE        | Real   | -1        |
|                          | integration fails.                                                  |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
| retry_swap_jacobian    | Swaps the type of Jacobian (from 1 to 0 or vice versa) in           | Int    | 1         |
|                        | case the ODE integration fails.                                     |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| retry_swap_jacobian      | When a failed ODE integration is retried (see ``retry_atol``),      | Int    | 0         |
|                          | switch between the analytical and the numerical (or Broyden)        |        |           |
|                          | Jacobian for the retry. Switching to analytical requires a          |        |           |
|                          | user-defined ``EulerianReactionRates::rate_jacobian``.              |        |           |
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| ode_max_dt               | Maximum timestep size for the ODE integration substeps.             | Real   | 1.e30     |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| max_dt_change_factor     | Only for StiffSolver::ForwardEuler, sets a maximum factor           | Real   | 1.001     |
|                          | for the change of the timestep for the internal substeps.           |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| max_iter                 | Maximum number of iterations for the internal Newton solver.        | Int    | 100       |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| linalg_do_pivoting       | Only for ``StiffSolver::BackwardEuler`` and ``StiffSolver::VODE``,  | Int    | 1         |
|                          | enables pivoting when solving the linear algebra                    |        |           |
|                          | problem associated to the internal Newton solver.                   |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| rp_rtol                  | Relative tolerance for the convergence test of the internal         | Real   | 1.e-6     |
|                          | Newton solver. Valid only for ``StiffSolver::BackwardEuler``.       |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| use_jacobian_caching     | Only for ``StiffSolver::VODE``, enable caching the numerical        | Int    | 1         |
|                          | Jacobian.                                                           |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+
| X_reject_buffer          | Only for ``StiffSolver::VODE``, constrain species abundances        | Real   | 1.0       |
|                          | such that they don't change by more than a certain factor in        |        |           |
|                          | a given step.                                                       |        |           |
+------------------------+---------------------------------------------------------------------+--------+-----------+
+--------------------------+---------------------------------------------------------------------+--------+-----------+

The Jacobian type is set separately for the Eulerian and Lagrangian reactions.
In a fluid cell without particles only the Eulerian reactions are integrated,
so ``eulerian.jacobian_type`` alone applies. In a cell with particles, the
Eulerian and Lagrangian reactions are integrated together for each particle,
and the Jacobian is the sum of the two parts: with ``eulerian.jacobian_type =
analytical``, the Eulerian part is analytical and the Lagrangian part is
computed numerically. Broyden's method approximates the whole Jacobian, so it
must be selected for both or neither.

The former ``chemistry.integrator.jacobian_type`` is read as
``chemistry.integrator.eulerian.jacobian_type``. Unless
``chemistry.integrator.lagrangian.jacobian_type`` is also given, the Lagrangian
type is set to ``numerical`` (or to ``broyden`` when the former key was
``broyden``) and a warning is printed.


Below is an example for specifying chemical reactions for MFIX-Exa.
Loading