# 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 to disable the reactions solver. | String | None

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

| Description | Type | Default
--- | --- | --- | ---
[reaction0].reaction | Chemical formula for the given reaction. The string 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. | String | None
mass_balance_tolerance | Tolerance used to test chemical formula conserves mass. abs( sum(products) - sum(reactants)) < tolerance | Real | 1e-12

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 are (case insensitive): `ForwardEuler` `StiffSolver::ForwardEuler` `StiffSolver::BackwardEuler` `StiffSolver::VODE` | String | ForwardEuler

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 solver. Available choices are: 0 for a first-order numerical approximation 1 for the analytical jacobian (not available yet) | int | 0
atol | Absolute tolerance for the ODE integration error test between the solution and the fine-step solution | Real | 1.e-6
rtol | Relative tolerance for the ODE integration error test between the solution and the fine-step solution | Real | 1.e-6
retry_atol | Overwrites the absolute tolerance value atol in case the ODE integration fails | Real | -1
retry_rtol | Overwrites the relative tolerance value rtol in case the ODE integration fails | Real | -1
retry_swap_jacobian | Swaps the type of jacobian (from 1 to 0 or vice versa) in case the ODE integration fails | int | 1
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 for the change of the timestep for the internal substeps | Real | 1.001
max_iter | Maximum number of iterations for the internal Newton solver | int | 100
linalg_do_pivoting | Only for StiffSolver::BackwardEuler and StiffSolver::VODE, switches on/off the pivoting when solving the linear algebra problem associated to the internal Newton solver | int | 1
rp_rtol | Relative tolerance for the convergence test of the internal Newton solver. Valid only for StiffSolver::BackwardEuler | Real | 1.e-6
use_jacobian_caching | Only for StiffSolver::VODE, enables caching the numerical jacobian | int | 1
X_reject_buffer | Only for StiffSolver::VODE, constrain species abundances such that they don’t change by more than a certain factor in a given step | Real | 1.0

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

    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