Linear Solver and CPU/GPU Options
Each fully coupled implicit nonlinear step requires a sparse block linear solve of the form \(A\Delta q=b\). The linear-solver panel controls how accurately and efficiently that system is solved. A typical relative stopping test is \(\|r_k\|/\|r_0\|\le r_{tol}\).
Theory reference. Each option entry includes a link to the corresponding equation, physical model, closure, or numerical method in the Theory Manual. Defaults, availability, simulation effects, and practical guidance are documented directly with the GUI option.
Linear settings normally affect convergence cost, not the intended converged physical solution. However, a linear tolerance or iteration cap that is too loose can leave enough algebraic error to slow or distort nonlinear convergence.
Solver family and stopping criteria
Choose the lightest solver that converges reliably for the active physics and mesh.
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| Preconditioned Krylov Subspace (PCKSS)Default: Default solver family | Uses a Krylov iterative method with a local block preconditioner. | Stability / convergenceCost Usually lowest setup/memory cost and fast on well-conditioned systems; can become difficult for stiff/highly coupled cases. | Good first choice for many cases. | Sparse linear solver |
| Aggregation Algebraic Multigrid (AAMG) | Uses algebraic coarse levels and smoothing directly as the linear solver. | Stability / convergenceCost More setup/memory, but stronger long-range error reduction and often more robust for difficult systems. | Use when a single-level Krylov method stalls or needs many iterations. | Sparse linear solver |
| AAMG Preconditioned Krylov Subspace (AAMGKSS) | Uses algebraic multigrid as a preconditioner inside a flexible Krylov outer method. | Stability / convergenceCost Combines robust multilevel preconditioning with Krylov acceleration; typically highest setup/memory but strong for complex systems. | Use for the most difficult coupled linear systems. | Sparse linear solver |
| ToleranceDefault: 1e-6 | Relative linear convergence tolerance \(r_{tol}\). | Stability / convergenceCostAccuracy Smaller tolerance solves each Newton/pseudo-time linear system more accurately but increases iterations. | Start near the default; tighten if nonlinear convergence stalls because linear solves terminate too early. | Sparse linear solver |
| Maximum IterationsDefault: 30 | Maximum Krylov/linear iterations per solve. | Stability / convergenceCost Caps cost; if reached repeatedly, the preconditioner/solver is insufficient or the nonlinear step is too aggressive. | Do not simply raise indefinitely; inspect solver choice, CFL and conditioning. | Sparse linear solver |
| Apply | Commits the displayed linear tolerance/solver controls. | Initialization Changes subsequent linear solves. | Apply after editing before continuing the solve. | Sparse linear solver |
CPU/GPU execution
Device selection changes where linear algebra runs, not the governing equations.
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| Use GPU/CPU matrices and vectorsDefault: Off unless selected | Enables the device-capable sparse-vector/matrix path. CMPS supports CPU execution through Intel MKL and NVIDIA CUDA for GPU acceleration. | Cost Can shift sparse linear algebra to an accelerator-capable execution path; speedup depends on problem size, memory transfer and solver/preconditioner support. | Use NVIDIA CUDA on sufficiently large cases and supported hardware; compare end-to-end time, not kernel time alone. | GPU acceleration |
| Execution mode: NVIDIA CUDA | Selects NVIDIA CUDA when GPU device execution is enabled. | Cost Runs supported linear algebra on NVIDIA GPU resources. | Use when a compatible NVIDIA GPU is present and the case is large enough to benefit. | GPU acceleration |
| Execution mode: compatibility/experimental entries | The GUI may display additional execution mode choices for compatibility or development environments. | Cost Availability/performance depends on the installed CMPS build and platform. | For supported production use, prefer the documented CPU or NVIDIA CUDA path. | GPU acceleration |
| Linear precisionDefault: Double precision | Requests the scalar precision used by the device-capable linear-solver path. Double precision is the stable default; a request that is not supported by the installed linear-algebra package falls back to its available precision. | Stability / convergenceAccuracyCost Lower precision reduces memory/bandwidth cost but can reduce attainable residual accuracy and robustness; double precision costs more memory/bandwidth. | Keep Double for stiff or accuracy-sensitive solves. Treat lower precision as a performance option that must be qualified against nonlinear convergence and final engineering quantities. | GPU acceleration |
| Print device object typesDefault: On | Reports which device/host matrix/vector representations are actually active. | Reporting / displayCost No solution effect apart from small logging overhead. | Use to verify that a requested GPU path is genuinely active. | GPU acceleration |
Preconditioned Krylov options
These are the local preconditioner and Krylov choices for the single-level family.
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| Block ILUDefault: Default | Uses block incomplete LU factorization as the preconditioner. | Stability / convergenceCost Stronger than simple block diagonal for many coupled systems; factorization setup/storage costs more but normally reduces Krylov iterations. | General default preconditioner. | Incomplete-LU preconditioning |
| PCKSS ILU Fill LevelDefault: 1 | Sets the incomplete-factorization fill level. Level 0 retains the original sparsity pattern; higher levels permit additional fill couplings. | Stability / convergenceCost More fill normally strengthens the preconditioner and reduces Krylov iterations, but increases setup time and memory. | Increase only when total time-to-solution improves and memory remains acceptable. | Incomplete-LU preconditioning |
| Block Jacobi | Uses independent block-diagonal/local subdomain solves without ILU coupling across local graph structure. | Stability / convergenceCost Cheap and parallel-friendly but weaker; may require more Krylov iterations. | Use for very parallel runs or when ILU setup/memory dominates and conditioning is mild. | Local/Krylov preconditioning |
| GMRESDefault: Default Krylov method | Minimizes residual over an expanding Krylov subspace, with restart behavior set by the solver environment. | Stability / convergenceCost Robust for nonsymmetric coupled systems but stores basis vectors and can use more memory. | General default for the coupled CMPS linear system. | GMRES |
| BiCGStab | Uses a short-recurrence stabilized bi-conjugate-gradient method. | Stability / convergenceCost Lower memory than GMRES and can be faster, but residual histories can be less smooth/robust. | Try when memory matters or GMRES is expensive; monitor stagnation/irregular residuals. | Local/Krylov preconditioning |
| TFQMR | Uses a transpose-free quasi-minimal-residual short-recurrence method. | Stability / convergenceCost Alternative memory-efficient nonsymmetric solver with problem-dependent robustness. | Use as a solver-sensitivity alternative when GMRES/BiCGStab are unsatisfactory. | Local/Krylov preconditioning |
Aggregation algebraic multigrid options
These controls determine multilevel hierarchy relaxation and cycle strength.
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| AAMG Relaxation: ILUDefault: Default | Uses incomplete factorization as the AAMG level relaxation method. | Stability / convergenceCost Strong local smoothing but more setup/memory than simpler relaxation. | General default for the stand-alone algebraic multigrid family. | AMG / AMG-preconditioned Krylov |
| AAMG Relaxation: SGSDefault: Alternative | Uses symmetric Gauss-Seidel-style level relaxation. | Stability / convergenceCost Lower factorization setup but more sequential data dependence; convergence is problem dependent. | Use when ILU setup/storage is undesirable and SGS smooths the matrix effectively. | AMG / AMG-preconditioned Krylov |
| AAMG Relaxation: ASMDefault: Alternative | Uses an additive-Schwarz/subdomain relaxation. | Stability / convergenceCost Can strengthen local partitioned solves at additional subdomain/overlap work. | Use for difficult partitioned systems when simpler level relaxation is weak. | AMG / AMG-preconditioned Krylov |
| AAMG ILU Fill LevelDefault: 0 | Fill level used when AAMG relaxation is ILU. | Stability / convergenceCost Higher fill strengthens each level relaxation but increases setup time and memory. | Keep the default first; increase only if fewer cycles justify the extra cost. | AMG / AMG-preconditioned Krylov |
| AAMG Smoothing: NoneDefault: Default | Uses no additional Krylov smoothing around the selected AAMG relaxation. | Cost Lowest per-level work. | Baseline configuration; a Krylov smoother can be added if the basic relaxation is insufficient. | AMG / AMG-preconditioned Krylov |
| AAMG Smoothing: GMRESDefault: Alternative | Uses GMRES as the optional extra AAMG smoothing method. | Stability / convergenceCost Adds work/memory per level and can improve damping of difficult error modes. | Use only when measured cycle convergence improves enough to offset the extra work. | AMG / AMG-preconditioned Krylov |
| AAMG Smoothing: BiCGStabDefault: Alternative | Uses BiCGStab as the optional extra AAMG smoothing method. | Stability / convergenceCost Adds short-recurrence Krylov smoothing with lower basis memory than GMRES but more problem-dependent residual behavior. | Use as an alternative when GMRES memory/cost is undesirable. | AMG / AMG-preconditioned Krylov |
| AAMG Smoothing: TFQMRDefault: Alternative | Uses TFQMR as the optional extra AAMG smoothing method. | Stability / convergenceCost Adds a transpose-free short-recurrence smoother with problem-dependent performance. | Use only after comparing cycle efficiency. | AMG / AMG-preconditioned Krylov |
| AAMG Cycle: VDefault: Alternative | One recursive coarse visit per level. | Stability / convergenceCost Lowest multilevel work per cycle, but may be weaker for long-wavelength error. | Use when it provides sufficient convergence at lower cost. | AMG / AMG-preconditioned Krylov |
| AAMG Cycle: FDefault: Default | Uses an F-cycle schedule with stronger coarse-level work than a simple V-cycle. | Stability / convergenceCost Usually improves coarse-error reduction at extra work per cycle. | This is the configured default; keep it unless a V/W/FW comparison improves total solve time. | AMG / AMG-preconditioned Krylov |
| AAMG Cycle: WDefault: Alternative | Performs repeated coarse visits at each level. | Stability / convergenceCost Strong coarse correction but the highest standard cycle work. | Use when low-frequency error remains after cheaper cycles. | AMG / AMG-preconditioned Krylov |
| AAMG Cycle: FWDefault: Alternative | Uses the combined F/W cycle schedule exposed by the GUI. | Stability / convergenceCost Provides very strong coarse work at high per-cycle cost. | Reserve for matrices that need stronger multilevel correction. | AMG / AMG-preconditioned Krylov |
| AAMG Coarse LevelsDefault: 5 | Requested/allowed number of algebraic multigrid levels. | Stability / convergenceCost More levels represent longer-range error but increase hierarchy setup/storage and can create a weak very-coarse system. | Use enough levels for the matrix size; avoid unnecessary depth on small cases. | AMG / AMG-preconditioned Krylov |
| AAMG ThresholdDefault: 0 | Strength/filtering threshold used when building the algebraic hierarchy. | Stability / convergenceCost Changes which matrix couplings influence coarsening and therefore hierarchy density, memory and convergence. | Keep 0 initially; tune only with measured iterations and memory. | AMG / AMG-preconditioned Krylov |
| Apply AAMG Threshold | Commits the displayed AAMG threshold value. | Initialization Changes the threshold used by subsequent AAMG setup/solves. | Use after editing the threshold. | AMG / AMG-preconditioned Krylov |
| AAMG Number of SmoothingDefault: 2 | Number of smoothing applications per AAMG level/cycle. | Stability / convergenceCost More smoothing can reduce high-frequency error more strongly but increases cycle cost. | Use the smallest count giving robust cycle convergence. | AMG / AMG-preconditioned Krylov |
Multigrid-preconditioned Krylov options
The multilevel solver can also be used as a variable preconditioner for an outer flexible Krylov method.
| GUI option | Meaning / formulation | Effect on the simulation | Practical guidance | Theory reference |
|---|---|---|---|---|
| AAMGKSS Outer Solver: FGMRESDefault: Default | Flexible GMRES permits the multigrid preconditioner to vary between outer iterations. | Stability / convergenceCost Robust with variable multigrid preconditioning but stores a Krylov basis and can use more memory. | General default for AAMGKSS. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Outer Solver: FBiCGStabDefault: Alternative | Flexible short-recurrence BiCGStab alternative around the multigrid preconditioner. | Stability / convergenceCost Uses less Krylov-basis memory but residual behavior can be less smooth and more problem dependent than FGMRES. | Try when memory is constrained and convergence remains acceptable. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Relaxation: ILUDefault: Default | Uses incomplete factorization for relaxation inside the AAMG preconditioner. | Stability / convergenceCost Strong default local smoothing with setup/memory cost. | Robust baseline for difficult coupled systems. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Relaxation: SGSDefault: Alternative | Uses symmetric Gauss-Seidel relaxation inside the AAMG preconditioner. | Stability / convergenceCost Lower factorization setup but more sequential dependency and problem-dependent strength. | Use when ILU is too expensive and SGS remains effective. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Relaxation: ASMDefault: Alternative | Uses additive-Schwarz/subdomain relaxation inside the AAMG preconditioner. | Stability / convergenceCost Can strengthen partition-local solves at extra local work. | Use when simpler relaxation is insufficient on distributed cases. | AMG / AMG-preconditioned Krylov |
| AAMGKSS ILU Fill LevelDefault: 0 | Fill level used when the inner AAMG relaxation is ILU. | Stability / convergenceCost Higher fill strengthens the preconditioner but increases setup time and memory on every relevant level. | Increase only when the reduction in outer iterations improves total run time. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Smoothing: NoneDefault: Default | Uses no additional Krylov smoothing inside the AAMG preconditioner. | Cost Lowest preconditioner application cost. | Default starting point. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Smoothing: GMRESDefault: Alternative | Uses GMRES for optional extra preconditioner-level smoothing. | Stability / convergenceCost Stronger but more expensive preconditioner application, with extra basis memory. | Enable only if it materially reduces outer work. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Smoothing: BiCGStabDefault: Alternative | Uses BiCGStab for optional extra preconditioner-level smoothing. | Stability / convergenceCost Adds short-recurrence smoothing with lower basis memory than GMRES. | Compare total time and robustness before production use. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Smoothing: TFQMRDefault: Alternative | Uses TFQMR for optional extra preconditioner-level smoothing. | Stability / convergenceCost Alternative short-recurrence smoothing with problem-dependent performance. | Use as a measured solver-sensitivity option. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Cycle: VDefault: Alternative | Uses a V-cycle for each multigrid preconditioner application. | Stability / convergenceCost Cheapest cycle but can be weaker for low-frequency error. | Use when outer convergence remains strong. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Cycle: FDefault: Default | Uses an F-cycle for each multigrid preconditioner application. | Stability / convergenceCost Stronger coarse work than V at higher application cost. | Configured default for the AAMGKSS preconditioner. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Cycle: WDefault: Alternative | Uses a W-cycle for each multigrid preconditioner application. | Stability / convergenceCost Strong coarse correction with high per-application cost. | Use only when cheaper cycles give too many outer iterations. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Cycle: FWDefault: Alternative | Uses the combined FW cycle for each preconditioner application. | Stability / convergenceCost Very strong and expensive multilevel correction. | Reserve for particularly difficult matrices. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Coarse LevelsDefault: 5 | Requested/allowed algebraic levels in the multigrid preconditioner. | Stability / convergenceCost More levels can strengthen long-range coupling but increase preconditioner setup and memory. | Use enough depth to reduce outer iterations without over-building the hierarchy. | AMG / AMG-preconditioned Krylov |
| AAMGKSS ThresholdDefault: 0 | Strength/filtering threshold used to form the AAMG preconditioner hierarchy. | Stability / convergenceCost Changes hierarchy density/quality and therefore both memory and outer convergence. | Keep the default first and tune only using total time/memory measurements. | AMG / AMG-preconditioned Krylov |
| Apply AAMGKSS Threshold | Commits the displayed AAMGKSS threshold. | Initialization Changes subsequent preconditioner hierarchy setup. | Use after editing the threshold. | AMG / AMG-preconditioned Krylov |
| AAMGKSS Number of SmoothingDefault: 2 | Number of smoothing applications used in each AAMG preconditioner cycle. | Stability / convergenceCost More smoothing strengthens each preconditioner application but costs more. | Use the smallest value that gives robust outer convergence. | AMG / AMG-preconditioned Krylov |
Recommended tuning order
- Keep the default solver family, tolerance and preconditioner and first tune nonlinear CFL/relaxation.
- If the linear iteration cap is reached repeatedly, try a stronger preconditioner or multigrid family before making the tolerance looser.
- For GPU use, verify device execution and compare memory use and total wall-clock time.
- Re-check final residuals and integral quantities after any large linear-solver change.