Skip to main content
`Ctrl`+`K`

# KSPConvergedDefault

Default code to determine convergence of the linear iterative solvers

## Synopsis

    #include "petscksp.h"
    PetscErrorCode KSPConvergedDefault(KSP ksp, PetscInt n, PetscReal rnorm, KSPConvergedReason *reason, void *ctx)

Collective

## Input Parameters

- ksp - iterative context

- n - iteration number

- rnorm - residual norm (may be estimated, depending on the method may be the preconditioned residual norm)

- ctx - convergence context which must be created by `KSPConvergedDefaultCreate()`

## Output Parameter

- reason - the convergence reason; it is positive if the iteration has converged, negative if the iteration has diverged, and `KSP_CONVERGED_ITERATING` otherwise

## Options Database Keys

- -ksp_max_it - maximum number of linear iterations

- -ksp_min_it - minimum number of linear iterations, defaults to 0

- -ksp_rtol rtol - relative tolerance used in default determination of convergence, i.e. if residual norm decreases by this factor than convergence is declared

- -ksp_atol abstol - absolute tolerance used in default convergence test, i.e. if residual norm is less than this then convergence is declared

- -ksp_divtol tol - if residual norm increases by this factor than divergence is declared

- -ksp_converged_use_initial_residual_norm - see `KSPConvergedDefaultSetUIRNorm()`

- -ksp_converged_use_min_initial_residual_norm - see `KSPConvergedDefaultSetUMIRNorm()`

- -ksp_converged_maxits - see `KSPConvergedDefaultSetConvergedMaxits()`

## Notes

`KSPConvergedDefault()` reaches convergence when rnorm < MAX (rtol * rnorm_0, abstol); Divergence is detected if rnorm > dtol * rnorm_0, or when failures are detected throughout the iteration. By default, reaching the maximum number of iterations is considered divergence (i.e. KSP_DIVERGED_ITS). In order to have PETSc declaring convergence in such a case (i.e. `KSP_CONVERGED_ITS`), users can use `KSPConvergedDefaultSetConvergedMaxits()`

where:

- `rtol` - relative tolerance,

- `abstol` - absolute tolerance.

- `dtol` - divergence tolerance,

- `rnorm_0` - the two norm of the right-hand side (or the preconditioned norm, depending on what was set with `KSPSetNormType()`. When initial guess is non-zero you can call `KSPConvergedDefaultSetUIRNorm()` to use the norm of (b - A*(initial guess)) as the starting point for relative norm convergence testing, that is as `rnorm_0`. Call `KSPConvergedDefaultSetUMIRNorm()` to use the minimum of the norm of (b - A*(initial guess)) and the norm of b as the starting point.

Use `KSPSetTolerances()` to alter the defaults for `rtol`, `abstol`, `dtol`.

Use `KSPSetNormType()` (or `-ksp_norm_type <none,preconditioned,unpreconditioned,natural>`) to change the norm used for computing rnorm

The precise values of reason are available in `KSPConvergedReason`

This routine is used by `KSP` by default so the user generally never needs call it directly.

Use `KSPSetConvergenceTest()` to provide your own test instead of using this one.

Call `KSPSetConvergenceTest()` with the `ctx`, as created above and the destruction function `KSPConvergedDefaultDestroy()`

## See Also

KSP: Linear System Solvers, `KSP`, `KSPSetConvergenceTest()`, `KSPSetTolerances()`, `KSPConvergedSkip()`, `KSPConvergedReason`, `KSPGetConvergedReason()`, `KSPSetMinimumIterations()`, `KSPConvergedDefaultSetUIRNorm()`, `KSPConvergedDefaultSetUMIRNorm()`, `KSPConvergedDefaultSetConvergedMaxits()`, `KSPConvergedDefaultCreate()`, `KSPConvergedDefaultDestroy()`

## Level

advanced

## Location

src/ksp/ksp/interface/iterativ.c

## Examples

src/ksp/ksp/tutorials/ex1f.F90

Index of all KSP routines
Table of Contents for all manual pages
Index of all manual pages