The following table describes optimization options. Create options
using the optimoptions
function,
or optimset
for fminbnd
, fminsearch
, fzero
,
or lsqnonneg
.
See the individual function reference pages for information about available option values and defaults.
The default values for the options vary depending on which optimization
function you call with options
as an input argument.
You can determine the default option values for any of the optimization
functions by entering optimoptions(@
or
the equivalent solvername
)optimoptions('
.
For example,solvername
')
optimoptions(@fmincon)
returns a list of the options and the default values for the
default 'interiorpoint'
fmincon
algorithm.
To find the default values for another fmincon
algorithm,
set the Algorithm
option. For example,
opts = optimoptions(@fmincon,'Algorithm','sqp')
Optimization Options
Option Name  Description  Used by Functions  Restrictions  

Algorithm  Chooses the algorithm used by the solver.  fmincon , fminunc , fsolve , linprog , lsqcurvefit , lsqlin , lsqnonlin , quadprog  
AlwaysHonorConstraints  The default  fmincon  
BranchingRule  Rule for choosing the component for branching:
 intlinprog  optimoptions only  
CutGeneration  Level of cut generation (see Cut Generation):
 intlinprog  optimoptions only  
CutGenMaxIter  Number of passes through all cut generation methods before
entering the branchandbound phase, an integer from 1 through 50 .
Disable cut generation by setting the CutGeneration option
to 'none' .  intlinprog  optimoptions only  
DerivativeCheck  Compare usersupplied analytic derivatives (gradients or Jacobian, depending on the selected solver) to finite differencing derivatives. 
 
Diagnostics  Display diagnostic information about the function to be minimized or solved.  All but  
 Maximum change in variables for finite differencing. 
 
 Minimum change in variables for finite differencing. 
 
Display  Level of display.
 All. See the individual function reference pages for the values that apply.  
FinDiffRelStep  Scalar or vector step size factor for finite differences. When
you set
where
Scalar 
 
FinDiffType  Finite differences, used to estimate gradients, are either 
 
FunValCheck  Check whether objective function and constraints values
are valid.

 
GoalsExactAchieve  Specify the number of objectives required for the objective  
GradConstr  Userdefined gradients for the nonlinear constraints.  
GradObj  Userdefined gradients for the objective functions.  
HessFcn  Function handle to a usersupplied Hessian (see Hessian).  fmincon  
Hessian  If  
HessMult  Handle to a usersupplied Hessian multiply function.
For  
HessPattern  Sparsity pattern of the Hessian for finite differencing.
The size of the matrix is nbyn, where n is the number of elements
in  
HessUpdate  QuasiNewton updating scheme.  
Heuristics  Algorithm for searching for feasible points (see Heuristics for Finding Feasible Solutions):
 intlinprog  optimoptions only  
HeuristicsMaxNodes  Strictly positive integer that bounds the number of nodes intlinprog can
explore in its branchandbound search for feasible points. See Heuristics for Finding Feasible Solutions.  intlinprog  optimoptions only  
InitBarrierParam  Initial barrier value.  fmincon  
InitDamping  Initial LevenbergMarquardt parameter.  fsolve , lsqcurvefit , lsqnonlin  optimoptions only  
InitialHessMatrix This option will be removed in a future release.  Initial quasiNewton matrix.  optimset only  
InitialHessType This option will be removed in a future release.  Initial quasiNewton matrix type.  optimset only  
InitTrustRegionRadius  Initial radius of the trust region.  fmincon  
IPPreprocess  Types of integer preprocessing (see MixedInteger Program Preprocessing):
 intlinprog  optimoptions only  
Jacobian  If  
JacobMult  Userdefined Jacobian multiply function. Ignored unless  
JacobPattern  Sparsity pattern of the Jacobian for finite differencing.
The size of the matrix is  
Use  Use largescale algorithm if possible.  optimset only  
LPMaxIter  Strictly positive integer, the maximum number of simplex algorithm iterations per node during the branchandbound process.  intlinprog  optimoptions only  
LPPreprocess  Type of preprocessing for the solution to the relaxed linear
program (see Linear Program Preprocessing):
 intlinprog  optimoptions only  
MaxFunEvals  Maximum number of function evaluations allowed. 
 
MaxIter  Maximum number of iterations allowed.  
MaxNodes  Strictly positive integer that is the maximum number of nodes the solver explores in its branchandbound process.  
MaxNumFeasPoints  Strictly positive integer. intlinprog stops
if it finds MaxNumFeasPoints integer feasible points.  intlinprog  optimoptions only  
MaxPCGIter  Maximum number of iterations of preconditioned conjugate gradients method allowed. 
 
MaxProjCGIter  A tolerance for the number of projected conjugate gradient iterations; this is an inner iteration, not the number of iterations of the algorithm.  fmincon  
MaxSQPIter  Maximum number of iterations of sequential quadratic programming method allowed.  
MaxTime  Maximum amount of time in seconds allowed for the algorithm.  
MeritFunction  Use goal attainment/minimax merit function (multiobjective)
vs.  
MinAbsMax  Number of F(x) to minimize the worst case absolute values.  
NodeSelection  Choose the node to explore next.
 intlinprog  optimoptions only  
ObjectiveCutOff  Real greater than Inf . The default is Inf .  intlinprog  optimoptions only  
ObjectiveLimit  If the objective function value goes below  fmincon , fminunc , quadprog  
OutputFcn  Specify one or more userdefined functions that the optimization
function calls at each iteration. See Output Function or 
 
PlotFcns  Plots various measures of progress while the algorithm executes, select from predefined plots or write your own.
See Plot Functions or 
 
PrecondBandWidth  Upper bandwidth of preconditioner for PCG. Setting to 
 
Preprocess  Level of LP preprocessing prior to simplex or dual simplex algorithm iterations.  optimoptions only  
RelLineSrchBnd  Relative bound on line search step length.  
RelLineSrchBndDuration  Number of iterations for which the bound specified in  
RelObjThreshold  Nonnegative real. intlinprog changes the
current feasible solution only when it locates another with an objective
function value that is at least RelObjThreshold lower: (fold
– fnew)/(1 + fold) > RelObjThreshold.  intlinprog  optimoptions only  
RootLPAlgorithm  Algorithm for solving linear programs:
 intlinprog  optimoptions only  
RootLPMaxIter  Nonnegative integer that is the maximum number of simplex algorithm iterations to solve the initial linear programming problem.  intlinprog  optimoptions only  
ScaleProblem  For For
the other solvers, when using the  fmincon , fsolve , lsqcurvefit , lsqnonlin , quadprog  
Use  If  optimset only  
SubproblemAlgorithm  Determines how the iteration step is calculated.  fmincon  
TolCon  Tolerance on the constraint violation. 
 
TolConSQP  Constraint violation tolerance for the inner SQP iteration.  fgoalattain , fmincon , fminimax , fseminf  
TolFun  Termination tolerance on the function value. 
 
TolFunLP  Nonnegative real where reduced costs must exceed TolFunLP for
a variable to be taken into the basis.  intlinprog  optimoptions only  
TolGapAbs  Nonnegative real. intlinprog stops if
the difference between the internally calculated upper (U )
and lower (L ) bounds on the objective function
is less than or equal to TolGapAbs :
 intlinprog  optimoptions only  
TolGapRel  Real from 0 through 1 . intlinprog stops
if the relative difference between the internally calculated upper
(U ) and lower (L ) bounds on
the objective function is less than or equal to TolGapRel :
 intlinprog  optimoptions only  
TolInteger  Real from 1e6 through 1e3 ,
where the maximum deviation from integer that a component of the solution x can
have and still be considered an integer. TolInteger is
not a stopping criterion.  intlinprog  optimoptions only  
TolPCG  Termination tolerance on the PCG iteration. 
 
TolProjCG  A relative tolerance for projected conjugate gradient algorithm; this is for an inner iteration, not the algorithm iteration.  fmincon  
TolProjCGAbs  Absolute tolerance for projected conjugate gradient algorithm; this is for an inner iteration, not the algorithm iteration.  fmincon  
TolX  Termination tolerance on x.  All functions except  
TypicalX  Array that specifies typical magnitude of array of parameters 
 
UseParallel  When 
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.
Caution

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 parameterize 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.
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
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. 
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.
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 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.
Stopping an Optimization Based on Data in optimValues. 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
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');
The PlotFcns
field of the options
structure
specifies one or more functions that an optimization function calls
at each iteration to plot various measures of progress while the algorithm
executes. The structure of a plot function is the same as that for
an output function. For more information on writing and calling a
plot function, see Output Function.
For an example of using builtin plot functions, Using a Plot Function.
To view a predefined plot function listed for PlotFcns
,
you can open it in the MATLAB^{®} Editor. For example, to view the
file corresponding to the norm of residuals, enter:
edit optimplotresnorm.m