General concepts » Solvers

Choose a solver from the assembled system, then verify its result.

A solver acts on the algebraic system produced by the weak formulation and its constraints. Solver selection depends on matrix properties, including nullspaces, boundary constraints, coupling and complex coefficients.

Solver selection

Assembled systemStarting pointRequired check
Symmetric/Hermitian positive definiteCGConstraints remove the kernel; preconditioning is compatible
NonsymmetricGMRES or another suitable Krylov methodConvergence and preconditioner quality
Nonsingular sparse, modest factorization costSparseLUFactorization status, residual, and memory use
Mixed saddle-point systemSmall direct solve or a block-preconditioned methodStable spaces and a valid gauge/nullspace treatment
Nonlinear residualNewton-type method with an inner linear solverConsistent tangent, state updates, and nonlinear convergence

The Dirichlet Poisson and clamped elasticity examples use CG. The Helmholtz matrix is indefinite, while Stokes has coupled velocity–pressure blocks. These systems require solvers compatible with their indefinite or saddle-point structure.

A periodic or pure-Neumann Poisson problem requires a compatible load and a normalization that removes its constant nullspace before a nonsingular algebraic solve.

Iterative convergence

In the unit-square Poisson program, poisson is a defined Problem object.

  CG solver(poisson);
  solver.solve();
  if (!solver.success())
    return EXIT_FAILURE;

The tolerance specifies the backend's algebraic stopping criterion. setMaxIterations(...) bounds the iteration count. Check the termination status before exporting the field, and assess discretization error through mesh refinement.

Algebraic diagnostics

Native CG and GMRES expose success(), getIterationNumber(), and getError(). The error value is a backend convergence estimate. An explicit residual supplies a separate algebraic check.

const auto& system = poisson.getLinearSystem();
const Real relativeResidual =
  (system.getOperator() * system.getSolution() - system.getVector()).norm()
  / system.getVector().norm();

This relative definition assumes a nonzero load vector. For a zero load, report the absolute residual or state another normalization explicitly. Conditioning relates the algebraic residual to solution error. Mesh refinement is used to assess discretization convergence.

GMRES configuration

For a defined native sparse problem, GMRES can be configured as follows.

Solver::GMRES solver(problem);
solver.setTolerance(1e-10).setMaxIterations(1000).setRestart(40).solve();
if (!solver.success())
  return EXIT_FAILURE;

Include <cstdlib> when using EXIT_FAILURE. The restart dimension bounds the retained Krylov basis; a smaller value reduces basis storage but can slow or prevent convergence. The native default preconditioner is diagonal. A compatible Eigen preconditioner can be supplied as a constructor argument; the public solver type remains parameterized by the linear-system type.

For incompressible flow, the preconditioner must account for the coupled velocity and pressure blocks and their gauge or nullspace treatment.

Direct-solver cost

Sparse LU factors a matrix and solves using those factors. It is useful for small verification problems and the tutorial-scale Helmholtz and Stokes solves. A nonsingular matrix is a necessary mathematical condition; numerical stability and successful factorization must still be checked.

Factorization creates fill-in. Memory and time depend on ordering, graph structure, dimension, polynomial degree and conditioning. Factorization cost should be measured for the chosen discretization. A three-dimensional mixed system can exhaust memory well before a similarly sized two-dimensional scalar system.

SimplicialLLT supplies a sparse Cholesky alternative for suitable positive definite systems. Other direct wrappers and optional SuiteSparse integrations are listed in the solver reference. Available dependencies and backend specializations must be checked for the configured build.

Object lifetimes

A configured solver is useful when its status must be checked or its settings adjusted. A temporary Solver::CG(problem).solve() also solves a problem, but discards the solver object and its diagnostics immediately.

Reassigning a problem body marks its assembly stale. If existing coefficient data change, explicitly reassemble or rebuild as required by the numerical contracts. Factorization reuse follows the contract of the selected backend and API.

Changing the mesh or finite element space changes the algebraic layout. Construct a new problem, linear system and associated solvers for the new layout.

Nonlinear residuals

For a residual $F(x)=0$ , Newton's method solves

\[ J(x^k)\delta x^k=-F(x^k),\qquad x^{k+1}=x^k+\alpha\delta x^k. \]

The nonlinear formulation supplies the state $x^k$ , residual and consistent tangent $J(x^k)$ . The Newton solver computes an increment and applies the damping $\alpha$ .

NewtonSolver wraps an associated linear solver and updates the supplied state. Its residual stopping criteria are $\|F(x^k)\|\le\mathrm{atol}$ or $\|F(x^k)\|\le\mathrm{rtol}\|F(x^0)\|$ . An optional step tolerance is disabled by default. After solving, converged() and getReport() expose the termination result; a converged inner linear solve alone is insufficient.

The solid mechanics guide develops the current internal virtual-work residual and consistent tangent. The native cavity tutorial uses one semi-implicit Oseen solve per time step.

PETSc configuration

KSP configures PETSc linear systems, and SNES supplies nonlinear solves using an associated KSP. PETSc-backed trial and test functions select PETSc algebra when that backend is enabled in the build.

For a PETSc program that initializes PETSc, processes its solver options, and defines the associated problem, command-line options can select the method and diagnostics.

./program -ksp_type gmres -pc_type ilu -ksp_rtol 1e-8 -ksp_monitor

These options configure GMRES with ILU for a compatible sequential matrix. MPI ownership, field splits, pressure nullspaces, and distributed preconditioner support require the PETSc guide. The reference pages specify the distinct native and PETSc convergence/status interfaces.

Solve diagnostics

ObservationChecks before changing algorithms
CG fails or stagnatesSymmetry, definiteness, unresolved modes, scaling, and preconditioner
Sparse factorization failsGauge, boundary constraints, conditioning, and factorization diagnostic
Factorization exhausts memoryFill-in, ordering, memory measurements, and a suitable iterative/block method
Iterative solve reaches its limitTrue residual, scaling, preconditioner, restart dimension, and tolerance
Small residual but an inaccurate fieldFormulation, loads, mesh, quadrature, boundary data, and conditioning
Nonlinear solve failsState synchronization, residual/tangent consistency, constraints, initial guess, and damping

Examples

The Poisson, Helmholtz, and Stokes tutorials include complete source and output. The variational guide explains assembly, while numerical contracts records the shared signs, quadrature, and lifetime rules.