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.
`hypreCoarseRelaxType`	`-1`	Coarsest-grid method for both AMG and GMRES preconditioning: `3` is forward hybrid Gauss–Seidel, `6` is symmetric hybrid Gauss–Seidel, and `9` is direct Gaussian elimination. `-1` preserves the solver default: follow `hypreRelaxType` for AMG, or use `9` for GMRES.
`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.

The following controls configure standalone AMG only. GMRES’s AMG preconditioner retains its own hierarchy and smoothing settings.

Standalone AMG hierarchy and smoothing controls
Fact	Default	Effect
`hypreCoarsenType`	`10`	Coarsening algorithm: `10` selects HMIS and `6` selects Falgout.
`hypreInterpType`	`6`	Interpolation algorithm used between multigrid levels.
`hypreRelaxType`	`3`	Down/up-cycle smoother: `3` selects forward hybrid Gauss–Seidel; `6` selects symmetric hybrid Gauss–Seidel. Also sets the coarse method when `hypreCoarseRelaxType` is `-1`. Select direct coarse solution through `hypreCoarseRelaxType: 9`.
`hypreNumSweeps`	`2`	Smoothing sweeps per down/up cycle. The coarsest level uses one sweep or one direct solve.
`hypreMaxLevels`	`16`	Maximum multigrid levels. Too few levels can prevent the hierarchy from reaching a small enough coarse grid for a direct solve.
`hypreMaxRowSum`	`0.9`	Row-sum criterion for identifying diagonally dominant rows when building the strength-of-connection graph.

For AMG that reduces the residual initially but then converges very slowly, try a direct coarse solve while retaining the same smoother and hierarchy:

Pressure correction with a direct AMG coarse solve

pressureCorrectionEquationOptions: <linearSolver=HYPRE, relaxationFactor=0.6,
                                    maxIterations=500, linearSolverTolerance=1.0e-3>
hypreSolverName: AMG
hypreRelaxType: 3
hypreCoarseRelaxType: 9
hypreSolverOutput: on

HYPRE can fall back to smoothing if no coarsening occurs or the coarse grid remains too large for its direct solver.

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 coarse method and GMRES restart length are 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.