The default convergence test, KSPDefaultConverged(), is based on the l2-norm of the residual. Convergence (or divergence) is decided by three quantities: the relative decrease of the residual norm, rtol, the absolute size of the residual norm, atol, and the relative increase in the residual, dtol. Convergence is detected at iteration k if
where rk = b - A xk. Divergence is detected if
These parameters, as well as the maximum number of allowable iterations,
can be set with the routine
ierr = KSPSetTolerances(KSP ksp,double rtol,double atol,double dtol,int maxits);The user can retain the default value of any of these parameters by specifying PETSC_DEFAULT as the corresponding tolerance; the defaults are rtol=10-5, atol=10-50, dtol=105, and maxits=105. These parameters can also be set from the options database with the commands -ksp_rtol <rtol>, -ksp_atol <atol>, -ksp_divtol <dtol>, and -ksp_max_it <its>.
In addition to providing an interface to a simple convergence test,
KSP allows the application programmer the flexibility to provide
customized convergence-testing routines.
The user can specify a customized
routine with the command
ierr = KSPSetConvergenceTest(KSP ksp,int (*test)(KSP ksp,int it,double rnorm,void *ctx), void *ctx);The final routine argument, ctx, is an optional context for private data for the user-defined convergence routine, test. Other test routine arguments are the iteration number, it, and the residual's l2 norm, rnorm. The routine for detecting convergence, test, should return the integer 1 for convergence, 0 for no convergence, and minus 1 (-1) on error or failure to converge.