Exit Flags and Exit Messages

Exit Flags

When an optimization solver completes its task, it sets an exit flag. An exit flag is an integer that is a code for the reason the solver halted its iterations. In general:

• Positive exit flags correspond to successful outcomes.

• Negative exit flags correspond to unsuccessful outcomes.

• The zero exit flag corresponds to the solver being halted by exceeding an iteration limit or limit on the number of function evaluations (see Iterations and Function Counts, and also see Tolerances and Stopping Criteria).

This table links to the exit flag description of each solver.

Exit Flags by Solver

coneprog exitflag	fgoalattain exitflag	fminbnd exitflag
fmincon exitflag	fminimax exitflag	fminsearch exitflag
fminunc exitflag	fseminf exitflag	fsolve exitflag
fzero exitflag	intlinprog exitflag	linprog exitflag
lsqcurvefit exitflag	lsqlin exitflag	lsqnonlin exitflag
lsqnonneg exitflag	quadprog exitflag

Note

Exit flags are not infallible guides to the quality of a solution. Many other factors, such as tolerance settings, can affect whether a solution is satisfactory to you. You are responsible for deciding whether a solver returns a satisfactory answer. Sometimes a negative exit flag does not correspond to a “bad” solution. Similarly, sometimes a positive exit flag does not correspond to a “good” solution.

You obtain an exit flag by calling a solver with the exitflag syntax. This syntax depends on the solver. For details, see the solver function reference pages. For example, for fsolve, the calling syntax to obtain an exit flag is

[x,fval,exitflag] = fsolve(...)

The following example uses this syntax. Suppose you want to solve the system of nonlinear equations

$$\begin{array}{c}2x_1-x_2=e^{-x_1}\\ -x_1+2x_2=e^{-x_2}.\end{array}$$

Write these equations as an anonymous function that gives a zero vector at a solution:

myfcn = @(x)[2*x(1) - x(2) - exp(-x(1));
      -x(1) + 2*x(2) - exp(-x(2))];

Call fsolve with the exitflag syntax at the initial point [-5 -5]:

[xfinal fval exitflag] = fsolve(myfcn,[-5 -5])

Equation solved.

fsolve completed because the vector of function values is near zero
as measured by the value of the function tolerance, and
the problem appears regular as measured by the gradient.

xfinal =
    0.5671    0.5671

fval =
  1.0e-06 *
   -0.4059
   -0.4059

exitflag =
     1

In the table for the fsolve exitflag, you find that an exit flag value 1 means “Function converged to a solution x.” In other words, fsolve reports myfcn is nearly zero at x = [0.5671 0.5671].

Exit Messages

Each solver issues a message to the MATLAB^® command window at the end of its iterations. This message explains briefly why the solver halted. The message might give more detail than the exit flag.

Many examples in this documentation show exit messages, such as Define and Solve Problem at Command Line. The example in the previous section, Exit Flags, shows the following exit message:

Equation solved.

fsolve completed because the vector of function values is near zero
as measured by the value of the function tolerance, and
the problem appears regular as measured by the gradient.

This message is more informative than the exit flag. The message indicates that the gradient is relevant. The message also states that the function tolerance controls how near 0 the vector of function values must be for fsolve to regard the solution as completed.

Enhanced Exit Messages

Some solvers have exit messages that contain links for more information. There are two types of links:

• Links on words or phrases. These links give definitions of terms or other information.

• A link as the last line of the display saying <stopping criteria details>. If you click this link, MATLAB displays more detail about the reason the solver halted.

The fminunc solver has enhanced exit messages.

[xfinal fval exitflag] = fminunc(@sin,0)

This yields the following results:

Each of the underlined words or phrases contains a link that provides more information.

• The <stopping criteria details> link prints the following to the MATLAB command line:

  Optimization completed: The first-order optimality measure, 0.000000e+00, is less 
  than options.OptimalityTolerance = 1.000000e-06.

• The other links point to the documentation for term definitions. For example, clicking the Local minimum found link opens the following:

  

  Clicking the first-order optimality measure link brings up the definition of first-order optimality measure for fminunc:

  

• The other links lead to similar documentation definitions.

Exit Message Options

Set the Display option to control the appearance of both exit messages and iterative display. For more information, see Iterative Display. The following table shows the effect of the various settings of the Display option.

Value of the Display Option	Output to Command Window
	Exit message	Iterative Display
'none', or the synonymous 'off'	None	None
'final' (default for most solvers)	Default	None
'final-detailed'	Detailed	None
'iter'	Default	Yes
'iter-detailed'	Detailed	Yes
'notify'	Default only if exitflag ≤ 0	None
'notify-detailed'	Detailed only if exitflag ≤ 0	None

For example,

opts = optimoptions(@fminunc,'Display','iter-detailed','Algorithm','quasi-newton');
[xfinal fval] = fminunc(@cos,1,opts);

yields the following display:

Related Topics

• Solver Outputs and Iterative Display