Optimization Options Reference

Optimization Options

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('solvername') or the equivalent optimoptions(@solvername). For example,

optimoptions('fmincon')

returns a list of the options and the default values for the default 'interior-point' fmincon algorithm. To find the default values for another fmincon algorithm, set the Algorithm option. For example,

opts = optimoptions('fmincon','Algorithm','sqp')

optimoptions “hides” some options, meaning it does not display their values. Those options do not appear in this table. Instead, they appear in Hidden Options.

Optimization Options

Option NameDescriptionUsed by FunctionsRestrictions
AbsoluteGapTolerance

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 AbsoluteGapTolerance:

U – L <= AbsoluteGapTolerance.

intlinprogoptimoptions only
AbsoluteMaxObjectiveCount

Number of F(x) to minimize the worst case absolute values.

fminimax

Algorithm

Chooses the algorithm used by the solver.

fmincon, fminunc, fsolve, linprog, lsqcurvefit, lsqlin, lsqnonlin, quadprog
BarrierParamUpdate

Chooses the algorithm for updating the barrier parameter in the 'interior-point' algorithm, either 'monotone' or 'predictor-corrector'.

fmincon
BranchRule

Rule for choosing the component for branching:

• 'maxpscost' — The fractional component with maximum pseudocost. See Branch and Bound.

• 'strongpscost' — The fractional component with maximum pseudocost, with a careful estimate of pseudocost. See Branch and Bound.

• 'reliability' — The fractional component with maximum pseudocost, with an even more careful estimate of pseudocost than in 'strongpscost'. See Branch and Bound.

• 'mostfractional' — The component whose fractional part is closest to 1/2.

• 'maxfun' — The fractional component with maximal corresponding component in the absolute value of objective vector f.

intlinprogoptimoptions only

Compare user-supplied analytic derivatives (gradients or Jacobian, depending on the selected solver) to finite differencing derivatives.

optimoptions only. For optimset, use DerivativeCheck
ConstraintTolerance

Tolerance on the constraint violation.

optimoptions only. For optimset, use TolCon
CutGeneration

Level of cut generation (see Cut Generation):

• 'none' — No cuts. Makes CutMaxIterations irrelevant.

• 'basic' — Normal cut generation.

• 'intermediate' — Use more cut types.

• 'advanced' — Use most cut types.

intlinprogoptimoptions only
CutMaxIterationsNumber of passes through all cut generation methods before entering the branch-and-bound phase, an integer from 1 through 50. Disable cut generation by setting the CutGeneration option to 'none'.intlinprogoptimoptions only
Display

Level of display.

• 'off' displays no output.

• 'iter' displays output at each iteration, and gives the default exit message.

• 'iter-detailed' displays output at each iteration, and gives the technical exit message.

• 'notify' displays output only if the function does not converge, and gives the default exit message.

• 'notify-detailed' displays output only if the function does not converge, and gives the technical exit message.

• 'final' displays just the final output, and gives the default exit message.

• 'final-detailed' displays just the final output, and gives the technical exit message.

All. See the individual function reference pages for the values that apply.

EnableFeasibilityMode

Chooses the algorithm for achieving feasibility in the 'interior-point' algorithm. true uses a different algorithm than the default false.

fmincon
EqualityGoalCount

Specify the number of objectives required for the objective fun to equal the set goal. Reorder your objectives, if necessary, to have fgoalattain achieve the first EqualityGoalCount objectives exactly.

fgoalattain

optimoptions only. For optimset, use GoalsExactAchieve
FiniteDifferenceStepSize

Scalar or vector step size factor for finite differences. When you set FiniteDifferenceStepSize to a vector v, the forward finite differences delta are

delta = v.*sign′(x).*max(abs(x),TypicalX);

where sign′(x) = sign(x) except sign′(0) = 1. Central finite differences are

delta = v.*max(abs(x),TypicalX);

Scalar FiniteDifferenceStepSize expands to a vector. The default is sqrt(eps) for forward finite differences, and eps^(1/3) for central finite differences.

optimoptions only. For optimset, use FinDiffRelStep
FiniteDifferenceType

Finite differences, used to estimate gradients, are either 'forward' (the default), or 'central' (centered), which takes twice as many function evaluations but should be more accurate. 'central' differences might violate bounds during their evaluation in fmincon interior-point evaluations if the HonorBounds option is set to false.

optimoptions only. For optimset, use FinDiffType
FunctionTolerance

Termination tolerance on the function value.

optimoptions only. For optimset, use TolFun
HessianApproximation

Method of Hessian approximation: 'bfgs', 'lbfgs', {'lbfgs',Positive Integer}, or 'finite-difference'.

Ignored when HessianFcn or HessianMultiplyFcn is nonempty.

fmincon

optimoptions only. For optimset, use Hessian
HessianFcn

User-supplied Hessian, specified as a function handle (see Including Hessians).

fmincon, fminuncoptimoptions only. For optimset, use HessFcn
HessianMultiplyFcn

User-supplied Hessian multiply function, specified as a function handle.

Ignored when HessianFcn is nonempty.

optimoptions only. For optimset, use HessMult
Heuristics

Algorithm for searching for feasible points (see Heuristics for Finding Feasible Solutions):

• 'basic'

• 'intermediate'

• 'rins'

• 'round'

• 'diving'

• 'rins-diving'

• 'round-diving'

• 'none'

intlinprogoptimoptions only
HeuristicsMaxNodesStrictly positive integer that bounds the number of nodes intlinprog can explore in its branch-and-bound search for feasible points. See Heuristics for Finding Feasible Solutions.intlinprogoptimoptions only
HonorBounds

The default true ensures that bound constraints are satisfied at every iteration. Turn off by setting to false.

fminconoptimoptions only. For optimset, use AlwaysHonorConstraints
IntegerPreprocess

Types of integer preprocessing (see Mixed-Integer Program Preprocessing):

• 'none' — Use very few integer preprocessing steps.

• 'basic' — Use a moderate number of integer preprocessing steps.

• 'advanced' — Use all available integer preprocessing steps.

intlinprogoptimoptions only
IntegerToleranceReal from 1e-6 through 1e-3, where the maximum deviation from integer that a component of the solution x can have and still be considered an integer. IntegerTolerance is not a stopping criterion.intlinprogoptimoptions only
JacobianMultiplyFcn

User-defined Jacobian multiply function, specified as a function handle. Ignored unless SpecifyObjectiveGradient is true for fsolve, lsqcurvefit, and lsqnonlin.

LinearSolver

Type of internal linear solver in algorithm. For lsqlin and quadprog:

• 'auto' — Use 'sparse' if the passed quadratic matrix is sparse (H for quadprog, C for lsqlin), 'dense' otherwise.

• 'sparse' — Use sparse linear algebra.

• 'dense' — Use dense linear algebra.

For coneprog:

• 'auto' (default) — coneprog chooses the step solver.

• If the problem is sparse, the step solver is 'prodchol'.

• Otherwise, the step solver is 'augmented'.

• 'augmented' — Augmented form step solver. See [1].

• 'normal' — Normal form step solver. See [1].

• 'prodchol' — Product form Cholesky step solver. See [4] and [5].

• 'schur' — Schur complement method step solver. See [2].

coneprog, lsqlin 'interior-point' algorithm and quadprog 'interior-point-convex' algorithm

LPMaxIterationsStrictly positive integer, the maximum number of simplex algorithm iterations per node during the branch-and-bound process.intlinprogoptimoptions only
LPOptimalityToleranceNonnegative real where reduced costs must exceed LPOptimalityTolerance for a variable to be taken into the basis.intlinprogoptimoptions only
MaxFunctionEvaluations

Maximum number of function evaluations allowed.

optimoptions only. For optimset, use MaxFunEvals
MaxIterations

Maximum number of iterations allowed.

All but fzero and lsqnonneg

optimoptions only. For optimset, use MaxIter
MaxFeasiblePointsStrictly positive integer. intlinprog stops if it finds MaxFeasiblePoints integer feasible points.intlinprogoptimoptions only
MaxNodesStrictly positive integer that is the maximum number of nodes the solver explores in its branch-and-bound process.

intlinprog

MaxTime

Maximum amount of time in seconds allowed for the algorithm.

NodeSelection

Choose the node to explore next.

• 'simplebestproj' — Best projection. See Branch and Bound.

• 'minobj' — Explore the node with the minimum objective function.

• 'mininfeas' — Explore the node with the minimal sum of integer infeasibilities. See Branch and Bound.

intlinprogoptimoptions only
ObjectiveCutOffReal greater than -Inf. The default is Inf.intlinprogoptimoptions only
ObjectiveImprovementThresholdNonnegative real. intlinprog changes the current feasible solution only when it locates another with an objective function value that is at least ObjectiveImprovementThreshold lower: (fold – fnew)/(1 + |fold|) > ObjectiveImprovementThreshold.intlinprogoptimoptions only
ObjectiveLimit

If the objective function value goes below ObjectiveLimit and the iterate is feasible, then the iterations halt.

OptimalityTolerance

Termination tolerance on the first-order optimality.

coneprog, fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, linprog (interior-point only), lsqcurvefit, lsqlin, lsqnonlin, quadprog

optimoptions only. For optimset, use TolFun
OutputFcn

Specify one or more user-defined functions that the optimization function calls at each iteration. Pass a function handle or a cell array of function handles. See Output Function and Plot Function Syntax or intlinprog Output Function and Plot Function Syntax.

PlotFcn

Plots various measures of progress while the algorithm executes. Select from predefined plots or write your own. Give the function name as listed, or as a function handle such as @optimplotx. Pass a built-in plot function name, a function handle, or a cell array of built-in names or function handles. For custom plot functions, pass function handles.

• 'optimplotx' plots the current point

• 'optimplotfunccount' plots the function count

• 'optimplotfval' plots the function value

• 'optimplotfvalconstr' plots the best feasible objective function value found as a line plot. The plot shows infeasible points as red and feasible points as blue, using a feasibility tolerance of 1e-6.

• 'optimplotconstrviolation' plots the maximum constraint violation

• 'optimplotresnorm' plots the norm of the residuals

• 'optimplotfirstorderopt' plots the first-order of optimality

• 'optimplotstepsize' plots the step size

• 'optimplotmilp' plots the gap for mixed-integer linear programs

fgoalattain, fminbnd, fmincon, fminimax, fminsearch, fminunc, fseminf, fsolve, fzero, intlinprog, lsqcurvefit, lsqnonlin. See the individual function reference pages for the values that apply.

optimoptions only. For optimset, use PlotFcns
RelativeGapTolerance

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 RelativeGapTolerance:

(U – L) / (abs(U) + 1) <= RelativeGapTolerance.

intlinprogoptimoptions only
RootLPAlgorithm

Algorithm for solving linear programs:

• 'dual-simplex' — Dual simplex algorithm

• 'primal-simplex' — Primal simplex algorithm

intlinprogoptimoptions only
RootLPMaxIterationsNonnegative integer that is the maximum number of simplex algorithm iterations to solve the initial linear programming problem.intlinprogoptimoptions only
ScaleProblem

For fmincon interior-point and sqp algorithms, true causes the algorithm to normalize all constraints and the objective function by their initial values. Disable by setting to the default false.

fmincon

User-defined gradients for the nonlinear constraints.

optimoptions only. For optimset, use GradConstr

User-defined gradients or Jacobians for the objective functions.

optimoptions only. For optimset, use GradObj or Jacobian
StepTolerance

Termination tolerance on x.

All functions except linprog and coneprog

SubproblemAlgorithm

Determines how the iteration step is calculated.

fmincon, fminunc, fsolve, lsqcurvefit, lsqlin, lsqnonlin
TypicalX

Array that specifies typical magnitude of array of parameters x. The size of the array is equal to the size of x0, the starting point. Primarily for scaling finite differences for gradient estimation.

UseParallel

When true, applicable solvers estimate gradients in parallel. Disable by setting to false.

Hidden Options

optimoptions “hides” some options, meaning it does not display their values. To learn how to view these options, and why they are hidden, see View Options.

Function reference pages list these options in italics.

Hidden Optimization Toolbox Options

This table lists the hidden Optimization Toolbox™ options.

Options that optimoptions Hides

Option NameDescriptionUsed by FunctionsRestrictions
Diagnostics

Display diagnostic information about the function to be minimized or solved.

All but fminbnd, fminsearch, fzero, and lsqnonneg

DiffMaxChange

Maximum change in variables for finite differencing.

DiffMinChange

Minimum change in variables for finite differencing.

FunValCheck

Check whether objective function and constraints values are valid. 'on' displays an error when the objective function or constraints return a value that is complex, NaN, or Inf.

Note

FunValCheck does not return an error for Inf when used with fminbnd, fminsearch, or fzero, which handle Inf appropriately.

'off' displays no error.

HessPattern

Sparsity pattern of the Hessian for finite differencing. The size of the matrix is n-by-n, where n is the number of elements in x0, the starting point.

HessUpdate

Quasi-Newton updating scheme.

fminunc

InitBarrierParam

Initial barrier value.

fmincon
InitDamping

Initial Levenberg-Marquardt parameter.

fsolve, lsqcurvefit, lsqnonlinoptimoptions only

Initial radius of the trust region.

fmincon
JacobPattern

Sparsity pattern of the Jacobian for finite differencing. The size of the matrix is m-by-n, where m is the number of values in the first argument returned by the user-specified function fun, and n is the number of elements in x0, the starting point.

LPPreprocess

Type of preprocessing for the solution to the relaxed linear program (see Linear Program Preprocessing):

• 'none' — No preprocessing.

• 'basic' — Use preprocessing.

intlinprogoptimoptions 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.

MeritFunction

Use goal attainment/minimax merit function (multiobjective) vs. fmincon (single objective).

PrecondBandWidth

Upper bandwidth of preconditioner for PCG. Setting to 'Inf' uses a direct factorization instead of CG.

Preprocess

Level of LP preprocessing prior to simplex or dual simplex algorithm iterations.

linprog

optimoptions only
RelLineSrchBnd

Relative bound on line search step length.

RelLineSrchBndDuration

Number of iterations for which the bound specified in RelLineSrchBnd should be active.

ScaleProblem

When using the Algorithm option 'levenberg-marquardt', setting the ScaleProblem option to 'jacobian' sometimes helps the solver on badly-scaled problems.

fsolve, lsqcurvefit, lsqnonlin
TolConSQP

Constraint violation tolerance for the inner SQP iteration.

fgoalattain, fmincon, fminimax, fseminf
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

Hidden Global Optimization Toolbox Options

For the reasons these options are hidden, see Options that optimoptions Hides (Global Optimization Toolbox).

Options that optimoptions Hides

Option NameUsed by Functions
Cache

patternsearch

CacheSize

patternsearch

CacheTol

patternsearch

DisplayInterval

particleswarm, simulannealbnd

FunValCheck

particleswarm

HybridInterval

simulannealbnd

InitialPenalty

ga, patternsearch

MaxMeshSize

patternsearch

MeshRotate

patternsearch

MigrationDirection

ga

MigrationFraction

ga

MigrationInterval

ga

PenaltyFactor

ga, patternsearch

PlotInterval

ga, patternsearch, simulannealbnd

StallTest

ga

TolBindpatternsearch