diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 73111ddf4bc13275eba96aad9e14419002b004fe..0306be9a8cc8ecbb14d81f04a479681b8cde6abe 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -3,14 +3,14 @@ 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 | String | None | -| | the reactions solver. | | | -+-------------------------+----------------------------------------------------------------------+----------+-----------+ ++----------------------------------+-------------------------------------------------------------+----------+-----------+ +| | 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 must be preceded by the "chemistry." prefix +The following inputs are defined using the ``chemistry`` prefix. +------------------------+---------------------------------------------------------+----------+-----------+ | | Description | Type | Default | @@ -21,10 +21,99 @@ The following inputs must be preceded by the "chemistry." prefix | | 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 - my_reaction0.reaction = Fe2O3(s)+CO(g)-->2.FeO(s)+CO2(g) - my_reaction1.reaction = FeO(s)+0.25O2(g)-->0.5Fe2O3(s) + 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