# 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
solids.update_type | When updating the solids quantities in chemistry due to chemical reactions, choose the update type among: `ConstantVolume` keep particles’ volume constant `ConstantDensity` keep particles’ density constant | String | ConstantVolume
solids.mass_threshold | Sets a threshold value for the particles’ mass. When updating the solids quantities in chemistry, check whether the solids mass is below the threshold, and in that case set the particle as invalid and remove it | Real | 0
solids.radius_threshold | Sets a threshold value for the particles’ radius. When updating the solids quantities in chemistry, check whether the solids radius is below the threshold, and in that case set the particle as invalid and remove it | Real | 0
solids.density_threshold | Sets a threshold value for the particles’ density. When updating the solids quantities in chemistry, check whether the solids density is below the threshold, and in that case set the particle as invalid and remove it | Real | 0

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: `Numerical` for a first-order numerical approximation `Broyden` for Broyden’s method (only for BackwardEuler) | string | Numerical
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
max_dt_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