Appendix: Linear Solvers

Linear solvers solve each equation’s linearized system within a nonlinear iteration. Select one with linearSolver in the corresponding equation options. The global settings below supply defaults; equation options can override the tolerance and PETSc solver name.

Global Linear Solver Options

linearSolverTolerance: 1.0e-02
petscSolverName: GMRES
hypreSolverName: AMG

For example, override the momentum solver and its tolerance:

Overriding the Global Linear Solver Options for the Momentum Equation

momentumEquationOptions: <linearSolver=PETSC, relaxationFactor=0.5, maxIterations=50,
                        linearSolverTolerance=1.0e-03, petscSolverName=CG>

Facts with the hypre prefix are global. Tolerances and iteration limits can be set per equation. For LSGS, PETSC, and HYPRE, maxIterations caps the number of linear iterations, and the solver can stop earlier when it meets its tolerance. SGS and FSGS always perform the specified number of sweeps.

Cell-wise field diagnostics are available for inspecting how much each linear solve reduces its equation residual. These variables use the naming convention <governingEquation>ResidualRatioLS and are described in Linear Solver Residual Ratio.

Available Linear Solvers
Solver	Description	Solver Names Supported	Solver Tolerance Used
SGS	Gauss-Seidel	N/A	No
FSGS	Cache-Optimized Gauss-Seidel	N/A	No
LSGS	Line Gauss-Seidel	N/A	Yes
PETSC	PETSc Library	GMRES, CG, BICG, CGS, BCGS	Yes
HYPRE	HYPRE Library	GMRES, AMG	Yes

HYPRE convergence and performance controls

hypreSolverName: GMRES uses AMG as a preconditioner; AMG solves directly with multigrid. These facts control the HYPRE equations in the case:

HYPRE controls
Fact	Default	Effect
`hypreGMRESRestart`	`5`	Positive integer: number of search vectors retained before GMRES restarts its search. Used only with `hypreSolverName: GMRES`. Larger values use more memory and orthogonalization work, but can improve convergence.
`hypreStrongThreshold`	`0.5`	Controls which matrix connections AMG treats as strong, affecting the multigrid hierarchy and cost. Applies to direct AMG and GMRES preconditioning.
`hypreSolverOutput`	`off`	Set to `on` to write linear iteration counts and final relative residuals to `debug/debug` for serial runs or `debug/debug.RANK` for MPI runs.

For GMRES solves that stagnate or repeatedly reach the iteration cap, try a restart length of 30. This is the linear search-space size, not a checkpoint restart or the total iteration limit. For example:

Pressure correction with AMG-preconditioned GMRES

pressureCorrectionEquationOptions: <linearSolver=HYPRE, relaxationFactor=0.6,
                                    maxIterations=100, linearSolverTolerance=1.0e-5>
hypreSolverName: GMRES
hypreGMRESRestart: 30
hypreStrongThreshold: 0.5
hypreSolverOutput: on

The selected GMRES restart length is recorded as HYPRE CONFIG in the debug files. Compare the HYPRE INFO residual with the equation’s linear tolerance: reaching maxIterations above that tolerance is a linear convergence miss. Check the outer nonlinear convergence separately.

Change one control at a time and compare accepted timesteps at the same mesh, rank count, and tolerances. A larger strong threshold is not always faster or more robust. The hypreCoarsenType, hypreInterpType, hypreRelaxType, hypreNumSweeps, hypreMaxLevels, and hypreMaxRowSum controls apply to direct AMG only; they do not configure the GMRES preconditioner.