diff --git a/docs/source_docs/user_guide/inputs/multigrid-solvers.rst b/docs/source_docs/user_guide/inputs/multigrid-solvers.rst index 9a6b9a0977d241b4abffc610954ca82bf165a21d..c8d248548d274ad99f113510e4cf37700c7830c9 100644 --- a/docs/source_docs/user_guide/inputs/multigrid-solvers.rst +++ b/docs/source_docs/user_guide/inputs/multigrid-solvers.rst @@ -3,17 +3,10 @@ Multigrid solvers ================= -The following inputs can be set directly in the AMReX solver classes but we -set them via the MFIX-Exa routines because we may want different inputs for the -different solvers called by MFIX-Exa. - Nodal projection ---------------- -NOTE: the nodal solver settings are read in directly by AMReX, -the MAC and diffusion settings by MFIX-Exa. - -These control the nodal projection and must be preceded by "nodal_proj.": +The following inputs are defined using the ``nodal_proj`` prefix. +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | @@ -31,7 +24,7 @@ These control the nodal projection and must be preceded by "nodal_proj.": | bottom_maxiter | Maximum number of iterations in the nodal projection | Int | 100 | | | bottom solver if using bicg, cg, bicgcg or cgbicg | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_max_coarsening_level | Maximum number of coarser levels to allowin the nodal projection | Int | 100 | +| mg_max_coarsening_level | Maximum number of coarser levels to allow in the nodal projection | Int | 100 | | | If set to 0, the bottom solver will be called at the current level | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | bottom_solver | Which bottom solver to use in the nodal projection | String | bicgcg | @@ -50,7 +43,7 @@ These control the nodal projection and must be preceded by "nodal_proj.": MAC projection -------------- -These control the MAC projection and must be preceded by "mac_proj.": +The following inputs are defined using the ``mac_proj`` prefix. +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | @@ -83,120 +76,158 @@ These control the MAC projection and must be preceded by "mac_proj.": | | Options are ij, semi_structured or structured | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -NOTE: If the :cpp:`nodal_proj` and :cpp:`mac_proj` :cpp:`hypre_namespace`'s are set, they must be distinct unless set to -:cpp:`hypre`, in which case the default behavior is recovered in which case hypre settings apply to all solvers. Diffusion --------- -These control the diffusion solver and must be preceded by "diffusion.": +The following inputs are defined using the ``diffusion`` prefix. +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | +=========================+=======================================================================+=============+==============+ -| verbose | Verbosity of linear solver for diffusion solve | Int | 0 | +| verbose | Verbosity of linear solver for diffusion solve | int | 0 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bottom_verbose | Verbosity of BiCGStab solver in diffusion solve | Int | 0 | +| bottom_verbose | Verbosity of BiCGStab solver in diffusion solve | int | 0 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | mg_rtol | Relative tolerance in diffusion solve | Real | 1.e-11 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ | mg_atol | Absolute tolerance in diffusion solve | Real | 1.e-14 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| maxiter | Maximum number of iterations in diffusion solve | Int | 100 | +| maxiter | Maximum number of iterations in diffusion solve | int | 100 | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bottom_maxiter | Maximum number of iterations in diffusion solve | Int | 100 | +| bottom_maxiter | Maximum number of iterations in diffusion solve | int | 100 | | | bottom solver if using bicg, cg, bicgcg or cgbicg | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| mg_max_coarsening_level | Maximum number of coarser levels to allow in diffusion solve | Int | 100 | +| mg_max_coarsening_level | Maximum number of coarser levels to allow in diffusion solve | int | 100 | | | If set to 0, the bottom solver will be called at the current level | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bottom_solver | Which bottom solver to use in the diffusion solve | String | bicgcg | +| bottom_solver | Which bottom solver to use in the diffusion solve | string | bicgcg | | | | | | | | Options are bicgcg, bicgstab, cg, cgbicg, or smoother | | | +-------------------------+-----------------------------------------------------------------------+-------------+--------------+ - Hypre Settings -------------- -The following inputs control the hypre settings and are read directly -by AMReX when we use hypre as the bottom solver, i.e., when -:cpp:`nodal_proj.bottom_solver = hypre` and/or when -:cpp:`mac_proj.bottom_solver = hypre` (see :ref:`Chap:InputsMultigrid`) -These settings must be preceded by the hypre_namespace setting corresponding -to the solver (see :ref:`Chap:InputsMultigrid`). - -NOTE: By default, the MAC and nodal projections use the same settings -specified with the namespace :cpp:`hypre`, however the solvers can be configured -separately by specifying :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace`. - -When not using the default namespace :cpp:`hypre`, additional restrictions apply: +`hypre` settings are specified using the following inputs which are read directly by AMReX when `hypre` is used as +the bottom solve for the MAC and/or nodal projections. By default, these inputs are defined using the +``hypre`` prefix, however different settings for the nodal and MAC projections can be used by specifying +a ``hpyre_namespace`` for each solver. -#. Both :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be set. +.. warning:: -#. :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be unique. + * MFIX-Exa must be built with `hypre` enabled to use `hypre` as the bottom solve. + * If `hypre` is used for the nodal and MAC projections, then either the ``hypre_namespace`` must be left as the default (``hypre``) + or unique name spaces must be provided for both. +These inputs follow the typical approach for using `hypre` in MFIX-Exa where `BoomerAMG` is employed as a preconditioner +and `GMRES` for the linear solver. +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ | | Description | Type | Default | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| verbose | Verbosity of hypre | Int | 0 | +| hypre_preconditioner | Type of preconditioner | string | none | +| | | | | +| | Options are BoomerAMG or euclid | | | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| adjust_singular_matrix | Should be true if the problem to be solved has singular matrix | Bool | false | +| recompute_preconditioner | Recompute preconditioner during runs | Bool | true | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| hypre_solver | Type of hypre solver | String | BoomerAMG | +| hypre_solver | Type of hypre solver | string | BoomerAMG | | | | | | | | Options are BoomerAMG, GMRES, COGMRES, LGMRES, FlexGMRES, BiCGSTAB, | | | | | PCG or Hybrid | | | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| hypre_preconditioner | Type of preconditioner | String | none | -| | | | | -| | Options are BoomerAMG or euclid | | | +| verbose | Verbosity of hypre | int | 0 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| recompute_preconditioner | Recompute preconditioner during runs | Bool | true | +| num_krylov | Number of iterations | int | 50 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| write_matrix_files | Write out matrix into text files | Bool | false | + + +The following inputs are valid when using ``BoomerAMG`` as a preconditioner or solver. + +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| overwrite_existing_matrix_files | Over-write existing matrix files | Bool | false | +| | Description | Type | Default | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_verbose | Verbosity of BoomerAMG preconditioner | Int | 0 | +| bamg_verbose | Set BoomerAMG verbosity | int | 0 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_logging | When using BoomerAMG preconditioner | Int | 0 | -| | | | | -| | See HYPRE_BoomerAMGSetLogging | | | +| bamg_logging | See HYPRE_BoomerAMGSetLogging | int | 0 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_coarsen_type | When using BoomerAMG preconditioner | Int | 6 | -| | | | | -| | See HYPRE_BoomerAMGSetCoarsenType | | | +| bamg_max_iterations | See HYPRE_BoomerAMGSetMaxIter | int | 1 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_cycle_type | When using BoomerAMG preconditioner | Int | 1 | -| | | | | -| | See HYPRE_BoomerAMGSetCycleType | | | +| bamg_precond_tolerance | See HYPRE_BoomerAMGSetTol | Real | 0.0 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_relax_type | When using BoomerAMG preconditioner | Int | 6 | -| | | | | -| | See HYPRE_BoomerAMGSetRelaxType | | | +| bamg_coarsen_type | See HYPRE_BoomerAMGSetCoarsenType | int | 6 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_relax_order | When using BoomerAMG preconditioner | Int | 1 | -| | | | | -| | See HYPRE_BoomerAMGSetRelaxOrder | | | +| bamg_cycle_type | See HYPRE_BoomerAMGSetCycleType | int | 1 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_num_sweeps | When using BoomerAMG preconditioner | Int | 2 | -| | | | | -| | See HYPRE_BoomerAMGSetNumSweeps | | | +| bamg_relax_order | See HYPRE_BoomerAMGSetRelaxOrder | int | 1 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_max_levels | When using BoomerAMG preconditioner | Int | 20 | -| | | | | -| | See HYPRE_BoomerAMGSetMaxLevels | | | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_strong_threshold | When using BoomerAMG preconditioner | Real | 0.57 | -| | | | | -| | See HYPRE_BoomerAMGSetStrongThreshold | | | +| bamg_relax_type | See HYPRE_BoomerAMGSetRelaxType | int | 6 | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ -| bamg_interp_type | When using BoomerAMG preconditioner | Int | 0 | -| | | | | -| | HYPRE_BoomerAMGSetInterpType | | | +-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_down_relax_type | See HYPRE_BoomerAMGSetCycleRelaxType | int | 11 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_up_relax_type | See HYPRE_BoomerAMGSetCycleRelaxType | int | 11 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_coarse_relax_type | See HYPRE_BoomerAMGSetCycleRelaxType | int | 11 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_num_sweeps | See HYPRE_BoomerAMGSetNumSweeps | int | 2 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_num_down_sweeps | See HYPRE_BoomerAMGSetCycleNumSweeps | int | 2 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_num_up_sweeps | See HYPRE_BoomerAMGSetCycleNumSweeps | int | 2 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_num_coarse_sweeps | See HYPRE_BoomerAMGSetCycleNumSweeps | int | 1 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_max_levels | See HYPRE_BoomerAMGSetMaxLevels | int | 20 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_strong_threshold | See HYPRE_BoomerAMGSetStrongThreshold | Real | 0.57 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_interp_type | See HYPRE_BoomerAMGSetInterpType | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_variant | See HYPRE_BoomerAMGSetVariant | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_keep_transpose | See HYPRE_BoomerAMGSetKeepTranspose | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_min_coarse_size | See HYPRE_BoomerAMGSetMinCoarseSize | int | 1 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_max_coarse_size | See HYPRE_BoomerAMGSetMaxCoarseSize | int | 9 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_pmax_elmts | See HYPRE_BoomerAMGSetPMaxElmts | int | 4 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_agg_num_levels | See HYPRE_BoomerAMGSetAggNumLevels | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_agg_interp_type | See HYPRE_BoomerAMGSetAggInterpType | int | 4 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_agg_pmax_elmts | See HYPRE_BoomerAMGSetAggPMaxElmts | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_trunc_factor | See HYPRE_BoomerAMGSetTruncFactor | Real | 0.1 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| bamg_set_restriction | See HYPRE_BoomerAMGSetRestriction | int | 0 | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ + + + + + + + ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| | Description | Type | Default | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| adjust_singular_matrix | Should be true if the problem to be solved has singular matrix | Bool | false | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ +| overwrite_existing_matrix_files | Over-write existing matrix files | Bool | false | ++-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+ + + +.. note:: + This list is likely incomplete because the AMReX / `hypre` interface continues to evolve.