Chemical Reactions
==================

Enabling the Chemical Reactions solver and specifying model options.

+----------------------------------+-------------------------------------------------------------+----------+-----------+
|                                  | Description                                                 |   Type   | Default   |
+==================================+=============================================================+==========+===========+
| chemistry.solve                  | Specified name(s) of the chemical reactions types or None   | String   |  None     |
|                                  | to disable the reactions solver.                            |          |           |
+----------------------------------+-------------------------------------------------------------+----------+-----------+

The following inputs are defined using the ``chemistry`` prefix.

+------------------------+---------------------------------------------------------+----------+-----------+
|                        | Description                                             |   Type   | Default   |
+========================+=========================================================+==========+===========+
| [reaction0].reaction   | Chemical formula for the given reaction. The string     |  String  |  None     |
|                        | given as input must not contain white spaces and        |          |           |
|                        | the reaction direction has to be specified as '-->'     |          |           |
|                        | or '<--'. Chemical species phases must be defined as    |          |           |
|                        | '(g)' for the fluid phase or '(s)' for the solid phase. |          |           |
+------------------------+---------------------------------------------------------+----------+-----------+
| mass_balance_tolerance | Tolerance used to test chemical formula conserves mass. | Real     | 1e-12     |
|                        |                                                         |          |           |
|                        |     abs( sum(products) - sum(reactants)) < tolerance    |          |           |
|                        |                                                         |          |           |
+------------------------+---------------------------------------------------------+----------+-----------+

Choosing the integrator type for the chemistry ODE integration operation that is
performed to determine the fluid and solids phases transfer quantities due to
chemical reactions. The ``StiffSolver`` class of integrators is inspired to the
class of integrators in AMReX-Astro/Microphysics
(https://github.com/AMReX-Astro/Microphysics)

+-------------------------+----------------------------------------------------------------------+----------+---------------+
|                         | Description                                                          |   Type   | Default       |
+=========================+======================================================================+==========+===============+
| chemistry.integrator    | Specified name of the chemistry ODE integrator type. Available types | String   | ForwardEuler  |
|                         | are (case insensitive):                                              |          |               |
|                         |                                                                      |          |               |
|                         | * ``ForwardEuler``                                                   |          |               |
|                         | * ``StiffSolver::ForwardEuler``                                      |          |               |
|                         | * ``StiffSolver::BackwardEuler``                                     |          |               |
|                         | * ``StiffSolver::VODE``                                              |          |               |
|                         |                                                                      |          |               |
+-------------------------+----------------------------------------------------------------------+----------+---------------+

One can define the environment variable ``VODE_JACOBIAN_CACHING`` at compile
time to enable caching of the numerical approximation of the Jacobian matrix
(the derivative of the ODE right-hand side), applicable when the VODE integrator
is selected. The following inputs can be specified using the
``chemistry.integrator`` prefix:

+--------------------------------+---------------------------------------------------------------+----------+---------+
|                                | Description                                                   |   Type   | Default |
+================================+===============================================================+==========+=========+
| burner_verbose                 | Enables the printing on screen of some integration statistics | int      | 0       |
+--------------------------------+---------------------------------------------------------------+----------+---------+
| 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      | int      | 0       |
|                                | solver. Available choices are:                                |          |         |
|                                |                                                               |          |         |
|                                | * 0 for a first-order numerical approximation                 |          |         |
|                                | * 1 for the analytical jacobian (not available yet)           |          |         |
+--------------------------------+---------------------------------------------------------------+----------+---------+
| 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                                |          |         |
+--------------------------------+---------------------------------------------------------------+----------+---------+
| ode_max_dt                     | Maximum timestep size for the ODE integration substeps        | Real     | 1.e30   |
+--------------------------------+---------------------------------------------------------------+----------+---------+
| maximum_timestep_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       |
|                                | switches on/off the 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, enables 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                                                  |          |         |
+--------------------------------+---------------------------------------------------------------+----------+---------+


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

.. code-block:: none

   chemistry.solve = my_reaction0 my_reaction1

   chemistry.my_reaction0.reaction = Fe2O3(s)+CO(g)-->2.FeO(s)+CO2(g)
   chemistry.my_reaction1.reaction = FeO(s)+0.25O2(g)-->0.5Fe2O3(s)

   chemistry.mass_balance_tolerance = 1.e-5

   chemistry.integrator = StiffSolver::BackwardEuler
   chemistry.integrator.atol = 1.e-8
   chemistry.integrator.rtol = 1.e-9
