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 system | Starting point | Required check |
|---|---|---|
| Symmetric/Hermitian positive definite | CG | Constraints remove the kernel; preconditioning is compatible |
| Nonsymmetric | GMRES or another suitable Krylov method | Convergence and preconditioner quality |
| Nonsingular sparse, modest factorization cost | SparseLU | Factorization status, residual, and memory use |
| Mixed saddle-point system | Small direct solve or a block-preconditioned method | Stable spaces and a valid gauge/nullspace treatment |
| Nonlinear residual | Newton-type method with an inner linear solver | Consistent 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 , Newton's method solves
The nonlinear formulation supplies the state , residual and consistent tangent . The Newton solver computes an increment and applies the damping .
NewtonSolver wraps an associated linear solver and updates the supplied state. Its residual stopping criteria are or . 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
| Observation | Checks before changing algorithms |
|---|---|
| CG fails or stagnates | Symmetry, definiteness, unresolved modes, scaling, and preconditioner |
| Sparse factorization fails | Gauge, boundary constraints, conditioning, and factorization diagnostic |
| Factorization exhausts memory | Fill-in, ordering, memory measurements, and a suitable iterative/block method |
| Iterative solve reaches its limit | True residual, scaling, preconditioner, restart dimension, and tolerance |
| Small residual but an inaccurate field | Formulation, loads, mesh, quadrature, boundary data, and conditioning |
| Nonlinear solve fails | State 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.