.. _Chap:InputsMultigrid:

Multigrid solvers
=================

Nodal projection
----------------

The following inputs are defined using the prefix ``nodal_proj``:

+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                         |  Description                                                          |   Type      | Default      |
+=========================+=======================================================================+=============+==============+
| verbose                 |  Verbosity of multigrid solver in nodal projection.                   |  Int        |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_verbose          |  Verbosity of BiCGStab solver in nodal projection.                    |  Int        |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_rtol                 |  Relative tolerance in nodal projection.                              |  Real       |   1.e-11     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_atol                 |  Absolute tolerance in nodal projection.                              |  Real       |   1.e-14     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| maxiter                 |  Maximum number of iterations in the nodal projection.                |  Int        |   100        |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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 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     |
|                         |                                                                       |             |              |
|                         |  Options:                                                             |             |              |
|                         |                                                                       |             |              |
|                         |  * ``bicgcg``                                                         |             |              |
|                         |  * ``bicgstab``                                                       |             |              |
|                         |  * ``cg``                                                             |             |              |
|                         |  * ``cgbicg``                                                         |             |              |
|                         |  * ``hypre``                                                          |             |              |
|                         |  * ``smoother``                                                       |             |              |
|                         |                                                                       |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| hypre_namespace         |  Namespace to use in the nodal projection when using hypre            |  String     |   hypre      |
|                         |  to control hypre specific settings. It can be any string.            |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| hypre_interface         |  Which interface to use in the nodal projection when using ``hypre``. |  String     |   ij         |
|                         |                                                                       |             |              |
|                         |                                                                       |             |              |
|                         |  Options:                                                             |             |              |
|                         |                                                                       |             |              |
|                         |  * ``ij``                                                             |             |              |
|                         |  * ``semi-structured``                                                |             |              |
|                         |  * ``structured``                                                     |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+


MAC projection
--------------

The following inputs are defined using the prefix ``mac_proj``:

+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                         | Description                                                           |   Type      | Default      |
+=========================+=======================================================================+=============+==============+
| verbose                 |  Verbosity of multigrid solver in MAC projection.                     |    Int      |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_verbose          |  Verbosity of BiCGStab solver in MAC projection.                      |    Int      |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_rtol                 |  Relative tolerance in MAC projection.                                |    Real     |   1.e-11     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_atol                 |  Absolute tolerance in MAC projection.                                |    Real     |   1.e-14     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| maxiter                 |  Maximum number of iterations in the MAC projection.                  |    Int      |   200        |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_maxiter          |  Maximum number of iterations in the MAC projection                   |    Int      |   200        |
|                         |  bottom solver if using ``bicg``, ``cg``, ``bicgcg``, or ``cgbicg``.  |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_max_coarsening_level |  Maximum number of coarser levels to allow in the MAC 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 MAC projection.                    |  String     |   bicgcg     |
|                         |                                                                       |             |              |
|                         |  Options:                                                             |             |              |
|                         |                                                                       |             |              |
|                         |  * ``bicgcg``                                                         |             |              |
|                         |  * ``bicgstab``                                                       |             |              |
|                         |  * ``cg``                                                             |             |              |
|                         |  * ``cgbicg``                                                         |             |              |
|                         |  * ``hypre``                                                          |             |              |
|                         |  * ``smoother``                                                       |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| hypre_namespace         |  Namespace to use in the MAC projection when using ``hypre``          |  String     |   hypre      |
|                         |  to control hypre specific settings. It can be any string.            |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| hypre_interface         |  Which interface to use in the MAC projection when using ``hypre``.   |  String     |   ij         |
|                         |                                                                       |             |              |
|                         |  Options:                                                             |             |              |
|                         |                                                                       |             |              |
|                         |  * ``ij``                                                             |             |              |
|                         |  * ``semi-structured``                                                |             |              |
|                         |  * ``structured``                                                     |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+



Diffusion
---------

The following inputs are defined using the prefix ``diffusion``:

+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                         | Description                                                           |   Type      | Default      |
+=========================+=======================================================================+=============+==============+
| verbose                 |  Verbosity of linear solver for diffusion.                            |    Int      |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_verbose          |  Verbosity of BiCGStab solver in diffusion.                           |    Int      |   0          |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_rtol                 |  Relative tolerance in diffusion solver.                              |    Real     |   1.e-11     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_atol                 |  Absolute tolerance in diffusion solver.                              |    Real     |   1.e-14     |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| maxiter                 |  Maximum number of iterations in diffusion solver.                    |    Int      |   100        |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_maxiter          |  Maximum number of iterations in diffusion solver                     |    Int      |   100        |
|                         |  bottom solver if using ``bicg``, ``cg``, ``bicgcg``, or ``cgbicg``.  |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| mg_max_coarsening_level |  Maximum number of coarser levels to allow in diffusion solver.       |    Int      |   100        |
|                         |  If set to 0, the bottom solver will be called at the current level.  |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bottom_solver           |  Which bottom solver to use for diffusion.                            |  String     |   bicgcg     |
|                         |                                                                       |             |              |
|                         |  Options:                                                             |             |              |
|                         |                                                                       |             |              |
|                         |  * ``bicgcg``                                                         |             |              |
|                         |  * ``bicgstab``                                                       |             |              |
|                         |  * ``cg``                                                             |             |              |
|                         |  * ``cgbigc``                                                         |             |              |
|                         |  * ``smoother``                                                       |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+


Hypre Settings
--------------

``hypre`` settings are specified using the following inputs which are read directly by AMReX when ``hypre`` is used as
the bottom solver for the MAC and/or nodal projections. By default, these inputs are defined using the
prefix ``hypre``, however different settings for the nodal and MAC projections can be used by specifying
a ``hypre_namespace`` for each solver.

.. warning::

  * MFIX-Exa must be built with ``hypre`` enabled to use ``hypre`` as the bottom solver.
  * 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 are all case-sensitive.

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      |
+===================================+=======================================================================+=============+==============+
| hypre_preconditioner              |  Type of preconditioner when using ``hypre``.                         |  String     |   none       |
|                                   |                                                                       |             |              |
|                                   |  Options:                                                             |             |              |
|                                   |                                                                       |             |              |
|                                   |  * ``none`` - no preconditioner                                       |             |              |
|                                   |  * ``BoomerAMG``                                                      |             |              |
|                                   |  * ``euclid``                                                         |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| recompute_preconditioner          |  Recompute preconditioner during runs.                                |   Bool      |   true       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| hypre_solver                      |  Type of hypre solver.                                                |   String    |  BoomerAMG   |
|                                   |                                                                       |             |              |
|                                   |  Options:                                                             |             |              |
|                                   |                                                                       |             |              |
|                                   |  * ``BoomerAMG``                                                      |             |              |
|                                   |  * ``GMRES``                                                          |             |              |
|                                   |  * ``COGMRES``                                                        |             |              |
|                                   |  * ``LGMRES``                                                         |             |              |
|                                   |  * ``FlexGMRES``                                                      |             |              |
|                                   |  * ``BiCGSTAB``                                                       |             |              |
|                                   |  * ``PCG``                                                            |             |              |
|                                   |  * ``Hybrid``                                                         |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| verbose                           |  Verbosity of hypre.                                                  |   Int       |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| num_krylov                        |  Number of iterations.                                                |   Int       |  50          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| adjust_singular_matrix            |  Enable if the problem to be solved has a singular matrix.            |   Bool      |  false       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| overwrite_existing_matrix_files   |  Overwrite existing matrix files.                                     |   Bool      |  false       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| write_matrix_files                |  Write matrix into text files.                                        |   Bool      |  false       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+

The following inputs are valid when using ``BoomerAMG`` as a preconditioner or solver.  They must be defined using the
prefix ``hypre``:

+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                                   |  Description                                                          |   Type      | Default      |
+===================================+=======================================================================+=============+==============+
| bamg_agg_interp_type              | See ``HYPRE_BoomerAMGSetAggInterpType``.                              |    Int      |   4          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_agg_num_levels               | See ``HYPRE_BoomerAMGSetAggNumLevels``.                               |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_agg_pmax_elmts               | See ``HYPRE_BoomerAMGSetAggPMaxElmts``.                               |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_coarse_relax_type            | See ``HYPRE_BoomerAMGSetCycleRelaxType``.                             |    Int      |   11         |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_coarsen_type                 | See ``HYPRE_BoomerAMGSetCoarsenType``.                                |    Int      |   6          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_cycle_type                   | See ``HYPRE_BoomerAMGSetCycleType``.                                  |    Int      |   1          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_down_relax_type              | See ``HYPRE_BoomerAMGSetCycleRelaxType``.                             |    Int      |   11         |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_interp_type                  | See ``HYPRE_BoomerAMGSetInterpType``.                                 |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_keep_transpose               | See ``HYPRE_BoomerAMGSetKeepTranspose``.                              |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_logging                      | See ``HYPRE_BoomerAMGSetLogging``.                                    |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_max_coarse_size              | See ``HYPRE_BoomerAMGSetMaxCoarseSize``.                              |    Int      |   9          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_max_iterations               | See ``HYPRE_BoomerAMGSetMaxIter``.                                    |    Int      |   1          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_max_levels                   | See ``HYPRE_BoomerAMGSetMaxLevels``.                                  |    Int      |   20         |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_min_coarse_size              | See ``HYPRE_BoomerAMGSetMinCoarseSize``.                              |    Int      |   1          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_coarse_sweeps            | See ``HYPRE_BoomerAMGSetCycleNumSweeps``.                             |    Int      |   1          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_down_sweeps              | See ``HYPRE_BoomerAMGSetCycleNumSweeps``.                             |    Int      |   2          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_down_sweeps              | See ``HYPRE_BoomerAMGSetCycleNumSweeps``.                             |    Int      |   2          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_sweeps                   | See ``HYPRE_BoomerAMGSetNumSweeps``.                                  |    Int      |   2          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_sweeps                   | See ``HYPRE_BoomerAMGSetNumSweeps``.                                  |    Int      |   2          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_up_sweeps                | See ``HYPRE_BoomerAMGSetCycleNumSweeps``.                             |    Int      |   2          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_pmax_elmts                   | See ``HYPRE_BoomerAMGSetPMaxElmts``.                                  |    Int      |   4          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_precond_tolerance            | See ``HYPRE_BoomerAMGSetTol``.                                        |    Real     |   0.0        |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_relax_order                  | See ``HYPRE_BoomerAMGSetRelaxOrder``.                                 |    Int      |   1          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_relax_type                   | See ``HYPRE_BoomerAMGSetRelaxType``.                                  |    Int      |   6          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_set_restriction              | See ``HYPRE_BoomerAMGSetRestriction``.                                |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_strong_threshold             | See ``HYPRE_BoomerAMGSetStrongThreshold``.                            |    Real     |   0.57       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_trunc_factor                 | See ``HYPRE_BoomerAMGSetTruncFactor``.                                |    Real     |   0.1        |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_up_relax_type                | See ``HYPRE_BoomerAMGSetCycleRelaxType``.                             |    Int      |   11         |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_variant                      | See ``HYPRE_BoomerAMGSetVariant``.                                    |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_verbose                      | Set ``BoomerAMG`` verbosity.                                          |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+


.. note::

   This list is likely incomplete because the  AMReX / `hypre` interface continues to evolve.
