7.3.1. Convergence Tests

Up: Contents Next: Convergence Monitoring Previous: General Options

Convergence of the nonlinear solvers can be detected in a variety of ways; the user can even specify a customized test, as discussed below. The default convergence routines for the various nonlinear solvers within SNES are listed in Table 12 ; see the corresponding manual pages for detailed descriptions. Each of these convergence tests involves several parameters, which are set by default to values that should be reasonable for a wide range of problems. The user can customize the parameters to the problem at hand by using some of the following routines and options.

One method of convergence testing is to declare convergence when the norm of the change in the solution between successive iterations is less than some tolerance, stol. Convergence can also be determined based on the norm of the function (or gradient for a minimization problem). Such a test can use either the absolute size of the norm, atol, or its relative decrease, rtol, from an initial guess. The following routine sets these parameters, which are used in many of the default SNES convergence tests:

   ierr = SNESSetTolerances(SNES snes,double rtol,double atol,double stol, 
          int its,int fcts); 
This routine also sets the maximum numbers of allowable nonlinear iterations, its, and function evaluations, fcts. The corresponding options database commands for setting these parameters are -snes_atol <atol>, -snes_rtol <rtol>, -snes_stol <stol>, -snes_max_it <its>, and -snes_max_funcs <fcts>. A related routine is SNESGetTolerances().

Convergence tests for trust regions methods often use an additional parameter that indicates the minimium allowable trust region radius. The user can set this parameter with the option -snes_trtol <trtol> or with the routine

   ierr = SNESSetTrustRegionTolerance(SNES snes,double trtol); 
An additional parameter is sometimes used for unconstrained minimization problems, namely the minimum function tolerance, ftol, which can be set with the option -snes_fmin <ftol> or with the routine
   ierr = SNESSetMinimizationFunctionTolerance(SNES snes,double ftol); 
Users can set their own customized convergence tests in SNES by using the command
   ierr = SNESSetConvergenceTest(SNES snes,int (*test)(SNES snes,double xnorm, 
                                 double gnorm,double f,void *cctx),void *cctx); 
The final argument of the convergence test routine, cctx, denotes an optional user-defined context for private data. When solving systems of nonlinear equations, the arguments xnorm, gnorm, and f are the current iterate norm, current step norm, and function norm, respectively. Likewise, when solving unconstrained minimization problems, the arguments xnorm, gnorm, and f are the current iterate norm, current gradient norm, and the function value.


Up: Contents Next: Convergence Monitoring Previous: General Options