Optimization Options Reference - MATLAB & Simulink (original) (raw)
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 enteringoptimoptions('_`solvername`_') or the equivalent optimoptions(@_`solvername`_). For example,
returns a list of the options and the default values for the default'interior-point' fmincon algorithm. To find the default values for anotherfmincon 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 inHidden Options.
Optimization Options
| Option Name | Description | Used by Functions | Restrictions |
|---|---|---|---|
| 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 toAbsoluteGapTolerance:U – L <= AbsoluteGapTolerance. | intlinprog | optimoptions 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 vectorf. | intlinprog | optimoptions only |
| CheckGradients | Compare user-supplied analytic derivatives (gradients or Jacobian, depending on the selected solver) to finite differencing derivatives.The CheckGradients option will be removed in a future release. To check derivatives, use the checkGradients function. | fmincon, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | optimoptions only. For optimset, use DerivativeCheck |
| ConstraintTolerance | Tolerance on the constraint violation. | coneprog, fgoalattain, fmincon, fminimax, fseminf, intlinprog, linprog, lsqlin, quadprog | optimoptions only. For optimset, use TolCon |
| CutGeneration | Level of cut generation (see Cut Generation):'none' — No cuts. MakesCutMaxIterations irrelevant.'basic' — Normal cut generation.'intermediate' — Use more cut types.'advanced' — Use most cut types. | intlinprog | optimoptions only |
| CutMaxIterations | Number of passes through all cut generation methods before entering the branch-and-bound phase, an integer from 1 through50. Disable cut generation by setting theCutGeneration option to 'none'. | intlinprog | optimoptions 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 objectivefun to equal the set goal. Reorder your objectives, if necessary, to have fgoalattain achieve the firstEqualityGoalCount 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 aredelta = v.*sign′(x).*max(abs(x),TypicalX);where sign′(x) = sign(x) except sign′(0) = 1. Central finite differences aredelta = v.*max(abs(x),TypicalX);A scalar FiniteDifferenceStepSize expands to a vector. The default is sqrt(eps) for forward finite differences, and eps^(1/3) for central finite differences. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | 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 tofalse. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | optimoptions only. For optimset, use FinDiffType |
| FunctionTolerance | Termination tolerance on the function value. | fgoalattain, fmincon, fminimax, fminsearch, fminunc, fseminf, fsolve, lsqcurvefit, lsqlin, lsqnonlin, quadprog | optimoptions only. For optimset, use TolFun |
| HessianApproximation | Method of Hessian approximation: 'bfgs','lbfgs', {'lbfgs',Positive Integer}, or'finite-difference'.Ignored whenHessianFcn or HessianMultiplyFcn is nonempty. | fmincon | optimoptions only. For optimset, use Hessian |
| HessianFcn | User-supplied Hessian, specified as a function handle (see Including Hessians). | fmincon, fminunc | optimoptions only. For optimset, use HessFcn |
| HessianMultiplyFcn | User-supplied Hessian multiply function, specified as a function handle.Ignored when HessianFcn is nonempty. | fmincon, fminunc, quadprog | optimoptions only. For optimset, use HessMult |
| Heuristics | Algorithm for searching for feasible points (see Heuristics for Finding Feasible Solutions):'basic''intermediate''advanced''rss''rins''round''diving''rss-diving''rins-diving''round-diving''none' | intlinprog | optimoptions only |
| HeuristicsMaxNodes | Strictly positive integer that bounds the number of nodesintlinprog can explore in its branch-and-bound search for feasible points. See Heuristics for Finding Feasible Solutions. | intlinprog | optimoptions only |
| HonorBounds | The default true ensures that bound constraints are satisfied at every iteration. Turn off by setting to false. | fmincon | optimoptions 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. | intlinprog | optimoptions only |
| IntegerTolerance | Real 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. | intlinprog | optimoptions only |
| JacobianMultiplyFcn | User-defined Jacobian multiply function, specified as a function handle. Ignored unless SpecifyObjectiveGradient istrue for fsolve, lsqcurvefit, and lsqnonlin. | fsolve, lsqcurvefit, lsqlin, lsqnonlin | |
| LinearSolver | Type of internal linear solver in algorithm. Forlsqlin and quadprog:'auto' — Use 'sparse' if the passed quadratic matrix is sparse (H forquadprog, C forlsqlin), '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].'normal-dense' — Normal form step solver using dense linear algebra.'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 | optimoptions only |
| LPMaxIterations | Strictly positive integer, the maximum number of simplex algorithm iterations per node during the branch-and-bound process. | intlinprog | optimoptions only |
| LPOptimalityTolerance | Nonnegative real where reduced costs must exceedLPOptimalityTolerance for a variable to be taken into the basis. | intlinprog | optimoptions only |
| MaxFunctionEvaluations | Maximum number of function evaluations allowed. | fgoalattain, fminbnd, fmincon, fminimax, fminsearch, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | optimoptions only. For optimset, use MaxFunEvals |
| MaxIterations | Maximum number of iterations allowed. | All but fzero and lsqnonneg | optimoptions only. For optimset, use MaxIter |
| MaxFeasiblePoints | Strictly positive integer. intlinprog stops if it findsMaxFeasiblePoints integer feasible points. | intlinprog | optimoptions only |
| MaxNodes | Strictly 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. | coneprog, intlinprog, linprog | |
| 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. | intlinprog | optimoptions only |
| ObjectiveCutOff | Real greater than -Inf. The default isInf. | intlinprog | optimoptions only |
| ObjectiveImprovementThreshold | Nonnegative 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. | intlinprog |
| ObjectiveLimit | If the objective function value goes belowObjectiveLimit and the iterate is feasible, then the iterations halt. | fmincon, fminunc, lsqlin, quadprog | |
| 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. | fgoalattain, fminbnd, fmincon, fminimax, fminsearch, fminunc, fseminf, fsolve, fzero, intlinprog, lsqcurvefit, lsqnonlin | |
| 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.'optimplot' plots the function value and constraint satisfaction, similar to 'optimplotfvalconstr', except 'optimplot' determines feasibility based on the ConstraintTolerance and algorithm, whereas 'optimplotfvalconstr' uses a fixed tolerance of1e-6. In addition, 'optimplot' shows the coordinates of the iterative points, and displays the satisfaction of the stopping criteria. For an example, see Monitor Solution Process with optimplot. The'optimplot' plot function plots into a new window that is not shared with any other plot function.'optimplotx' plots the current point.'optimplotfunccount' plots the function count.'optimplotfval' plots the function value.'optimplotfvalconstr' plots the best feasible objective function value found. The plot shows infeasible points in one color and feasible points in another, 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.See Plot Functions or intlinprog Output Function and Plot Function Syntax. | 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 toRelativeGapTolerance:(U – L) / (abs(U) + 1) <= RelativeGapTolerance. | intlinprog | optimoptions only |
| RootLPAlgorithm | Algorithm for solving linear programs:'dual-simplex' — Dual simplex algorithm'primal-simplex' — Primal simplex algorithm | intlinprog | optimoptions only |
| RootLPMaxIterations | Nonnegative integer that is the maximum number of simplex algorithm iterations to solve the initial linear programming problem. | intlinprog | optimoptions 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 defaultfalse. | fmincon | |
| SpecifyConstraintGradient | User-defined gradients for the nonlinear constraints. | fgoalattain, fmincon, fminimax | optimoptions only. For optimset, use GradConstr |
| SpecifyObjectiveGradient | User-defined gradients or Jacobians for the objective functions. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | optimoptions only. For optimset, use GradObj orJacobian |
| 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 parametersx. The size of the array is equal to the size ofx0, the starting point. Primarily for scaling finite differences for gradient estimation. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqlin, lsqnonlin, quadprog | |
| UseParallel | When true, applicable solvers estimate gradients in parallel. Disable by setting to false. | fgoalattain, fmincon, fminimax, fminunc, fsolve, lsqcurvefit, lsqnonlin. |
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, seeView Optimization 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 Name | Description | Used by Functions | Restrictions |
|---|---|---|---|
| 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. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | |
| DiffMinChange | Minimum change in variables for finite differencing. | fgoalattain, fmincon, fminimax, fminunc, fseminf, fsolve, lsqcurvefit, lsqnonlin | |
| 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. NoteFunValCheck does not return an error forInf when used with fminbnd,fminsearch, or fzero, which handleInf appropriately.'off' displays no error. | fgoalattain, fminbnd, fmincon, fminimax, fminsearch, fminunc, fseminf, fsolve, fzero, lsqcurvefit, lsqnonlin | |
| 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 inx0, the starting point. | fmincon, fminunc | |
| HessUpdate | Quasi-Newton updating scheme. | fminunc | |
| InitBarrierParam | Initial barrier value. | fmincon | |
| InitDamping | Initial Levenberg-Marquardt parameter. | fsolve, lsqcurvefit, lsqnonlin | optimoptions only |
| InitTrustRegionRadius | 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, wherem 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. | fsolve, lsqcurvefit, lsqnonlin | |
| LPPreprocess | Type of preprocessing for the solution to the relaxed linear program (see Linear Program Preprocessing):'none' — No preprocessing.'basic' — Use preprocessing. | intlinprog | optimoptions only |
| MaxPCGIter | Maximum number of iterations of preconditioned conjugate gradients method allowed. | fmincon, fminunc, fsolve, lsqcurvefit, lsqlin, lsqnonlin, quadprog | |
| 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. | fgoalattain, fmincon, fminimax | |
| MeritFunction | Use goal attainment/minimax merit function (multiobjective) vs.fmincon (single objective). | fgoalattain, fminimax | |
| PrecondBandWidth | Upper bandwidth of preconditioner for PCG. Setting to'Inf' uses a direct factorization instead of CG. | fmincon, fminunc, fsolve, lsqcurvefit, lsqlin, lsqnonlin, quadprog | |
| Preprocess | Level of LP preprocessing prior to simplex or dual simplex algorithm iterations. | linprog | optimoptions only |
| RelLineSrchBnd | Relative bound on line search step length. | fgoalattain, fmincon, fminimax, fseminf | |
| RelLineSrchBndDuration | Number of iterations for which the bound specified inRelLineSrchBnd should be active. | fgoalattain, fmincon, fminimax, fseminf | |
| ScaleProblem | When using the Algorithm option'levenberg-marquardt', setting theScaleProblem 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. | fmincon, fminunc, fsolve, lsqcurvefit, lsqlin, lsqnonlin, quadprog | |
| 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 Name | Used 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 |
| TolBind | patternsearch |