fmincon

Find minimum of constrained nonlinear multivariable function

collapse all in page

Syntax

x = fmincon(fun,x0,A,b)
x = fmincon(fun,x0,A,b,Aeq,beq)
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
x = fmincon(problem)
[x,fval] = fmincon(___)
[x,fval,exitflag,output] = fmincon(___)
[x,fval,exitflag,output,lambda,grad,hessian] = fmincon(___)

Description

Nonlinear programming solver.

Finds the minimum of a problem specified by

minxf(x) such that {c(x)≤0ceq(x)=0A⋅x≤bAeq⋅x=beqlb≤x≤ub,

b and beq are vectors, A and Aeq are matrices, c(x) and ceq(x) are functions that return vectors, and f(x) is a function that returns a scalar. f(x), c(x), and ceq(x) can be nonlinear functions.

x, lb, and ub can be passed as vectors or matrices; see Matrix Arguments.

x = fmincon(fun,x0,A,b) starts at x0 and attempts to find a minimizer x of the function described in fun subject to the linear inequalities A*x ≤ b. x0 can be a scalar, vector, or matrix.

Note

Passing Extra Parameters explains how to pass extra parameters to the objective function and nonlinear constraint functions, if necessary.

example

x = fmincon(fun,x0,A,b,Aeq,beq) minimizes fun subject to the linear equalities Aeq*x = beq and A*x ≤ b. If no inequalities exist, set A = [] and b = [].

example

x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub) defines a set of lower and upper bounds on the design variables in x, so that the solution is always in the range lb ≤ x ≤ ub. If no equalities exist, set Aeq = [] and beq = []. If x(i) is unbounded below, set lb(i) = -Inf, and if x(i) is unbounded above, set ub(i) = Inf.

Note

If the specified input bounds for a problem are inconsistent, fmincon throws an error. In this case, output x is x0 and fval is [].

For the default 'interior-point' algorithm, fmincon sets components of x0 that violate the bounds lb ≤ x ≤ ub, or are equal to a bound, to the interior of the bound region. For the 'trust-region-reflective' algorithm, fmincon sets violating components to the interior of the bound region. For other algorithms, fmincon sets violating components to the closest bound. Components that respect the bounds are not changed. See Iterations Can Violate Constraints.

example

x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon) subjects the minimization to the nonlinear inequalities c(x) or equalities ceq(x) defined in nonlcon. fmincon optimizes such that c(x) ≤ 0 and ceq(x) = 0. If no bounds exist, set lb = [] and/or ub = [].

example

x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options) minimizes with the optimization options specified in options. Use optimoptions to set these options. If there are no nonlinear inequality or equality constraints, set nonlcon = [].

example

x = fmincon(problem) finds the minimum for problem, a structure described in problem.

example

[x,fval] = fmincon(___), for any syntax, returns the value of the objective function fun at the solution x.

example

[x,fval,exitflag,output] = fmincon(___) additionally returns a value exitflag that describes the exit condition of fmincon, and a structure output with information about the optimization process.

example

[x,fval,exitflag,output,lambda,grad,hessian] = fmincon(___) additionally returns:

  • lambda — Structure with fields containing the Lagrange multipliers at the solution x.

  • grad — Gradient of fun at the solution x.

  • hessian — Hessian of fun at the solution x. See fmincon Hessian.

example

Examples

collapse all

Open Live Script

Find the minimum value of Rosenbrock's function when there is a linear inequality constraint.

Set the objective function fun to be Rosenbrock's function. Rosenbrock's function is well-known to be difficult to minimize. It has its minimum objective value of 0 at the point (1,1). For more information, see Constrained Nonlinear Problem Using Optimize Live Editor Task or Solver. 

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;

Find the minimum value starting from the point [-1,2], constrained to have x(1)+2x(2)≤1. Express this constraint in the form Ax <= b by taking A = [1,2] and b = 1. Notice that this constraint means that the solution will not be at the unconstrained solution (1,1), because at that point x(1)+2x(2)=3>1.

x0 = [-1,2];
A = [1,2];
b = 1;
x = fmincon(fun,x0,A,b)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    0.5022    0.2489
Open Live Script

Find the minimum value of Rosenbrock's function when there are both a linear inequality constraint and a linear equality constraint.

Set the objective function fun to be Rosenbrock's function. 

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;

Find the minimum value starting from the point [0.5,0], constrained to have x(1)+2x(2)≤1 and 2x(1)+x(2)=1.

  • Express the linear inequality constraint in the form A*x <= b by taking A = [1,2] and b = 1.

  • Express the linear equality constraint in the form Aeq*x = beq by taking Aeq = [2,1] and beq = 1. 

x0 = [0.5,0];
A = [1,2];
b = 1;
Aeq = [2,1];
beq = 1;
x = fmincon(fun,x0,A,b,Aeq,beq)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    0.4149    0.1701
Open Live Script

Find the minimum of an objective function in the presence of bound constraints.

The objective function is a simple algebraic function of two variables.

fun = @(x)1+x(1)/(1+x(2)) - 3*x(1)*x(2) + x(2)*(1+x(1));

Look in the region where x has positive values, x(1) ≤ 1, and x(2) ≤ 2.

lb = [0,0];
ub = [1,2];

The problem has no linear constraints, so set those arguments to [].

A = [];
b = [];
Aeq = [];
beq = [];

Try an initial point in the middle of the region.

x0 = (lb + ub)/2;

Solve the problem.

x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    1.0000    2.0000

A different initial point can lead to a different solution.

x0 = x0/5;
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2
10-6 ×

    0.4000    0.4000

To determine which solution is better, see Obtain the Objective Function Value.

Open Live Script

Find the minimum of a function subject to nonlinear constraints

Find the point where Rosenbrock's function is minimized within a circle, also subject to bound constraints.

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;

Look within the region 0≤x(1)≤0.5, 0.2≤x(2)≤0.8.

lb = [0,0.2];
ub = [0.5,0.8];

Also look within the circle centered at [1/3,1/3] with radius 1/3. Use this code for the nonlinear constraint function.

function [c,ceq] = circlecon(x)
c = (x(1)-1/3)^2 + (x(2)-1/3)^2 - (1/3)^2;
ceq = [];
end

There are no linear constraints, so set those arguments to [].

A = [];
b = [];
Aeq = [];
beq = [];

Choose an initial point satisfying all the constraints.

x0 = [1/4,1/4];

Solve the problem.

nonlcon = @circlecon;
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)   
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    0.5000    0.2500
Open Live Script

Set options to view iterations as they occur and to use a different algorithm.

To observe the fmincon solution process, set the Display option to 'iter'. Also, try the 'sqp' algorithm, which is sometimes faster or more accurate than the default 'interior-point' algorithm. 

options = optimoptions('fmincon','Display','iter','Algorithm','sqp');

Find the minimum of Rosenbrock's function on the unit disk, ||x||2≤1. First create a function that represents the nonlinear constraint. Save this as a file named unitdisk.m on your MATLAB® path. 

type unitdisk.m
function [c,ceq] = unitdisk(x)
c = x(1)^2 + x(2)^2 - 1;
ceq = [];

Create the remaining problem specifications. Then run fmincon. 

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
nonlcon = @unitdisk;
x0 = [0,0];
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
 Iter  Func-count            Fval   Feasibility   Step Length       Norm of   First-order  
                                                                       step    optimality
    0           3    1.000000e+00     0.000e+00     1.000e+00     0.000e+00     2.000e+00  
    1          12    8.913011e-01     0.000e+00     1.176e-01     2.353e-01     1.107e+01  
    2          22    8.047847e-01     0.000e+00     8.235e-02     1.900e-01     1.330e+01  
    3          28    4.197517e-01     0.000e+00     3.430e-01     1.217e-01     6.172e+00  
    4          31    2.733703e-01     0.000e+00     1.000e+00     5.254e-02     5.705e-01  
    5          34    2.397111e-01     0.000e+00     1.000e+00     7.498e-02     3.164e+00  
    6          37    2.036002e-01     0.000e+00     1.000e+00     5.960e-02     3.106e+00  
    7          40    1.164353e-01     0.000e+00     1.000e+00     1.459e-01     1.059e+00  
    8          43    1.161753e-01     0.000e+00     1.000e+00     1.754e-01     7.383e+00  
    9          46    5.901602e-02     0.000e+00     1.000e+00     1.547e-02     7.278e-01  
   10          49    4.533081e-02     2.898e-03     1.000e+00     5.393e-02     1.252e-01  
   11          52    4.567454e-02     2.225e-06     1.000e+00     1.492e-03     1.679e-03  
   12          55    4.567481e-02     4.386e-12     1.000e+00     2.095e-06     1.502e-05  
   13          58    4.567481e-02     0.000e+00     1.000e+00     2.193e-12     1.406e-05  

Local minimum possible. Constraints satisfied.

fmincon stopped because the size of the current step is less than
the value of the step size tolerance and constraints are 
satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    0.7864    0.6177

For iterative display details, see Iterative Display.

Open Live Script

Include gradient evaluation in the objective function for faster or more reliable computations.

Include the gradient evaluation as a conditionalized output in the objective function file. For details, see Including Gradients and Hessians. The objective function is Rosenbrock's function,

f(x)=100(x2-x12)2+(1-x1)2,

which has gradient

∇f(x)=[-400(x2-x12)x1-2(1-x1)200(x2-x12)].

This code creates the rosenbrockwithgrad function, which implements the objective function with gradient..

function [f,g] = rosenbrockwithgrad(x)
% Calculate objective f
f = 100*(x(2) - x(1)^2)^2 + (1-x(1))^2;

if nargout > 1 % gradient required
    g = [-400*(x(2)-x(1)^2)*x(1)-2*(1-x(1));
        200*(x(2)-x(1)^2)];
end
end

Create options to use the objective function gradient.

options = optimoptions('fmincon','SpecifyObjectiveGradient',true);

Create the other inputs for the problem. Then call fmincon.

fun = @rosenbrockwithgrad;
x0 = [-1,2];
A = [];
b = [];
Aeq = [];
beq = [];
lb = [-2,-2];
ub = [2,2];
nonlcon = [];
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)   
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    1.0000    1.0000
Open Live Script

Solve the same problem as in Nondefault Options using a problem structure instead of separate arguments.

Create the options and a problem structure. See problem for the field names and required fields.

options = optimoptions('fmincon','Display','iter','Algorithm','sqp');
problem.options = options;
problem.solver = 'fmincon';
problem.objective = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
problem.x0 = [0,0];

The nonlinear constraint function unitdisk appears at the end of this example. Include the nonlinear constraint function in problem.

problem.nonlcon = @unitdisk;

Solve the problem.

x = fmincon(problem)
 Iter  Func-count            Fval   Feasibility   Step Length       Norm of   First-order  
                                                                       step    optimality
    0           3    1.000000e+00     0.000e+00     1.000e+00     0.000e+00     2.000e+00  
    1          12    8.913011e-01     0.000e+00     1.176e-01     2.353e-01     1.107e+01  
    2          22    8.047847e-01     0.000e+00     8.235e-02     1.900e-01     1.330e+01  
    3          28    4.197517e-01     0.000e+00     3.430e-01     1.217e-01     6.172e+00  
    4          31    2.733703e-01     0.000e+00     1.000e+00     5.254e-02     5.705e-01  
    5          34    2.397111e-01     0.000e+00     1.000e+00     7.498e-02     3.164e+00  
    6          37    2.036002e-01     0.000e+00     1.000e+00     5.960e-02     3.106e+00  
    7          40    1.164353e-01     0.000e+00     1.000e+00     1.459e-01     1.059e+00  
    8          43    1.161753e-01     0.000e+00     1.000e+00     1.754e-01     7.383e+00  
    9          46    5.901602e-02     0.000e+00     1.000e+00     1.547e-02     7.278e-01  
   10          49    4.533081e-02     2.898e-03     1.000e+00     5.393e-02     1.252e-01  
   11          52    4.567454e-02     2.225e-06     1.000e+00     1.492e-03     1.679e-03  
   12          55    4.567481e-02     4.386e-12     1.000e+00     2.095e-06     1.502e-05  
   13          58    4.567481e-02     0.000e+00     1.000e+00     2.193e-12     1.406e-05  

Local minimum possible. Constraints satisfied.

fmincon stopped because the size of the current step is less than
the value of the step size tolerance and constraints are 
satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    0.7864    0.6177

The iterative display and solution are the same as in Nondefault Options.

The following code creates the unitdisk function.

function [c,ceq] = unitdisk(x)
c = x(1)^2 + x(2)^2 - 1;
ceq = [];
end
Open Live Script

Call fmincon with the fval output to obtain the value of the objective function at the solution.

The Minimize with Bound Constraints example shows two solutions. Which is better? Run the example requesting the fval output as well as the solution.

fun = @(x)1+x(1)./(1+x(2)) - 3*x(1).*x(2) + x(2).*(1+x(1));
lb = [0,0];
ub = [1,2];
A = [];
b = [];
Aeq = [];
beq = [];
x0 = (lb + ub)/2;
[x,fval] = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x = 1×2

    1.0000    2.0000


fval = 
-0.6667

Run the problem using a different starting point x0.

x0 = x0/5;
[x2,fval2] = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.

<stopping criteria details>

x2 = 1×2
10-6 ×

    0.4000    0.4000


fval2 = 
1.0000

This solution has an objective function value fval2 = 1, which is higher than the first value fval = –0.6667. The first solution x has a lower local minimum objective function value.

Open Script

To easily examine the quality of a solution, request the exitflag and output outputs.

Set up the problem of minimizing Rosenbrock's function on the unit disk, $||x||^2 \le 1$. First create a function that represents the nonlinear constraint. Save this as a file named unitdisk.m on your MATLAB® path.

function [c,ceq] = unitdisk(x)
c = x(1)^2 + x(2)^2 - 1;
ceq = [];

Create the remaining problem specifications.

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
nonlcon = @unitdisk;
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
x0 = [0,0];

Call fmincon using the fval, exitflag, and output outputs.

[x,fval,exitflag,output] = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.


x =

    0.7864    0.6177


fval =

    0.0457


exitflag =

     1


output = 

  struct with fields:

         iterations: 24
          funcCount: 84
    constrviolation: 0
           stepsize: 6.9162e-06
          algorithm: 'interior-point'
      firstorderopt: 2.4373e-08
       cgiterations: 4
            message: 'Local minimum found that satisfies the constraints.↵↵Optimization completed because the objective function is non-decreasing in ↵feasible directions, to within the value of the optimality tolerance,↵and constraints are satisfied to within the value of the constraint tolerance.↵↵<stopping criteria details>↵↵Optimization completed: The relative first-order optimality measure, 2.437331e-08,↵is less than options.OptimalityTolerance = 1.000000e-06, and the relative maximum constraint↵violation, 0.000000e+00, is less than options.ConstraintTolerance = 1.000000e-06.'
       bestfeasible: [1×1 struct]

  • The exitflag value 1 indicates that the solution is a local minimum.

  • The output structure reports several statistics about the solution process. In particular, it gives the number of iterations in output.iterations, number of function evaluations in output.funcCount, and the feasibility in output.constrviolation.

Open Script

fmincon optionally returns several outputs that you can use for analyzing the reported solution.

Set up the problem of minimizing Rosenbrock's function on the unit disk. First create a function that represents the nonlinear constraint. Save this as a file named unitdisk.m on your MATLAB® path.

function [c,ceq] = unitdisk(x)
c = x(1)^2 + x(2)^2 - 1;
ceq = [];

Create the remaining problem specifications.

fun = @(x)100*(x(2)-x(1)^2)^2 + (1-x(1))^2;
nonlcon = @unitdisk;
A = [];
b = [];
Aeq = [];
beq = [];
lb = [];
ub = [];
x0 = [0,0];

Request all fmincon outputs.

[x,fval,exitflag,output,lambda,grad,hessian] = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon)

Local minimum found that satisfies the constraints.

Optimization completed because the objective function is non-decreasing in 
feasible directions, to within the value of the optimality tolerance,
and constraints are satisfied to within the value of the constraint tolerance.


x =

    0.7864    0.6177


fval =

    0.0457


exitflag =

     1


output = 

  struct with fields:

         iterations: 24
          funcCount: 84
    constrviolation: 0
           stepsize: 6.9162e-06
          algorithm: 'interior-point'
      firstorderopt: 2.4373e-08
       cgiterations: 4
            message: 'Local minimum found that satisfies the constraints.↵↵Optimization completed because the objective function is non-decreasing in ↵feasible directions, to within the value of the optimality tolerance,↵and constraints are satisfied to within the value of the constraint tolerance.↵↵<stopping criteria details>↵↵Optimization completed: The relative first-order optimality measure, 2.437331e-08,↵is less than options.OptimalityTolerance = 1.000000e-06, and the relative maximum constraint↵violation, 0.000000e+00, is less than options.ConstraintTolerance = 1.000000e-06.'
       bestfeasible: [1×1 struct]


lambda = 

  struct with fields:

         eqlin: [0×1 double]
      eqnonlin: [0×1 double]
       ineqlin: [0×1 double]
         lower: [2×1 double]
         upper: [2×1 double]
    ineqnonlin: 0.1215


grad =

   -0.1911
   -0.1501


hessian =

  497.2903 -314.5589
 -314.5589  200.2392

  • The lambda.ineqnonlin output shows that the nonlinear constraint is active at the solution, and gives the value of the associated Lagrange multiplier.

  • The grad output gives the value of the gradient of the objective function at the solution x.

  • The hessian output is described in fmincon Hessian.

Input Arguments

collapse all

Function to minimize, specified as a function handle or function name. fun is a function that accepts a vector or array x and returns a real scalar f, the objective function evaluated at x.

fmincon passes x to your objective function and any nonlinear constraint functions in the shape of the x0 argument. For example, if x0 is a 5-by-3 array, then fmincon passes x to fun as a 5-by-3 array. However, fmincon multiplies linear constraint matrices A or Aeq with x after converting x to the column vector x(:).

Specify fun as a function handle for a file:

x = fmincon(@myfun,x0,A,b)

where myfun is a MATLAB® function such as

function f = myfun(x)
f = ...            % Compute function value at x

You can also specify fun as a function handle for an anonymous function:

x = fmincon(@(x)norm(x)^2,x0,A,b);

If you can compute the gradient of fun and the SpecifyObjectiveGradient option is set to true, as set by

options = optimoptions('fmincon','SpecifyObjectiveGradient',true)
then fun must return the gradient vector g(x) in the second output argument.

If you can also compute the Hessian matrix and the HessianFcn option is set to 'objective' via optimoptions and the Algorithm option is 'trust-region-reflective', fun must return the Hessian value H(x), a symmetric matrix, in a third output argument. fun can give a sparse Hessian. See Hessian for fminunc trust-region or fmincon trust-region-reflective algorithms for details.

If you can also compute the Hessian matrix and the Algorithm option is set to 'interior-point', there is a different way to pass the Hessian to fmincon. For more information, see Hessian for fmincon interior-point algorithm. For an example using Symbolic Math Toolbox™ to compute the gradient and Hessian, see Calculate Gradients and Hessians Using Symbolic Math Toolbox.

The interior-point and trust-region-reflective algorithms allow you to supply a Hessian multiply function. This function gives the result of a Hessian-times-vector product without computing the Hessian directly. This can save memory. See Hessian Multiply Function.

Example: fun = @(x)sin(x(1))*cos(x(2))

Data Types: char | function_handle | string

Initial point, specified as a real vector or real array. Solvers use the number of elements in, and size of, x0 to determine the number and size of variables that fun accepts.

  • 'interior-point' algorithm — If the HonorBounds option is true (default), fmincon resets x0 components that are on or outside bounds lb or ub to values strictly between the bounds.

  • 'trust-region-reflective' algorithm — fmincon resets infeasible x0 components to be feasible with respect to bounds or linear equalities.

  • 'sqp', 'sqp-legacy', or 'active-set' algorithm — fmincon resets x0 components that are outside bounds to the values of the corresponding bounds.

Example: x0 = [1,2,3,4]

Data Types: double

Linear inequality constraints, specified as a real matrix. A is an M-by-N matrix, where M is the number of inequalities, and N is the number of variables (number of elements in x0). For large problems with algorithms that support sparse data, pass A as a sparse matrix. See Sparsity in Optimization Algorithms.

A encodes the M linear inequalities

A*x <= b,

where x is the column vector of N variables x(:), and b is a column vector with M elements.

For example, consider these inequalities:

x1 + 2x2 ≤ 10
3x1 + 4x2 ≤ 20
5x1 + 6x2 ≤ 30,

Specify the inequalities by entering the following constraints.

A = [1,2;3,4;5,6];
b = [10;20;30];

Example: To specify that the x components sum to 1 or less, use A = ones(1,N) and b = 1.

Data Types: single | double

Linear inequality constraints, specified as a real vector. b is an M-element vector related to the A matrix. If you pass b as a row vector, solvers internally convert b to the column vector b(:).

b encodes the M linear inequalities

A*x <= b,

where x is the column vector of N variables x(:), and A is a matrix of size M-by-N.

For example, consider these inequalities:

x1 + 2x2 ≤ 10
3x1 + 4x2 ≤ 20
5x1 + 6x2 ≤ 30.

Specify the inequalities by entering the following constraints.

A = [1,2;3,4;5,6];
b = [10;20;30];

Example: To specify that the x components sum to 1 or less, use A = ones(1,N) and b = 1.

Data Types: single | double

Linear equality constraints, specified as a real matrix. Aeq is an Me-by-N matrix, where Me is the number of equalities, and N is the number of variables (number of elements in x0). For large problems with algorithms that support sparse data, pass A as a sparse matrix. See Sparsity in Optimization Algorithms.

Aeq encodes the Me linear equalities

Aeq*x = beq,

where x is the column vector of N variables x(:), and beq is a column vector with Me elements.

For example, consider these inequalities:

x1 + 2x2 + 3x3 = 10
2x1 + 4x2 + x3 = 20,

Specify the inequalities by entering the following constraints.

Aeq = [1,2,3;2,4,1];
beq = [10;20];

Example: To specify that the x components sum to 1, use Aeq = ones(1,N) and beq = 1.

Data Types: single | double

Linear equality constraints, specified as a real vector. beq is an Me-element vector related to the Aeq matrix. If you pass beq as a row vector, solvers internally convert beq to the column vector beq(:).

beq encodes the Me linear equalities

Aeq*x = beq,

where x is the column vector of N variables x(:), and Aeq is a matrix of size Me-by-N.

For example, consider these equalities:

x1 + 2x2 + 3x3 = 10
2x1 + 4x2 + x3 = 20.

Specify the equalities by entering the following constraints.

Aeq = [1,2,3;2,4,1];
beq = [10;20];

Example: To specify that the x components sum to 1, use Aeq = ones(1,N) and beq = 1.

Data Types: single | double

Lower bounds, specified as a real vector or real array. If the number of elements in x0 is equal to the number of elements in lb, then lb specifies that

x(i) >= lb(i) for all i.

If numel(lb) < numel(x0), then lb specifies that

x(i) >= lb(i) for 1 <= i <= numel(lb).

If lb has fewer elements than x0, solvers issue a warning.

Example: To specify that all x components are positive, use lb = zeros(size(x0)).

Data Types: single | double

Upper bounds, specified as a real vector or real array. If the number of elements in x0 is equal to the number of elements in ub, then ub specifies that

x(i) <= ub(i) for all i.

If numel(ub) < numel(x0), then ub specifies that

x(i) <= ub(i) for 1 <= i <= numel(ub).

If ub has fewer elements than x0, solvers issue a warning.

Example: To specify that all x components are less than 1, use ub = ones(size(x0)).

Data Types: single | double

Nonlinear constraints, specified as a function handle or function name. nonlcon is a function that accepts a vector or array x and returns two arrays, c(x) and ceq(x).

  • c(x) is the array of nonlinear inequality constraints at x. fmincon attempts to satisfy

    c(x) <= 0 for all entries of c.

  • ceq(x) is the array of nonlinear equality constraints at x. fmincon attempts to satisfy

    ceq(x) = 0 for all entries of ceq.

For example,

x = fmincon(@myfun,x0,A,b,Aeq,beq,lb,ub,@mycon)

where mycon is a MATLAB function such as

function [c,ceq] = mycon(x)
c = ...     % Compute nonlinear inequalities at x.
ceq = ...   % Compute nonlinear equalities at x.
If the gradients of the constraints can also be computed and the SpecifyConstraintGradient option is true, as set by
options = optimoptions('fmincon',SpecifyConstraintGradient=true)
then nonlcon must also return, in the third and fourth output arguments, GC, the gradient of c(x), and GCeq, the gradient of ceq(x). GC and GCeq can be sparse or dense. If GC or GCeq is large, with relatively few nonzero entries, save running time and memory in the interior-point algorithm by representing them as sparse matrices. For more information, see Nonlinear Constraints.

Note

Setting SpecifyConstraintGradient to true is effective only when SpecifyObjectiveGradient is set to true. Internally, the objective is folded into the constraint, so the solver needs both gradients (objective and constraint) supplied in order to avoid estimating a gradient.

Note

Because Optimization Toolbox™ functions accept only inputs of type double, user-supplied objective and nonlinear constraint functions must return outputs of type double.

Data Types: char | function_handle | string

Optimization options, specified as the output of optimoptions or a structure such as optimset returns.

Some options apply to all algorithms, and others are relevant for particular algorithms. See Optimization Options Reference for detailed information.

Some options are absent from the optimoptions display. These options appear in italics in the following table. For details, see View Optimization Options.

All Algorithms
Algorithm

Choose the optimization algorithm:

  • 'interior-point' (default)

  • 'trust-region-reflective'

  • 'sqp'

  • 'sqp-legacy' (optimoptions only)

  • 'active-set'

For information on choosing the algorithm, see Choosing the Algorithm.

The trust-region-reflective algorithm requires:

  • A gradient to be supplied in the objective function

  • SpecifyObjectiveGradient to be set to true

  • Either bound constraints or linear equality constraints, but not both

If you select the 'trust-region-reflective' algorithm and these conditions are not all satisfied, fmincon throws an error.

The 'active-set', 'sqp-legacy', and 'sqp' algorithms cannot use sparse data. See Sparsity in Optimization Algorithms.

CheckGradients

Compare user-supplied derivatives (gradients of objective or constraints) to finite-differencing derivatives. Choices are false (default) or true.

For optimset, the name is DerivativeCheck and the values are 'on' or 'off'. See Current and Legacy Option Names.

The CheckGradients option will be removed in a future release. To check derivatives, use the checkGradients function.

ConstraintTolerance

Tolerance on the constraint violation, a nonnegative scalar. The default is 1e-6. See Tolerances and Stopping Criteria.

For optimset, the name is TolCon. See Current and Legacy Option Names.

Diagnostics

Display diagnostic information about the function to be minimized or solved. Choices are 'off' (default) or 'on'.

DiffMaxChange

Maximum change in variables for finite-difference gradients (a positive scalar). The default is Inf.

DiffMinChange

Minimum change in variables for finite-difference gradients (a positive scalar). The default is 0.

Display

Level of display (see Iterative Display):

  • 'off' or 'none' 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' (default) displays only the final output, and gives the default exit message.

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

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);

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

For optimset, the name is FinDiffRelStep. See Current and Legacy Option Names.

FiniteDifferenceType

Finite differences, used to estimate gradients, are either 'forward' (default), or 'central' (centered). 'central' takes twice as many function evaluations but should be more accurate. The trust-region-reflective algorithm uses FiniteDifferenceType only when CheckGradients is set to true.

fmincon is careful to obey bounds when estimating both types of finite differences. So, for example, it could take a backward, rather than a forward, difference to avoid evaluating at a point outside bounds. However, for the interior-point algorithm, 'central' differences might violate bounds during their evaluation if the HonorBounds option is set to false.

For optimset, the name is FinDiffType. See Current and Legacy Option Names.

FunValCheck

Check whether objective function values are valid. The default setting, 'off', does not perform a check. The 'on' setting displays an error when the objective function returns a value that is complex, Inf, or NaN.

MaxFunctionEvaluations

Maximum number of function evaluations allowed, a nonnegative integer. The default value for all algorithms except interior-point is 100*numberOfVariables; for the interior-point algorithm the default is 3000. See Tolerances and Stopping Criteria and Iterations and Function Counts.

For optimset, the name is MaxFunEvals. See Current and Legacy Option Names.

MaxIterations

Maximum number of iterations allowed, a nonnegative integer. The default value for all algorithms except interior-point is 400; for the interior-point algorithm the default is 1000. See Tolerances and Stopping Criteria and Iterations and Function Counts.

For optimset, the name is MaxIter. See Current and Legacy Option Names.

OptimalityTolerance

Termination tolerance on the first-order optimality (a nonnegative scalar). The default is 1e-6. See First-Order Optimality Measure.

For optimset, the name is TolFun. See Current and Legacy Option Names.

OutputFcn

Specify one or more user-defined functions that an optimization function calls at each iteration. Pass a function handle or a cell array of function handles. The default is none ([]). See Output Function and Plot Function Syntax.

PlotFcn

Plots various measures of progress while the algorithm executes; select from predefined plots or write your own. Pass a built-in plot function name, a function handle, or a cell array of built-in plot function names or function handles. For custom plot functions, pass function handles. The default is none ([]):

  • '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 of 1e-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.

  • 'optimplotstepsize' plots the step size.

  • 'optimplotfirstorderopt' plots the first-order optimality measure.

Custom plot functions use the same syntax as output functions. See Output Functions for Optimization Toolbox and Output Function and Plot Function Syntax.

For optimset, the name is PlotFcns. See Current and Legacy Option Names.

SpecifyConstraintGradient

Gradient for nonlinear constraint functions defined by the user. When set to the default, false, fmincon estimates gradients of the nonlinear constraints by finite differences. When set to true, fmincon expects the constraint function to have four outputs, as described in nonlcon. The trust-region-reflective algorithm does not accept nonlinear constraints.

For optimset, the name is GradConstr and the values are 'on' or 'off'. See Current and Legacy Option Names.

SpecifyObjectiveGradient

Gradient for the objective function defined by the user. See the description of fun to see how to define the gradient in fun. The default, false, causes fmincon to estimate gradients using finite differences. Set to true to have fmincon use a user-defined gradient of the objective function. To use the 'trust-region-reflective' algorithm, you must provide the gradient, and set SpecifyObjectiveGradient to true.

For optimset, the name is GradObj and the values are 'on' or 'off'. See Current and Legacy Option Names.

StepTolerance

Termination tolerance on x, a nonnegative scalar. The default value for all algorithms except 'interior-point' is 1e-6; for the 'interior-point' algorithm, the default is 1e-10. See Tolerances and Stopping Criteria.

For optimset, the name is TolX. See Current and Legacy Option Names.

TypicalX

Typical x values. The number of elements in TypicalX is equal to the number of elements in x0, the starting point. The default value is ones(numberofvariables,1). fmincon uses TypicalX for scaling finite differences for gradient estimation.

The 'trust-region-reflective' algorithm uses TypicalX only for the CheckGradients option.

UseParallel

When true, fmincon estimates gradients in parallel. Disable by setting to the default, false. trust-region-reflective requires a gradient in the objective, so UseParallel does not apply. See Parallel Computing.

Trust-Region-Reflective Algorithm
FunctionTolerance

Termination tolerance on the function value, a nonnegative scalar. The default is 1e-6. See Tolerances and Stopping Criteria.

For optimset, the name is TolFun. See Current and Legacy Option Names.

HessianFcn

If [] (default), fmincon approximates the Hessian using finite differences, or uses a Hessian multiply function (with option HessianMultiplyFcn). If 'objective', fmincon uses a user-defined Hessian (defined in fun). See Hessian as an Input.

For optimset, the name is HessFcn. See Current and Legacy Option Names.

HessianMultiplyFcn

Hessian multiply function, specified as a function handle. For large-scale structured problems, this function computes the Hessian matrix product H*Y without actually forming H. The function is of the form

W = hmfun(Hinfo,Y)

where Hinfo contains a matrix used to compute H*Y.

The first argument is the same as the third argument returned by the objective function fun, for example

[f,g,Hinfo] = fun(x)

Y is a matrix that has the same number of rows as there are dimensions in the problem. The matrix W = H*Y, although H is not formed explicitly. fmincon uses Hinfo to compute the preconditioner. For information on how to supply values for any additional parameters hmfun needs, see Passing Extra Parameters.

Note

To use the HessianMultiplyFcn option, HessianFcn must be set to [], and SubproblemAlgorithm must be 'cg' (default).

See Hessian Multiply Function. See Minimization with Dense Structured Hessian, Linear Equalities for an example.

For optimset, the name is HessMult. See Current and Legacy Option Names.

HessPattern

Sparsity pattern of the Hessian for finite differencing. Set HessPattern(i,j) = 1 when you can have ∂2fun/∂x(i)∂x(j) ≠ 0. Otherwise, set HessPattern(i,j) = 0.

Use HessPattern when it is inconvenient to compute the Hessian matrix H in fun, but you can determine (say, by inspection) when the ith component of the gradient of fun depends on x(j). fmincon can approximate H via sparse finite differences (of the gradient) if you provide the sparsity structure of H as the value for HessPattern. In other words, provide the locations of the nonzeros.

When the structure is unknown, do not set HessPattern. The default behavior is as if HessPattern is a dense matrix of ones. Then fmincon computes a full finite-difference approximation in each iteration. This computation can be very expensive for large problems, so it is usually better to determine the sparsity structure.

MaxPCGIter

Maximum number of preconditioned conjugate gradient (PCG) iterations, a positive scalar. The default is max(1,floor(numberOfVariables/2)) for bound-constrained problems, and is numberOfVariables for equality-constrained problems. For more information, see Preconditioned Conjugate Gradient Method.

PrecondBandWidth

Upper bandwidth of preconditioner for PCG, a nonnegative integer. By default, diagonal preconditioning is used (upper bandwidth of 0). For some problems, increasing the bandwidth reduces the number of PCG iterations. Setting PrecondBandWidth to Inf uses a direct factorization (Cholesky) rather than the conjugate gradients (CG). The direct factorization is computationally more expensive than CG, but produces a better quality step towards the solution.

SubproblemAlgorithm

Determines how the iteration step is calculated. The default, 'cg', takes a faster but less accurate step than 'factorization'. See fmincon Trust Region Reflective Algorithm.

For optimset, you cannot set a nondefault value. To use 'factorization', set options using optimoptions.

TolPCG

Termination tolerance on the PCG iteration, a positive scalar. The default is 0.1.

Active-Set Algorithm
FunctionTolerance

Termination tolerance on the function value, a nonnegative scalar. The default is 1e-6. See Tolerances and Stopping Criteria.

For optimset, the name is TolFun. See Current and Legacy Option Names.

MaxSQPIter

Maximum number of SQP iterations allowed, a positive integer. The default is 10*max(numberOfVariables, numberOfInequalities + numberOfBounds).

RelLineSrchBnd

Relative bound (a real nonnegative scalar value) on the line search step length. The total displacement in x satisfies |Δx(i)| ≤ relLineSrchBnd· max(|x(i)|,|typicalx(i)|). This option provides control over the magnitude of the displacements in x for cases in which the solver takes steps that are considered too large. The default is no bounds ([]).

RelLineSrchBndDuration

Number of iterations for which the bound specified in RelLineSrchBnd should be active (default is 1).

TolConSQP

Termination tolerance on inner iteration SQP constraint violation, a positive scalar. The default is 1e-6.

Interior-Point Algorithm
BarrierParamUpdate

Specifies how fmincon updates the barrier parameter (see fmincon Interior Point Algorithm). The options are:

  • 'monotone' (default)

  • 'predictor-corrector'

This option can affect the speed and convergence of the solver, but the effect is not easy to predict.

EnableFeasibilityMode

When true, fmincon uses a different algorithm for achieving feasibility. This setting can help fmincon reach a feasible solution in some cases. The default value is false.

Feasibility mode usually performs better when SubproblemAlgorithm is 'cg'. For details, see Feasibility Mode. For an example, see Obtain Solution Using Feasibility Mode.

HessianApproximation

Specifies how fmincon calculates the Hessian (see Hessian as an Input). The choices are:

  • 'bfgs' (default)

  • 'finite-difference'

  • 'lbfgs'

  • {'lbfgs',Positive Integer}

Note

To use HessianApproximation, both HessianFcn and HessianMultiplyFcn must be empty entries ([]).

For optimset, the name is Hessian and the values are 'user-supplied', 'bfgs', 'lbfgs', 'fin-diff-grads', 'on', or 'off'. See Current and Legacy Option Names.

HessianFcn

If [] (default), fmincon approximates the Hessian using the method specified in HessianApproximation, or uses a supplied HessianMultiplyFcn. If a function handle, fmincon uses HessianFcn to calculate the Hessian. See Hessian as an Input.

For optimset, the name is HessFcn. See Current and Legacy Option Names.

HessianMultiplyFcn

User-supplied function that gives a Hessian-times-vector product (see Hessian Multiply Function). Pass a function handle.

Note

To use the HessianMultiplyFcn option, HessianFcn must be set to [], and SubproblemAlgorithm must be 'cg'.

For optimset, the name is HessMult. See Current and Legacy Option Names.

HonorBounds

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

For optimset, the name is AlwaysHonorConstraints and the values are 'bounds' or 'none'. See Current and Legacy Option Names.

InitBarrierParam

Initial barrier value, a positive scalar. Sometimes it might help to try a value above the default 0.1, especially if the objective or constraint functions are large.

InitTrustRegionRadius

Initial radius of the trust region, a positive scalar. On badly scaled problems it might help to choose a value smaller than the default n, where n is the number of variables.

MaxProjCGIter

A tolerance (stopping criterion) for the number of projected conjugate gradient iterations; this is an inner iteration, not the number of iterations of the algorithm. This positive integer has a default value of 2*(numberOfVariables - numberOfEqualities).

ObjectiveLimit

A tolerance (stopping criterion) that is a scalar. If the objective function value goes below ObjectiveLimit and the iterate is feasible, the iterations halt, because the problem is presumably unbounded. The default value is -1e20.

ScaleProblem

true causes the algorithm to normalize all constraints and the objective function. Disable by setting to the default false.

For optimset, the values are 'obj-and-constr' or 'none'. See Current and Legacy Option Names.

SubproblemAlgorithm

Determines how the iteration step is calculated. The default, 'factorization', is usually faster than 'cg' (conjugate gradient), though 'cg' might be faster for large problems with dense Hessians. See fmincon Interior Point Algorithm.

For optimset, the values are 'cg' and 'ldl-factorization'. See Current and Legacy Option Names.

TolProjCG

A relative tolerance (stopping criterion) for projected conjugate gradient algorithm; this is for an inner iteration, not the algorithm iteration. This positive scalar has a default of 0.01.

TolProjCGAbs

Absolute tolerance (stopping criterion) for projected conjugate gradient algorithm; this is for an inner iteration, not the algorithm iteration. This positive scalar has a default of 1e-10.

SQP and SQP Legacy Algorithms
ObjectiveLimit

A tolerance (stopping criterion) that is a scalar. If the objective function value goes below ObjectiveLimit and the iterate is feasible, the iterations halt, because the problem is presumably unbounded. The default value is -1e20.

ScaleProblem

true causes the algorithm to normalize all constraints and the objective function. Disable by setting to the default false.

For optimset, the values are 'obj-and-constr' or 'none'. See Current and Legacy Option Names.

UseCodegenSolver

Indication to use the version of the software that runs on target hardware, specified as true or the default false. Use this option for testing code in the desktop environment prior to generating code. You can pass this option when generating code, but it has no effect on code generation.

Single-Precision Code Generation
Algorithm

Must be 'sqp' or 'sqp-legacy'.

ConstraintTolerance

Tolerance on the constraint violation, a nonnegative scalar. The default is 1e-3. See Tolerances and Stopping Criteria.

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);(1)
where sign′(x) = sign(x) except sign′(0) = 1. Central finite differences are
delta = v.*max(abs(x),TypicalX);(2)
A scalar FiniteDifferenceStepSize expands to a vector. The default is sqrt(eps('single')) for forward finite differences, and eps('single')^(1/3) for central finite differences.

FiniteDifferenceType

Finite differences, used to estimate gradients, are either 'forward' (default), or 'central' (centered). 'central' takes twice as many function evaluations but should be more accurate.

fmincon is careful to obey bounds when estimating both types of finite differences. So, for example, it could take a backward, rather than a forward, difference to avoid evaluating at a point outside bounds.

MaxFunctionEvaluations

Maximum number of function evaluations allowed, a nonnegative integer. The default value is 100*numberOfVariables. See Tolerances and Stopping Criteria and Iterations and Function Counts.

MaxIterations

Maximum number of iterations allowed, a nonnegative integer. The default value is 400. See Tolerances and Stopping Criteria and Iterations and Function Counts.

ObjectiveLimit

A tolerance (stopping criterion) that is a scalar. If the objective function value goes below ObjectiveLimit and the iterate is feasible, the iterations halt, because the problem is presumably unbounded. The default value is -1e20.

OptimalityTolerance

Termination tolerance on the first-order optimality (a nonnegative scalar). The default is 1e-3. See First-Order Optimality Measure.

ScaleProblem

true causes the algorithm to normalize all constraints and the objective function. Disable by setting to the default false.

SpecifyConstraintGradient

Gradient for nonlinear constraint functions defined by the user. When set to the default, false, fmincon estimates gradients of the nonlinear constraints by finite differences. When set to true, fmincon expects the constraint function to have four outputs, as described in nonlcon.

SpecifyObjectiveGradient

Gradient for the objective function defined by the user. See the description of fun to see how to define the gradient in fun. The default, false, causes fmincon to estimate gradients using finite differences. Set to true to have fmincon use a user-defined gradient of the objective function.

StepTolerance

Termination tolerance on x, a nonnegative scalar. The default value is 1e-4. See Tolerances and Stopping Criteria.

TypicalX

Typical x values. The number of elements in TypicalX is equal to the number of elements in x0, the starting point. The default value is ones(numberofvariables,1). fmincon uses TypicalX for scaling finite differences for gradient estimation.

UseCodegenSolver

Indication to use the version of the software that runs on target hardware, specified as true or the default false. Use this option for testing code in the desktop environment prior to generating code. You can pass this option when generating code, but it has no effect on code generation.

Example: options = optimoptions('fmincon','SpecifyObjectiveGradient',true,'SpecifyConstraintGradient',true)

Problem structure, specified as a structure with the following fields:

Field NameEntry

objective

Objective function

x0

Initial point for x

Aineq

Matrix for linear inequality constraints

bineq

Vector for linear inequality constraints

Aeq

Matrix for linear equality constraints

beq

Vector for linear equality constraints
lbVector of lower bounds
ubVector of upper bounds

nonlcon

Nonlinear constraint function

solver

'fmincon'

options

Options created with optimoptions

You must supply at least the objective, x0, solver, and options fields in the problem structure.

Data Types: struct

Output Arguments

collapse all

Solution, returned as a real vector or real array. The size of x is the same as the size of x0. Typically, x is a local solution to the problem when exitflag is positive. For information on the quality of the solution, see When the Solver Succeeds.

Objective function value at the solution, returned as a real number. Generally, fval = fun(x).

Reason fmincon stopped, returned as an integer.

All Algorithms:

1

First-order optimality measure was less than options.OptimalityTolerance, and maximum constraint violation was less than options.ConstraintTolerance.

0

Number of iterations exceeded options.MaxIterations or number of function evaluations exceeded options.MaxFunctionEvaluations.

-1

Stopped by an output function or plot function.

-2

No feasible point was found.

All algorithms except active-set:

2

Change in x was less than options.StepTolerance and maximum constraint violation was less than options.ConstraintTolerance.

trust-region-reflective algorithm only:

3

Change in the objective function value was less than options.FunctionTolerance and maximum constraint violation was less than options.ConstraintTolerance.

active-set algorithm only:

4

Magnitude of the search direction was less than 2*options.StepTolerance and maximum constraint violation was less than options.ConstraintTolerance.

5

Magnitude of directional derivative in search direction was less than 2*options.OptimalityTolerance and maximum constraint violation was less than options.ConstraintTolerance.

interior-point, sqp-legacy, and sqp algorithms:

-3

Objective function at current iteration went below options.ObjectiveLimit and maximum constraint violation was less than options.ConstraintTolerance.

Information about the optimization process, returned as a structure with fields:

iterations

Number of iterations taken

funcCount

Number of function evaluations

lssteplength

Size of line search step relative to search direction (active-set and sqp algorithms only)

constrviolation

Maximum of constraint functions

stepsize

Length of last displacement in x (not in active-set algorithm)

algorithm

Optimization algorithm used

cgiterations

Total number of PCG iterations (trust-region-reflective and interior-point algorithms)

firstorderopt

Measure of first-order optimality

bestfeasible

Best (lowest objective function) feasible point encountered at the ends of the iterations. A structure with these fields:

  • x

  • fval

  • firstorderopt

  • constrviolation

If no feasible point is found, the bestfeasible field is empty. For this purpose, a point is feasible when the maximum of the constraint functions does not exceed options.ConstraintTolerance.

The bestfeasible point can differ from the returned solution point x for a variety of reasons. For an example, see Obtain Best Feasible Point.

message

Exit message

Lagrange multipliers at the solution, returned as a structure with fields:

lower

Lower bounds corresponding to lb

upper

Upper bounds corresponding to ub

ineqlin

Linear inequalities corresponding to A and b

eqlin

Linear equalities corresponding to Aeq and beq

ineqnonlin

Nonlinear inequalities corresponding to the c in nonlcon

eqnonlin

Nonlinear equalities corresponding to the ceq in nonlcon

Gradient at the solution, returned as a real vector. grad gives the gradient of fun at the point x(:).

Approximate Hessian, returned as a real matrix. For the meaning of hessian, see Hessian Output.

Limitations

  • fmincon is a gradient-based method that is designed to work on problems where the objective and constraint functions are both continuous and have continuous first derivatives.

  • For the 'trust-region-reflective' algorithm, you must provide the gradient in fun and set the 'SpecifyObjectiveGradient' option to true.

  • The 'trust-region-reflective' algorithm does not allow equal upper and lower bounds. For example, if lb(2)==ub(2), fmincon gives this error:

    Equal upper and lower bounds not permitted in trust-region-reflective algorithm. Use
either interior-point or SQP algorithms instead.

  • There are two different syntaxes for passing a Hessian, and there are two different syntaxes for passing a HessianMultiplyFcn function; one for trust-region-reflective, and another for interior-point. See Including Hessians.

    • For trust-region-reflective, the Hessian of the Lagrangian is the same as the Hessian of the objective function. You pass that Hessian as the third output of the objective function.

    • For interior-point, the Hessian of the Lagrangian involves the Lagrange multipliers and the Hessians of the nonlinear constraint functions. You pass the Hessian as a separate function that takes into account both the current point x and the Lagrange multiplier structure lambda.

  • When the problem is infeasible, fmincon attempts to minimize the maximum constraint value.

More About

collapse all

Algorithms

collapse all

Alternative Functionality

App

The Optimize Live Editor task provides a visual interface for fmincon.

References

[1] Byrd, R. H., J. C. Gilbert, and J. Nocedal. “A Trust Region Method Based on Interior Point Techniques for Nonlinear Programming.” Mathematical Programming, Vol 89, No. 1, 2000, pp. 149–185.

[2] Byrd, R. H., Mary E. Hribar, and Jorge Nocedal. “An Interior Point Algorithm for Large-Scale Nonlinear Programming.” SIAM Journal on Optimization, Vol 9, No. 4, 1999, pp. 877–900.

[3] Coleman, T. F. and Y. Li. “An Interior, Trust Region Approach for Nonlinear Minimization Subject to Bounds.” SIAM Journal on Optimization, Vol. 6, 1996, pp. 418–445.

[4] Coleman, T. F. and Y. Li. “On the Convergence of Reflective Newton Methods for Large-Scale Nonlinear Minimization Subject to Bounds.” Mathematical Programming, Vol. 67, Number 2, 1994, pp. 189–224.

[5] Gill, P. E., W. Murray, and M. H. Wright. Practical Optimization, London, Academic Press, 1981.

[6] Han, S. P. “A Globally Convergent Method for Nonlinear Programming.” Journal of Optimization Theory and Applications, Vol. 22, 1977, pp. 297.

[7] Powell, M. J. D. “A Fast Algorithm for Nonlinearly Constrained Optimization Calculations.” Numerical Analysis, ed. G. A. Watson, Lecture Notes in Mathematics, Springer-Verlag, Vol. 630, 1978.

[8] Powell, M. J. D. “The Convergence of Variable Metric Methods For Nonlinearly Constrained Optimization Calculations.” Nonlinear Programming 3 (O. L. Mangasarian, R. R. Meyer, and S. M. Robinson, eds.), Academic Press, 1978.

[9] Waltz, R. A., J. L. Morales, J. Nocedal, and D. Orban. “An interior algorithm for nonlinear optimization that combines line search and trust region steps.” Mathematical Programming, Vol 107, No. 3, 2006, pp. 391–408.

Extended Capabilities

expand all

Version History

Introduced before R2006a

expand all

See Also

| | | |

Topics