# 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 on ksp


## 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_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 macros such as `KSP_CONVERGED_RTOL`, which are defined in petscksp.h.

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
 [](chapter_ksp), `KSP`, `KSPSetConvergenceTest()`, `KSPSetTolerances()`, `KSPConvergedSkip()`, `KSPConvergedReason`, `KSPGetConvergedReason()`,
`KSPConvergedDefaultSetUIRNorm()`, `KSPConvergedDefaultSetUMIRNorm()`, `KSPConvergedDefaultSetConvergedMaxits()`, `KSPConvergedDefaultCreate()`, `KSPConvergedDefaultDestroy()`

## Level
advanced

## Location
<A HREF="PETSC_DOC_OUT_ROOT_PLACEHOLDER/src/ksp/ksp/interface/iterativ.c.html#KSPConvergedDefault">src/ksp/ksp/interface/iterativ.c</A>


---
[Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/src/ksp/ksp/interface/iterativ.c)


[Index of all KSP routines](index.md)  
[Table of Contents for all manual pages](/docs/manualpages/index.md)  
[Index of all manual pages](/docs/manualpages/singleindex.md)  
