Loading docs/source_docs/user_guide/inputs/chemical_reactions.rst +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 Loading @@ -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``. | | | Loading @@ -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. | | | Loading @@ -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 Loading
docs/source_docs/user_guide/inputs/chemical_reactions.rst +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 Loading @@ -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``. | | | Loading @@ -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. | | | Loading @@ -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