Optimization Toolbox  Search Help Desk 
fmincon  Examples See Also 
Find the minimum of a constrained nonlinear multivariable function
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(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options,P1,P2, ...) [x,fval] = fmincon(...) [x,fval,exitflag] = fmincon(...) [x,fval,exitflag,output] = fmincon(...) [x,fval,exitflag,output,lambda] = fmincon(...) [x,fval,exitflag,output,lambda,grad] = fmincon(...) [x,fval,exitflag,output,lambda,grad,hessian] = fmincon(...)
Description
fmincon
finds the constrained minimum of a scalar function of several variables starting at an initial estimate. This is generally referred to as constrained nonlinear optimization or nonlinear programming.
x = fmincon(
fun,x0,A,b)
starts at x0
and finds a minimum x
to the function described in fun
subject to the linear inequalities A*x <= b
. x0
can be a scalar, vector, or matrix.
x = fmincon(
fun,x0,A,b,Aeq,beq)
minimizes fun
subject to the linear equalities Aeq*x = beq
as well as A*x <= b
. Set A=[]
and b=[]
if no inequalities exist.
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub)
defines a set of lower and upper bounds on the design variables, x
, so that the solution is always in the range lb <= x <= ub
. Set Aeq=[]
and beq=[]
if no equalities exist.
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.
Set lb=[]
and/or ub=[]
if no bounds exist.
x = fmincon(fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options)
minimizes with the optimization parameters specified in the structure options
.
x = fmincon(
fun,x0,A,b,Aeq,beq,lb,ub,nonlcon,options,P1,P2,...)
passes the problemdependent parameters P1
, P2
, etc., directly to the functions fun
and nonlcon
. Pass empty matrices as placeholders for A
, b
, Aeq
, beq
, lb
, ub
, nonlcon
, and options
if these arguments are not needed.
[x,fval] = fmincon(...)
returns the value of the objective function fun
at the solution x
.
[x,fval,exitflag] = fmincon(...)
returns a value exitflag
that describes the exit condition of fmincon
.
[x,fval,exitflag,output] = fmincon(...)
returns a structure output
with information about the optimization.
[x,fval,exitflag,output,lambda] = fmincon(...)
returns a structure lambda
whose fields contain the Lagrange multipliers at the solution x.
[x,fval,exitflag,output,lambda,grad] = fmincon(...)
returns the value of the gradient of fun
at the solution x
.
[x,fval,exitflag,output,lambda,grad,hessian] = fmincon(...)
returns the value of the Hessian of fun
at the solution x
.
Arguments
The arguments passed into the function are described in Table 11. The arguments returned by the function are described in Table 12. Details relevant tofmincon
are included below for fun
, nonlcon
, options
, exitflag
, lambda
, and output
.fun 
The function to be minimized. fun takes a vector x and returns a scalar value f of the objective function evaluated at x . You can specify fun to be an inline object. For example,
fun = inline('sin(x''*x)');Alternatively, fun can be a string containing the name of a function (an Mfile, a builtin function, or a MEXfile). If fun='myfun' then the Mfile function myfun.m would have the form
function f = myfun(x) f = ... % Compute function value at x 

If the gradient of fun can also be computed and options.GradObj is 'on' , as set by
options = optimset('GradObj','on')then the function fun must return, in the second output argument, the gradient value g , a vector, at x . Note that by checking the value of nargout the function can avoid computing g when fun is called with only one output argument (in the case where the optimization algorithm only needs the value of f but not g ):
function [f,g] = myfun(x) f = ... % compute the function value at x if nargout > 1 % fun called with two output arguments g = ... % compute the gradient evaluated at x end 
The gradient is the partial derivatives of f at the point x . That is, the i th component of g is the partial derivative of f with respect to the i th component of x .


If the Hessian matrix can also be computed and options.Hessian is 'on' , i.e., options = optimset('Hessian','on') , then the function fun must return the Hessian value H , a symmetric matrix, at x in a third output argument. Note that by checking the value of nargout we can avoid computing H when fun is called with only one or two output arguments (in the case where the optimization algorithm only needs the values of f and g but not H ):
function [f,g,H] = myfun(x) f = ... % Compute the objective function value at x if nargout > 1 % fun called with two output arguments g = ... % gradient of the function evaluated at x if nargout > 2 H = ... % Hessian evaluated at x endThe Hessian matrix is the second partial derivatives matrix of f at the point x . That is, the (i th,j th) component of H is the second partial derivative of f with respect to x _{i} and x _{j}, . The Hessian is by definition a symmetric matrix.


nonlcon 
The function that computes the nonlinear inequality constraints c(x)<=0 and nonlinear equality constraints ceq(x)=0 . nonlcon is a string containing the name of a function (an Mfile, a builtin, or a MEXfile). nonlcon takes a vector x and returns two arguments, a vector c of the nonlinear inequalities evaluated at x and a vector ceq of the nonlinear equalities evaluated at x . For example, if nonlcon='mycon' then the Mfile mycon.m would have the form
function [c,ceq] = mycon(x) c = ... % Compute nonlinear inequalities at x ceq = ... % Compute the nonlinear equalities at x 
If the gradients of the constraints can also be computed and options.GradConstr is 'on' , as set by
options = optimset('GradConstr','on')then the function nonlcon must also return, in the third and fourth output arguments, GC , the gradient of c(x) , and GCeq , the gradient of ceq(x) . Note that by checking the value of nargout the function can avoid computing GC and GCeq when nonlcon is called with only two output arguments (in the case where the optimization algorithm only needs the values of c and ceq but not GC and GCeq ):


function [c,ceq,GC,GCeq] = mycon(x) c = ... % nonlinear inequalities at x ceq = ... % nonlinear equalities at x if nargout > 2 % nonlcon called with 4 outputs GC = ... % gradients of the inequalities GCeq = ... % gradients of the equalities end 

If nonlcon returns a vector c of m components and x has length n , then the gradient GC of c(x) is an nbym matrix, where GC(i,j) is the partial derivative of c(j) with respect to x(i) (i.e., the j th column of GC is the gradient of the j th inequality constraint c(j) ). Likewise, if ceq has p components, the gradient GCeq of ceq(x) is an nbyp matrix, where GCeq(i,j) is the partial derivative of ceq(j) with respect to x(i) (i.e., the j th column of GCeq is the gradient of the j th equality constraint ceq(j) ).


options 
Optimization parameter options. You can set or change the values of these parameters using the optimset function. Some parameters apply to all algorithms, some are only relevant when using the largescale algorithm, and others are only relevant when using the mediumscale algorithm.
We start by describing the LargeScale option since it states a preference for which algorithm to use. It is only a preference since certain conditions must be met to use the largescale algorithm. For fmincon , the gradient must be provided (see the description of fun above to see how) or else the mediumscale algorithm will be used.

Parameters used by both the largescale and mediumscale algorithms:


Parameters used by the largescale algorithm only:




Parameters used by the mediumscale algorithm only:


exitflag 
Describes the exit condition: 
lambda 
A structure containing the Lagrange multipliers at the solution x (separated by constraint type):

output 
A structure whose fields contain information about the optimization:

Examples
Find values of x that minimize , starting at the pointx = [10; 10; 10]
and subject to the constraints
f
of the function evaluated at x
:
function f = myfun(x) f = x(1) * x(2) * x(3);Then rewrite the constraints as both less than or equal to a constant,
x0 = [10; 10; 10]; % Starting guess at the solution [x,fval] = fmincon('myfun',x0,A,b)After 66 function evaluations, the solution is
x = 24.0000 12.0000 12.0000where the function value is
fval = 3.4560e+03and linear inequality constraints evaluate to be
<= 0
A*xb= 72 0
Notes
Largescale optimization. To use the largescale method, the gradient must be provided infun
(and options.GradObj
set to 'on'
). A warning is given if no gradient is provided and options.LargeScale
is not 'off'
. fmincon
permits g(x) to be an approximate gradient but this option is not recommended: the numerical behavior of most optimization codes is considerably more robust when the true gradient is used.
The largescale method in fmincon
is most effective when the matrix of second derivatives, i.e., the Hessian matrix H(x), is also computed. However, evaluation of the true Hessian matrix is not required. For example, if you can supply the Hessian sparsity structure (using the HessPattern
parameter in options
), then fmincon
will compute a sparse finitedifference approximation to H(x).
If x0
is not strictly feasible, fmincon
chooses a new strictly feasible (centered) starting point.
If components of x have no upper (or lower) bounds, then fmincon
prefers that the corresponding components of ub
(or lb)
be set to Inf
(
or Inf
for lb)
as opposed to an arbitrary but very large positive (or negative in the case of lower bounds) number.
Several aspects of linearly constrained minimization should be noted:
Aeq
can result in considerable fill and computational cost.
fmincon
removes (numerically) linearly dependent rows in Aeq
; however, this process involves repeated matrix factorizations and therefore can be costly if there are many dependencies.
where R
T is the Cholesky factor of the preconditioner. Therefore, there is a potential conflict between choosing an effective preconditioner and minimizing fill in .
Aeq
and beq,
instead of implicitly using lb
and ub
.
If equality constraints are present and dependent equalities are detected and removed in the quadratic subproblem, 'dependent'
is printed under the Procedures
heading (when output is asked for using options.Display = 'iter')
. The dependent equalities are only removed when the equalities are consistent. If the system of equalities is not consistent, the subproblem is infeasible and 'infeasible'
is printed under the Procedures
heading.
Algorithm
Largescale optimization. By defaultfmincon
will choose the largescale algorithm if the user supplies the gradient in fun
(and GradObj
is 'on'
in options
) and if only upper and lower bounds exists or only linear equality constraints exist. This algorithm is a subspace trust region method and is based on the interiorreflective Newton method described in [5],[6]. Each iteration involves the approximate solution of a large linear system using the method of preconditioned conjugate gradients (PCG). See the trustregion and preconditioned conjugate gradient method descriptions in the LargeScale Algorithms chapter.
Mediumscale optimization.
fmincon
uses a Sequential Quadratic Programming (SQP) method. In this method, a Quadratic Programming (QP) subproblem is solved at each iteration. An estimate of the Hessian of the Lagrangian is updated at each iteration using the BFGS formula (see fminunc
, references [3, 6]).
A line search is performed using a merit function similar to that proposed by [1] and [2, 3]. The QP subproblem is solved using an active set strategy similar to that described in [4]. A full description of this algorithm is found in the "Constrained Optimization" section of the Introduction to Algorithms chapter of the toolbox manual.
See also the SQP implementation section in the Introduction to Algorithms chapter for more details on the algorithm used.
Diagnostics
Largescale optimization. The largescale code will not allow equal upper and lower bounds. For example iflb(2)==ub(2)
, then fmincon
gives the error:
Equal upper and lower bounds not permitted in this largescale method. Use equality constraints and the mediumscale method instead.If you only have equality constraints you can still use the largescale method. But if you have both equalities and bounds, you must use the mediumscale method.
Limitations
The function to be minimized and the constraints must both be continuous.fmincon
may only give local solutions.
When the problem is infeasible, fmincon
attempts to minimize the maximum constraint value.
The objective function and constraint function must be realvalued, that is they cannot return complex values.
Largescale optimization.
To use the largescale algorithm, the user must supply the gradient in fun
(and GradObj
must be set 'on'
in options
) , and only upper and lower bounds constraints may be specified, or only linear equality constraints must exist and Aeq
cannot have more rows than columns. Aeq
is typically sparse. See Table 14 for more information on what problem formulations are covered and what information must be provided.
Currently, if the analytical gradient is provided in fun
, the options
parameter DerivativeCheck
cannot be used with the largescale method to compare the analytic gradient to the finitedifference gradient. Instead, use the mediumscale method to check the derivative with options
parameter MaxIter
set to 0 iterations. Then run the problem with the largescale method.
References
[1] Han, S.P., "A Globally Convergent Method for Nonlinear Programming," Journal of Optimization Theory and Applications, Vol. 22, p. 297, 1977. [2] 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. [3] Powell, M.J.D., "A Fast Algorithm for Nonlineary Constrained Optimization Calculations," Numerical Analysis, ed. G.A. Watson, Lecture Notes in Mathematics, Springer Verlag, Vol. 630, 1978. [4] Gill, P.E., W. Murray, and M.H. Wright, Practical Optimization, Academic Press, London, 1981. [5] Coleman, T.F. and Y. Li, "On the Convergence of Reflective Newton Methods for LargeScale Nonlinear Minimization Subject to Bounds," Mathematical Programming, Vol. 67, Number 2, pp. 189224, 1994. [6] Coleman, T.F. and Y. Li, "An Interior, Trust Region Approach for Nonlinear Minimization Subject to Bounds," SIAM Journal on Optimization, Vol. 6, pp. 418445, 1996.See Also
fminbnd
, fminsearch
, fminunc
, optimset