# Hypre

### From Gerris

The Hypre module makes available some features of the high-performance preconditioning library Hypre, in particular its algebraic multigrid for use instead of Gerris' native multigrid solver for Poisson equations.

There are some special notes on installing Hypre for use with Gerris.

The parameters of the Hypre module can be tuned using an optional parameter block. For example

GModule hypre { solver_type = boomer_amg precond_type = none relax_type = gs-j coarsening_type = cgc_e cycle_type = 1 nlevel = 0 verbose = 0 }

where the values are set to their default. The parameters are

`solver_type`

- the type of solver to be used,
`relax_type`

- the type of relaxation to use for the AMG solver,
`coarsening_type`

- the coarsening algorithm to use for the AMG solver,
`relax_type`

- the type of cycle to use for the AMG solver,
`nlevel`

- the maximum number of multigrid levels for the AMG solver (setting this to zero will use the depth of the quad/octree),
`verbose`

- selects whether Hypre should print its own statistics.

So far, only two types of solvers are available:

`boomer_amg`

- the AMG solver,
`pcj`

- a preconjugate gradient solver.

For the AMG solver various types of cycles can be used and several algorithms are available for relaxation and coarsening. Please refer to the documentation page of the Hypre library for more details on the different algorithms. The keywords for the different relaxation algorithms are:

`jacobi`

- Jacobi or CF-Jacobi,
`gauss_seidel`

- Gauss-Seidel, sequential (very slow!),
`sor-j-forward`

- Hybrid: SOR-J mix off-processor, SOR on-processor with outer relaxation parameters (forward solve),
`sor-j-backward`

- Hybrid: SOR-J mix off-processor, SOR on-processor with outer relaxation parameters (backward solve),
`ssor-j`

- Hybrid: SSOR-J mix off-processor, SSOR on-processor with outer relaxation parameters,
`gs-j`

- Hybrid: GS-J mix off-processor, chaotic GS on-node,
`matvec-jacobi`

- Jacobi (uses Matvec), only needed in CGNR.

The keywords for the different coarsening algorithms are:

`cljp`

- CLJP-coarsening - a parallel coarsening algorithm using independent sets,
`ruge_stueben`

- Classical Ruge-Stueben coarsening on each processor, followed by a third pass, which adds coarse points on the boundaries,
`falgout`

- Falgout coarsening (uses 1 first, followed by CLJP using the interior coarse points generated by 1 as its first independent set) ,
`pmis`

- PMIS-coarsening (a parallel coarsening algorithm using independent sets, generating lower complexities than CLJP, might also lead to slower convergence),
`hmis`

- HMIS-coarsening (uses one pass Ruge-Stueben on each processor independently, followed by PMIS using the interior C-points generated as its first independent set),
`cgc`

- CGC coarsening by M. Griebel, B. Metsch and A. Schweitzer,
`cgc_e`

- CGC-E coarsening by M. Griebel, B. Metsch and A. Schweitzer.

For compatibility with Gerris' default solver, the Hypre module also uses the following parameters, set using GfsApproxProjectionsParams and GfsProjectionParams:

`tolerance`

- the convergence threshold,
`nitermin`

- the minimum number of iterations,
`nitermax`

- the maximum number of iterations,
`nrelax`

- the number of relaxation sweeps on each level.

Note that Hypre uses the RMS-norm of the residual to define its convergence tolerance criteria (rather than the maximum for Gerris). It also calculates the RMS-norm in a different way than Gerris. This is partly related to the fact that the Hypre module solves a linear probem for which each stencil has been non-dimensionalised by the size of the diagonal cell, whereas the residual norm in Gerris takes into account the volume of all the cells of the domain. Also, whereas Gerris calculates the norm of the residual only over all the cells of the domain, Hypre takes into accounts the ghost cells at the boundaries of the domain. To account partially for the difference, a correction factor defined as <math> \sqrt \right( \frac{ \sum_1^n cell_volume }{n} \left) </math> where n is the number of cells in the domain is used to rescale the norm residual calculated by Hypre.