.. _Chap:InputsMultigrid:

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.":

+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                         |  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 allowin 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 are bicgcg, bicgstab, cg, cgbicg, smoother or hypre          |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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 are ij, semi_structured or structured                        |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+


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

These control the MAC projection and must be preceded by "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 are bicgcg, bicgstab, cg, cgbicg, smoother or hypre          |             |              |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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 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.":

+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                         | Description                                                           |   Type      | Default      |
+=========================+=======================================================================+=============+==============+
| verbose                 |  Verbosity of linear solver for 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        |
+-------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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        |
|                         |  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     |
|                         |                                                                       |             |              |
|                         |  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:

#. Both :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be set.

#. :cpp:`mac_proj.hypre_namespace` and :cpp:`nodal_proj.hypre_namespace` must be unique.


+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
|                                   |  Description                                                          |   Type      | Default      |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| verbose                           |  Verbosity of hypre                                                   |   Int       |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| adjust_singular_matrix            |  Should be true if the problem to be solved has singular matrix       |   Bool      |   false      |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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                                      |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| recompute_preconditioner          |  Recompute preconditioner during runs                                 |    Bool     |   true       |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| write_matrix_files                |  Write out matrix into text files                                     |    Bool     |   false      |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| overwrite_existing_matrix_files   |  Over-write existing matrix files                                     |    Bool     |   false      |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_verbose                      |  Verbosity of BoomerAMG preconditioner                                |    Int      |   0          |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_logging                      |  When using BoomerAMG preconditioner                                  |    Int      |   0          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetLogging                                        |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_coarsen_type                 |  When using BoomerAMG preconditioner                                  |    Int      |   6          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetCoarsenType                                    |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_cycle_type                   |  When using BoomerAMG preconditioner                                  |    Int      |   1          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetCycleType                                      |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_relax_type                   |  When using BoomerAMG preconditioner                                  |    Int      |   6          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetRelaxType                                      |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_relax_order                  |  When using BoomerAMG preconditioner                                  |    Int      |   1          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetRelaxOrder                                     |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| bamg_num_sweeps                   |  When using BoomerAMG preconditioner                                  |    Int      |   2          |
|                                   |                                                                       |             |              |
|                                   |  See HYPRE_BoomerAMGSetNumSweeps                                      |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+
| 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_interp_type                  |  When using BoomerAMG preconditioner                                  |    Int      |   0          |
|                                   |                                                                       |             |              |
|                                   |  HYPRE_BoomerAMGSetInterpType                                         |             |              |
+-----------------------------------+-----------------------------------------------------------------------+-------------+--------------+

