The Outputfcn
field of options
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.
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, do the following:
Write the output function as a function file or local function.
Use optimoptions
to
set the value of Outputfcn
to be a function handle,
that is, the name of the function preceded by the @ sign. For example,
if the output function is outfun.m
, the command
options = optimoptions(@solvername,'OutputFcn', @outfun);
specifies OutputFcn
to be the handle to outfun
.
To specify more than one output function, use the syntax
options = optimoptions(@solvername,'OutputFcn',{@outfun, @outfun2});
Call the optimization function with options
as
an input argument.
See Output Functions for an example of an output function.
Passing Extra Parameters explains how to parametrize the output function
OutputFcn
, if necessary.
The function definition line of the output 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 is true
or false
depending
on whether the optimization routine should quit or continue. See Stop Flag for more information.
The optimization function passes the values of the input arguments
to outfun
at each iteration.
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.
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.
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
for fminunc
TR
and fsolve
TRR
.
procedure
for fmincon
TRR
and SQP
,
and for fminunc
.
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 The partial derivative with respect to one of the variables is 0 at the point. A bound constraint is active for that variable at the point. 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. 
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.
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
The output argument stop
is a flag that is true
or false
.
The flag tells the optimization function whether the optimization
should quit or continue. The following examples show typical ways
to use the stop
flag.
The output function can stop an optimization at any iteration
based on the current data in optimValues
. For example,
the following code sets stop
to true
if
the directional derivative is less than .01
:
function stop = outfun(x,optimValues,state) stop = false; % Check if directional derivative is less than .01. if optimValues.directionalderivative < .01 stop = true; end
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');