fmincon

Find the constrained minimum of a real function.

Syntax

x = fmincon(@func,x0)

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

x = fmincon(@func,x0,A,b,Aeq,beq)

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

x = fmincon(@func,x0,A,b,Aeq,beq,lb,ub,nonlcon)

x = fmincon(@func,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)

[x,fval,info,output] = fmincon(...)

Inputs

func
The function to minimize. See the optimset option GradObj for details.
x0
An estimate of the location of the minimum.
A
A matrix used to compute A*x for inequality constraints.
Use [ ] if unneeded.
b
The upper bound of the inequality constraints A*x<=b.
Use [ ] if unneeded.
Aeq
A matrix used to compute Aeq*x for equality constraints.
Use [ ] if unneeded.
beq
The upper bound of the equality constraints Aeq*x=beq.
Use [ ] if unneeded.
lb
The design variable lower bounds.
Use [ ] if unbounded. Support for this option is limited. See Comments.
ub
The design variable upper bounds.
Use [ ] if unbounded. Support for this option is limited. See Comments.
nonlcon
The nonlinear constraints function.
The function signature is as follows: function [c, ceq, cj, ceqj] = ConFunc(x), where c and ceq contain inequality and equality constraints, respectively, and cj and ceqj contain their Jacobians. See the optimset option GradConstr.
The function can return 1, 2, or 4 outputs. Any required output that is unused should be set to [ ].
Inequality constraints are assumed to have upper bounds of 0, and equality constraints are equal to 0. For constraints of the form g(x) < b, where b ~= 0, the recommended best practice is to write the constraint as (g(x) - b) / abs(b) < 0.
Use [ ] if unused and the options argument is needed.
options
A struct containing option settings.
See optimset for details.

Outputs

x
The location of the function minimum.
fval
The minimum of the function.
info
The convergence status flag.
info = 3:
Converged with a constraint violation within TolCon.
info = 1
Function value converged to within TolX or TolKKT.
info = 0
Reached maximum number of iterations or function calls, or the algorithm aborted because it was not converging.
info = -2
The function did not converge.
output
A struct containing iteration details. The members are as follows:
iterations
The number of iterations.
nfev
The number of function evaluations.
xiter
The candidate solution at each iteration.
fvaliter
The objective function value at each iteration.
coniter
The constraint values at each iteration. The columns contain the constraint function values in the following order: linear inequality contraints, linear equality constraints, nonlinear inequality contraints, nonlinear equality constraints.

Examples

Minimize the function ObjFunc, subject to the linear inequality constraint: x1 + 4*x2 > 27.

The constraint must be expressed with an upper bound: -x1 - 4*x2 < -27.
function obj = ObjFunc(x)
    obj = 2*(x(1)-3)^2 - 5*(x(1)-3)*(x(2)-2) + 4*(x(2)-2)^2 + 6;
end

init = [8, 6];		% initial estimate
A = [-1, -4];		% inequality contraint matrix
b = [-27];		% inequality contraint bound
lb = [-10, -10];	% lower variable bounds
ub = [10, 10];		% upper variable bounds
[x,fval] = fmincon(@ObjFunc,init,A,b,[],[],lb,ub)
x = [Matrix] 1 x 2
7.00000  5.00000
fval = 14
Modify the previous example to pass an extra parameter to the objective function using a function handle.
function obj = ObjFunc(x,offset)
    obj = 2*(x(1)-3)^2 - 5*(x(1)-3)*(x(2)-2) + 4*(x(2)-2)^2 + offset;
end
handle = @(x) ObjFunc(x,7);
[x,fval] = fmincon(handle,init,A,b,[],[],lb,ub)
x = [Matrix] 1 x 2
7.00000  5.00000
fval = 15

Comments

By default, fmincon uses a Sequential Quadratic Programming (SQP) algorithm with a line search method. The optimset 'Method' option can be used to select a Generalized Reduced Gradient (GRG) algorithm. SQP is typically more efficient that GRG, but it permits infeasible iterations. GRG might be preferred when it is desirable for the convergence path to be feasible at each iteration, within a rounding error. The feasibile history property of GRG means that it does not suppprt equality constraints, as does SQP. The equality constraint inputs must be set to [] for GRG unless omitted.

Options for convergence tolerance controls and analytical derivatives are specified with optimset.

If large lb and ub values are specified with SQP, then it is essential to use option TolX in optimset. The default TolX is likely too large, since it is applied relative to the interval size.

When convergence occurs with an acceptable contraint violation using SQP, the next to last iteration might have a lower objetive value than the final iteration, but the final iteration might have the lower constraint violation of the two. The final iteration is reported as the solution, x. The value of TolCon affects the size of the potential difference between the choices.

For SQP, the unbounded lb and ub options are not fully supported due to their relationship to the TolX. The unbounded options are defaulted to -1000 and 1000, respectively.

To pass additional parameters to a function argument, use an anonymous function.

See the optimization tutorial for an example with nonlinear constraints.

The optimset options and defaults are as follows:

  • Method: 'sqp'
  • MaxIter: 400
  • MaxFunEvals: 1,000,000
  • MaxFail: 20,000
  • TolX: 1.0e-7
  • TolCon: 0.5%
  • TolKKT: 1.0e-7
  • GradObj: 'off'
  • GradConstr: 'off'
  • Display: 'off'

When convergence occurs with an acceptable contraint violation, the next to last iteration might have a lower objective value than the final iteration, but the final iteration might have the lower constraint violation of the two. The final iteration is reported as the solution, x. The value of TolCon affects the size of potential difference between the choices.