1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML3.2 EN">
<HTML>
<HEAD> <link rel="canonical" href="http://www.mcs.anl.gov/petsc/petsc-current/docs/manualpages/SNES/SNESConvergedReason.html" />
<META NAME="GENERATOR" CONTENT="DOCTEXT">
<TITLE>SNESConvergedReason</TITLE>
</HEAD>
<BODY BGCOLOR="FFFFFF">
<div id="version" align=right><b>petsc-3.7.5 2017-01-01</b></div>
<div id="bugreport" align=right><a href="mailto:petsc-maint@mcs.anl.gov?subject=Typo or Error in Documentation &body=Please describe the typo or error in the documentation: petsc-3.7.5 v3.7.5 docs/manualpages/SNES/SNESConvergedReason.html "><small>Report Typos and Errors</small></a></div>
<A NAME="SNESConvergedReason"><H1>SNESConvergedReason</H1></A>
reason a <A HREF="../SNES/SNES.html#SNES">SNES</A> method was said to have converged or diverged
<H3><FONT COLOR="#CC3333">Synopsis</FONT></H3>
<PRE>
typedef enum {/* converged */
<A HREF="../SNES/SNES_CONVERGED_FNORM_ABS.html#SNES_CONVERGED_FNORM_ABS">SNES_CONVERGED_FNORM_ABS</A> = 2, /* ||F|| < atol */
<A HREF="../SNES/SNES_CONVERGED_FNORM_RELATIVE.html#SNES_CONVERGED_FNORM_RELATIVE">SNES_CONVERGED_FNORM_RELATIVE</A> = 3, /* ||F|| < rtol*||F_initial|| */
<A HREF="../SNES/SNES_CONVERGED_SNORM_RELATIVE.html#SNES_CONVERGED_SNORM_RELATIVE">SNES_CONVERGED_SNORM_RELATIVE</A> = 4, /* Newton computed step size small; || delta x || < stol || x ||*/
SNES_CONVERGED_ITS = 5, /* maximum iterations reached */
SNES_CONVERGED_TR_DELTA = 7,
/* diverged */
SNES_DIVERGED_FUNCTION_DOMAIN = -1, /* the new x location passed the function is not in the domain of F */
<A HREF="../SNES/SNES_DIVERGED_FUNCTION_COUNT.html#SNES_DIVERGED_FUNCTION_COUNT">SNES_DIVERGED_FUNCTION_COUNT</A> = -2,
SNES_DIVERGED_LINEAR_SOLVE = -3, /* the linear solve failed */
<A HREF="../SNES/SNES_DIVERGED_FNORM_NAN.html#SNES_DIVERGED_FNORM_NAN">SNES_DIVERGED_FNORM_NAN</A> = -4,
<A HREF="../SNES/SNES_DIVERGED_MAX_IT.html#SNES_DIVERGED_MAX_IT">SNES_DIVERGED_MAX_IT</A> = -5,
<A HREF="../SNES/SNES_DIVERGED_LINE_SEARCH.html#SNES_DIVERGED_LINE_SEARCH">SNES_DIVERGED_LINE_SEARCH</A> = -6, /* the line search failed */
SNES_DIVERGED_INNER = -7, /* inner solve failed */
<A HREF="../SNES/SNES_DIVERGED_LOCAL_MIN.html#SNES_DIVERGED_LOCAL_MIN">SNES_DIVERGED_LOCAL_MIN</A> = -8, /* || J^T b || is small, implies converged to local minimum of F() */
SNES_CONVERGED_ITERATING = 0} <A HREF="../SNES/SNESConvergedReason.html#SNESConvergedReason">SNESConvergedReason</A>;
</PRE>
<P>
The two most common reasons for divergence are
<pre>
1) an incorrectly coded or computed Jacobian or
</pre>
<pre>
2) failure or lack of convergence in the linear system (in this case we recommend
</pre>
<pre>
testing with -pc_type lu to eliminate the linear solver as the cause of the problem).
</pre>
<P>
<H3><FONT COLOR="#CC3333">Diverged Reasons</FONT></H3>
<DT><B><A HREF="../SNES/SNES_DIVERGED_LOCAL_MIN.html#SNES_DIVERGED_LOCAL_MIN">SNES_DIVERGED_LOCAL_MIN</A> </B> -this can only occur when using the line-search variant of <A HREF="../SNES/SNES.html#SNES">SNES</A>.
The line search wants to minimize Q(alpha) = 1/2 || F(x + alpha s) ||^2_2 this occurs
at Q'(alpha) = s^T F'(x+alpha s)^T F(x+alpha s) = 0. If s is the Newton direction - F'(x)^(-1)F(x) then
you get Q'(alpha) = -F(x)^T F'(x)^(-1)^T F'(x+alpha s)F(x+alpha s); when alpha = 0
Q'(0) = - ||F(x)||^2_2 which is always NEGATIVE if F'(x) is invertible. This means the Newton
direction is a descent direction and the line search should succeed if alpha is small enough.
<br>
<P>
If F'(x) is NOT invertible AND F'(x)^T F(x) = 0 then Q'(0) = 0 and the Newton direction
is NOT a descent direction so the line search will fail. All one can do at this point
is change the initial guess and try again.
<P>
An alternative explanation: Newton's method can be regarded as replacing the function with
its linear approximation and minimizing the 2-norm of that. That is F(x+s) approx F(x) + F'(x)s
so we minimize || F(x) + F'(x) s ||^2_2; do this using Least Squares. If F'(x) is invertible then
s = - F'(x)^(-1)F(x) otherwise F'(x)^T F'(x) s = -F'(x)^T F(x). If F'(x)^T F(x) is NOT zero then there
exists a nontrival (that is F'(x)s != 0) solution to the equation and this direction is
s = - [F'(x)^T F'(x)]^(-1) F'(x)^T F(x) so Q'(0) = - F(x)^T F'(x) [F'(x)^T F'(x)]^(-T) F'(x)^T F(x)
= - (F'(x)^T F(x)) [F'(x)^T F'(x)]^(-T) (F'(x)^T F(x)). Since we are assuming (F'(x)^T F(x)) != 0
and F'(x)^T F'(x) has no negative eigenvalues Q'(0) < 0 so s is a descent direction and the line
search should succeed for small enough alpha.
<P>
Note that this RARELY happens in practice. Far more likely the linear system is not being solved
(well enough?) or the Jacobian is wrong.
<P>
<A HREF="../SNES/SNES_DIVERGED_MAX_IT.html#SNES_DIVERGED_MAX_IT">SNES_DIVERGED_MAX_IT</A> means that the solver reached the maximum number of iterations without satisfying any
convergence criteria. SNES_CONVERGED_ITS means that <A HREF="../SNES/SNESConvergedSkip.html#SNESConvergedSkip">SNESConvergedSkip</A>() was chosen as the convergence test;
thus the usual convergence criteria have not been checked and may or may not be satisfied.
<P>
Developer Notes: this must match petsc/finclude/petscsnes.h
<P>
The string versions of these are in <A HREF="../SNES/SNESConvergedReason.html#SNESConvergedReason">SNESConvergedReason</A>, if you change any value here you must
also adjust that array.
<P>
Each reason has its own manual page.
<P>
<H3><FONT COLOR="#CC3333">See Also</FONT></H3>
<A HREF="../SNES/SNESSolve.html#SNESSolve">SNESSolve</A>(), <A HREF="../SNES/SNESGetConvergedReason.html#SNESGetConvergedReason">SNESGetConvergedReason</A>(), <A HREF="../KSP/KSPConvergedReason.html#KSPConvergedReason">KSPConvergedReason</A>, <A HREF="../SNES/SNESSetConvergenceTest.html#SNESSetConvergenceTest">SNESSetConvergenceTest</A>()
<BR><P><B><P><B><FONT COLOR="#CC3333">Level:</FONT></B>beginner
<BR><FONT COLOR="#CC3333">Location:</FONT></B><A HREF="../../../src/snes/../../include/petscsnes.h.html#SNESConvergedReason">src/snes/../../include/petscsnes.h</A>
<BR><A HREF="./index.html">Index of all SNES routines</A>
<BR><A HREF="../../index.html">Table of Contents for all manual pages</A>
<BR><A HREF="../singleindex.html">Index of all manual pages</A>
<P><H3><FONT COLOR="#CC3333">Examples</FONT></H3>
<A HREF="../../../src/snes/examples/tutorials/ex30.c.html">src/snes/examples/tutorials/ex30.c.html</A><BR>
</BODY></HTML>
|
