Output Function and Plot Function Syntax
What Are Output Functions and Plot Functions?
For examples of output functions and plot functions, see Output Functions for Optimization Toolbox and Plot Functions.
The OutputFcn
option specifies one or more functions that an
optimization function calls at each iteration. Typically, you might use an output function
to plot points at each iteration or to display optimization quantities from the algorithm.
Using an output function you can view, but not set, optimization quantities. You can also
halt the execution of a solver according to conditions you set; see Structure of the Output Function or Plot Function.
Similarly, the PlotFcn
option specifies one or more functions that an
optimization function calls at each iteration, and can halt the solver. The difference
between a plot function and an output function is twofold:
Predefined plot functions exist for most solvers, enabling you to obtain typical plots easily.
A plot function sends output to a window having Pause and Stop buttons, enabling you to halt the solver early without losing information.
Caution
intlinprog
output functions and plot functions differ from those
in other solvers. See intlinprog Output Function and Plot Function Syntax.
To set up an output function or plot function, do the following:
Write the function as a function file or local function.
Use
optimoptions
to set the value ofOutputFcn
orPlotFcn
to be a function handle, that is, the name of the function preceded by the @ sign. For example, if the output function isoutfun.m
, the commandoptions = optimoptions(@solvername,'OutputFcn',@outfun);
specifies
OutputFcn
to be the handle tooutfun
. To specify more than one output function or plot function, use the syntaxoptions = optimoptions('solvername','OutputFcn',{@outfun, @outfun2});
To use tabcompletion to help select a builtin plot function name, use quotes rather than a function handle.
Call the optimization function with
options
as an input argument.
Passing Extra Parameters explains how to pass parameters or data to your output function or plot function, if necessary.
Structure of the Output Function or Plot Function
The function definition line of the output function or plot function has the following form:
stop = outfun(x,optimValues,state)
where
x
is the point computed by the algorithm at the current iteration.optimValues
is a structure containing data from the current iteration. Fields in optimValues describes the structure in detail.state
is the current state of the algorithm. States of the Algorithm lists the possible values.stop
is a flag that istrue
orfalse
depending on whether the optimization routine should stop (true
) or continue (false
). For details, see Stop Flag.
The optimization function passes the values of the input arguments to
outfun
at each iteration.
Fields in optimValues
The following table lists the fields of the optimValues
structure. A
particular optimization function returns values for only some of these fields. For each
field, the Returned by Functions column of the table lists the functions that return the
field.
Corresponding Output Arguments
Some of the fields of optimValues
correspond to output arguments of
the optimization function. After the final iteration of the optimization algorithm, the
value of such a field equals the corresponding output argument. For example,
optimValues.fval
corresponds to the output argument
fval
. So, if you call fmincon
with an output
function and return fval
, the final value of
optimValues.fval
equals fval
. The Description
column of the following table indicates the fields that have a corresponding output
argument.
CommandLine Display
The values of some fields of optimValues
are displayed at the
command line when you call the optimization function with the Display
field of options
set to 'iter'
, as described in
Iterative Display. For example, optimValues.fval
is displayed in the f(x)
column. The CommandLine Display column of the
following table indicates the fields that you can display at the command line.
Some optimValues
fields apply only to specific algorithms:
AS —
activeset
D —
trustregiondogleg
IP —
interiorpoint
LM —
levenbergmarquardt
Q —
quasinewton
SQP —
sqp
TR —
trustregion
TRR —
trustregionreflective
Some optimValues
fields exist in certain solvers or algorithms, but
are always filled with empty or zero values, so are meaningless. These fields
include:
constrviolation
forfminunc
TR
andfsolve
TRR
.procedure
forfmincon
TRR
andSQP
, and forfminunc
.
optimValues Fields
OptimValues Field (optimValues.field)  Description  Returned by Functions  CommandLine Display 

 Attainment factor for multiobjective problem. For details, see Goal Attainment Method.  None  
 Number of conjugate gradient iterations at current optimization iteration. 

See Iterative Display. 
 Maximum constraint violation. 

See Iterative Display. 
 Measure of degeneracy. A point is degenerate if:
See Degeneracy. 
 None 
 Directional derivative in the search direction. 

See Iterative Display. 
 Firstorder optimality (depends on algorithm). Final value equals
optimization function output


See Iterative Display. 
 Cumulative number of function evaluations. Final value equals
optimization function output 

See Iterative Display. 
 Function value at current point. Final value equals optimization
function output For


See Iterative Display. 
 Current gradient of objective function — either analytic
gradient if you provide it or finitedifferencing approximation. Final value
equals optimization function output 
 None 
 Iteration number — starts at 

See Iterative Display. 
 The LevenbergMarquardt parameter, 


 Actual step length divided by initially predicted step length 
See Iterative Display.  
 Maximum function value  fminimax  None 


 None 
 Procedure messages. 

See Iterative Display. 
 Ratio of change in the objective function to change in the quadratic approximation. 
 None 
 The residual vector. 
See Iterative Display.  
 2norm of the residual squared. 
See Iterative Display.  
 Search direction. 
 None 
 Status of the current trustregion step. Returns true if the current trustregion step was successful, and false if the trustregion step was unsuccessful. 
 None 
 Current step size (displacement in 

See Iterative Display. 
 Radius of trust region. 

See Iterative Display. 
Degeneracy
The value of the field degenerate
, which measures the degeneracy of
the current optimization point x
, is defined as follows. First, define
a vector r
, of the same size as x
, for which
r(i)
is the minimum distance from x(i)
to the
ith entries of the lower and upper bounds, lb
and
ub
. That is,
r = min(abs(ubx, xlb))
Then the value of degenerate
is the minimum entry of the vector
r + abs(grad)
, where grad
is the
gradient of the objective function. The value of degenerate
is 0 if
there is an index i
for which both of the following are true:
grad(i) = 0
x(i)
equals the ith entry of either the lower or upper bound.
States of the Algorithm
The following table lists the possible values for state
:
State  Description 

 The algorithm is in the initial state before the first iteration. 
 The algorithm is in some computationally expensive part of the iteration.
In this state, the output function can interrupt the current iteration of the
optimization. At this time, the values of 
 The algorithm is at the end of an iteration. 
 The algorithm is in the final state after the last iteration. 
The 'interrupt'
state occurs only in the fmincon
'activeset'
algorithm and the fgoalattain
,
fminimax
, and fseminf
solvers. There, the state
can occur before a quadratic programming subproblem solution or a line search.
The following code illustrates how the output function might use the value of
state
to decide which tasks to perform at the current iteration:
switch state case 'iter' % Make updates to plot or guis as needed case 'interrupt' % Probably no action here. Check conditions to see % whether optimization should quit. case 'init' % Setup for plots or guis case 'done' % Cleanup of plots, guis, or final plot otherwise end
Stop Flag
The output argument stop
is a flag that is true
or
false
. The flag tells the optimization function whether the
optimization should stop (true
) or continue (false
).
The following examples show typical ways to use the stop
flag.
Stopping an Optimization Based on Data in optimValues
The output function or plot function can stop an optimization at any iteration based
on the current data in optimValues
. For example, the following code
sets stop
to true
, stopping the optimization, when
the size of the directional derivative is less than .01
:
function stop = outfun(x,optimValues,state) stop = false; % Check whether directional derivative norm is less than .01. if norm(optimValues.directionalderivative) < .01 stop = true; end
Stopping an Optimization Based on GUI Input
If you design a GUI to perform optimizations, you can make the output function stop an
optimization when a user clicks a Stop button on the GUI. The
following code shows how to do this, assuming that the Stop button
callback stores the value true
in the optimstop
field of a handles
structure called hObject
:
function stop = outfun(x,optimValues,state) stop = false; % Check if user has requested to stop the optimization. stop = getappdata(hObject,'optimstop');