From 4890e894902caff80f0e64514cd76193719fc587 Mon Sep 17 00:00:00 2001 From: Roberto Porcu Date: Tue, 17 Dec 2024 18:26:20 -0500 Subject: [PATCH 1/6] start adding ODE integrator inputs --- .../user_guide/inputs/chemical_reactions.rst | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 73111dd..851e225 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -28,3 +28,68 @@ The following inputs must be preceded by the "chemistry." prefix my_reaction0.reaction = Fe2O3(s)+CO(g)-->2.FeO(s)+CO2(g) my_reaction1.reaction = FeO(s)+0.25O2(g)-->0.5Fe2O3(s) + + +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. + ++-------------------------+----------------------------------------------------------------------+----------+---------------+ +| | Description | Type | Default | ++=========================+======================================================================+==========+===============+ +| mfix.integrator | Specified name of the chemistry ODE integrator type. Available types | String | ForwardEuler | +| | are: | | | +| | | | | +| | * ``ForwardEuler`` | | | +| | * ``StiffSolver::ForwardEuler`` | | | +| | * ``StiffSolver::BackwardEuler`` | | | +| | * ``StiffSolver::VODE`` | | | +| | | | | ++-------------------------+----------------------------------------------------------------------+----------+---------------+ + +It is possible to define the environmental variable ``VODE_JACOBIAN_CACHING`` at +compile time, which enables the possibility to cache the numerical approximation +of the Jacobian matrix (derivative of the ODE right-hand side) if the VODE +integrator is chosen by the user. +The following inputs must be preceded by the "mfix.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 convergence test of the internal | Real | 1.e-6 | +| | Newton solver | | | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| rtol | Relative tolerance for the convergence test of the internal | Real | 1.e-6 | +| | Newton solver | | | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| retry_atol | | Real | -1 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| retry_rtol | | Real | -1 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| retry_swap_jacobian | | int | 1 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| ode_max_dt | Maximum timestep size for the ODE integration substeps | Real | 1.e30 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| maximum_timestep_change_factor | | Real | 1.001 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| max_iter | Maximum number of iterations for the internal Newton solver | int | 100 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| linalg_do_pivoting | | int | 1 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| rp_rtol | | Real | 1.e-6 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| use_jacobian_caching | Only for VODE, enables caching the numerical jacobian | int | 1 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ +| X_reject_buffer | | Real | 1.0 | ++--------------------------------+---------------------------------------------------------------+----------+---------------+ -- GitLab From c7230d0475fea40b392ad4416d686dfbeea4c835 Mon Sep 17 00:00:00 2001 From: Roberto Porcu Date: Tue, 17 Dec 2024 19:31:46 -0500 Subject: [PATCH 2/6] complete the description of the integrator inputs --- .../user_guide/inputs/chemical_reactions.rst | 90 ++++++++++--------- 1 file changed, 50 insertions(+), 40 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 851e225..04054f9 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -39,7 +39,7 @@ class of integrators in AMReX-Astro/Microphysics. | | Description | Type | Default | +=========================+======================================================================+==========+===============+ | mfix.integrator | Specified name of the chemistry ODE integrator type. Available types | String | ForwardEuler | -| | are: | | | +| | are (case insensitive): | | | | | | | | | | * ``ForwardEuler`` | | | | | * ``StiffSolver::ForwardEuler`` | | | @@ -54,42 +54,52 @@ of the Jacobian matrix (derivative of the ODE right-hand side) if the VODE integrator is chosen by the user. The following inputs must be preceded by the "mfix.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 convergence test of the internal | Real | 1.e-6 | -| | Newton solver | | | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| rtol | Relative tolerance for the convergence test of the internal | Real | 1.e-6 | -| | Newton solver | | | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| retry_atol | | Real | -1 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| retry_rtol | | Real | -1 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| retry_swap_jacobian | | int | 1 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| ode_max_dt | Maximum timestep size for the ODE integration substeps | Real | 1.e30 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| maximum_timestep_change_factor | | Real | 1.001 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| max_iter | Maximum number of iterations for the internal Newton solver | int | 100 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| linalg_do_pivoting | | int | 1 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| rp_rtol | | Real | 1.e-6 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| use_jacobian_caching | Only for VODE, enables caching the numerical jacobian | int | 1 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ -| X_reject_buffer | | Real | 1.0 | -+--------------------------------+---------------------------------------------------------------+----------+---------------+ ++--------------------------------+---------------------------------------------------------------+----------+---------+ +| | 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 | | | ++--------------------------------+---------------------------------------------------------------+----------+---------+ -- GitLab From d060bde271278b5f7b65b5345ff749adfc1a518d Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 18 Dec 2024 11:15:38 -0500 Subject: [PATCH 3/6] Update namespace from mfix to chemistry --- docs/source_docs/user_guide/inputs/chemical_reactions.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 04054f9..b7898a4 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -38,7 +38,7 @@ class of integrators in AMReX-Astro/Microphysics. +-------------------------+----------------------------------------------------------------------+----------+---------------+ | | Description | Type | Default | +=========================+======================================================================+==========+===============+ -| mfix.integrator | Specified name of the chemistry ODE integrator type. Available types | String | ForwardEuler | +| chemistry.integrator | Specified name of the chemistry ODE integrator type. Available types | String | ForwardEuler | | | are (case insensitive): | | | | | | | | | | * ``ForwardEuler`` | | | @@ -52,7 +52,8 @@ It is possible to define the environmental variable ``VODE_JACOBIAN_CACHING`` at compile time, which enables the possibility to cache the numerical approximation of the Jacobian matrix (derivative of the ODE right-hand side) if the VODE integrator is chosen by the user. -The following inputs must be preceded by the "mfix.integrator" prefix: + +The following inputs are defined using the ``mfix.chemistry`` prefix. +--------------------------------+---------------------------------------------------------------+----------+---------+ | | Description | Type | Default | -- GitLab From 4d6e17a4d070c764be1d31da27de00d72e68eb29 Mon Sep 17 00:00:00 2001 From: Jordan Musser Date: Wed, 18 Dec 2024 11:23:19 -0500 Subject: [PATCH 4/6] Add mass_balance_tolerance --- docs/source_docs/user_guide/inputs/chemical_reactions.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index b7898a4..7cbb27d 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -10,7 +10,7 @@ Enabling the Chemical Reactions solver and specifying model options. | | the reactions solver. | | | +-------------------------+----------------------------------------------------------------------+----------+-----------+ -The following inputs must be preceded by the "chemistry." prefix +The following inputs are defined using the ``mfix.chemistry`` prefix. +------------------------+---------------------------------------------------------+----------+-----------+ | | Description | Type | Default | @@ -21,6 +21,11 @@ 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 | | | +| | | | | ++------------------------+---------------------------------------------------------+----------+-----------+ .. code-block:: none -- GitLab From 71b39dc91a6ac14f0e77454bef30a7dab9f04935 Mon Sep 17 00:00:00 2001 From: Roberto Porcu Date: Wed, 18 Dec 2024 12:20:52 -0500 Subject: [PATCH 5/6] improve the chemistry example code --- .../user_guide/inputs/chemical_reactions.rst | 52 +++++++++++-------- 1 file changed, 30 insertions(+), 22 deletions(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index 7cbb27d..e42048a 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 are defined using the ``mfix.chemistry`` prefix. +The following inputs are defined using the ``chemistry`` prefix. +------------------------+---------------------------------------------------------+----------+-----------+ | | Description | Type | Default | @@ -27,18 +27,11 @@ The following inputs are defined using the ``mfix.chemistry`` prefix. | | | | | +------------------------+---------------------------------------------------------+----------+-----------+ -.. 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) - - 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. +class of integrators in AMReX-Astro/Microphysics +(https://github.com/AMReX-Astro/Microphysics) +-------------------------+----------------------------------------------------------------------+----------+---------------+ | | Description | Type | Default | @@ -53,12 +46,11 @@ class of integrators in AMReX-Astro/Microphysics. | | | | | +-------------------------+----------------------------------------------------------------------+----------+---------------+ -It is possible to define the environmental variable ``VODE_JACOBIAN_CACHING`` at -compile time, which enables the possibility to cache the numerical approximation -of the Jacobian matrix (derivative of the ODE right-hand side) if the VODE -integrator is chosen by the user. - -The following inputs are defined using the ``mfix.chemistry`` prefix. +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 | @@ -109,3 +101,19 @@ The following inputs are defined using the ``mfix.chemistry`` prefix. | | 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 -- GitLab From f2f6d2fbfdeb9c9a38f9f117c6ab240d46be2d6c Mon Sep 17 00:00:00 2001 From: Roberto Porcu Date: Wed, 18 Dec 2024 12:23:34 -0500 Subject: [PATCH 6/6] minor fix in chemistry inputs --- docs/source_docs/user_guide/inputs/chemical_reactions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source_docs/user_guide/inputs/chemical_reactions.rst b/docs/source_docs/user_guide/inputs/chemical_reactions.rst index e42048a..0306be9 100644 --- a/docs/source_docs/user_guide/inputs/chemical_reactions.rst +++ b/docs/source_docs/user_guide/inputs/chemical_reactions.rst @@ -50,7 +50,7 @@ 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: +``chemistry.integrator`` prefix: +--------------------------------+---------------------------------------------------------------+----------+---------+ | | Description | Type | Default | -- GitLab