A. Basic Calls (without any special options)
Example1              Example 2
B. Calls with Gradients Supplied
Matlab's HELP DESCRIPTION

For constrained minimization of an objective function f(x) (for maximization use -f), Matlab provides the command fmincon. The objective function must be coded in a function file in the same manner as for fminunc. In these notes this file will be called objfun and saved as objfun.m  in the working directory.

A: Basic calls   top

Without any extra options, fmincon  is called as follows:

- with linear inequality constraints Ax£b only (as in linprog):
[x,fval]=fmincon('objfun',x0,A,b)

- with linear inequality constraints and linear equality constraints Aeq·x=beq only:
[x,fval]=fmincon('objfun',x0,A,b,Aeq,beq)

- with linear inequality and equality constraints, and in addition a lower bound of the form x³lb only:
[x,fval]=fmincon('objfun',x0,A,b,Aeq,beq,lb)
If only a subset of the variables has a lower bound, the components of lb corresponding to variables without lower bound are -Inf. For example, if the variables are (x,y), and x³1 but y has no lower bound, then lb=[1;-Inf].

- with linear inequality and equality constraints and lower as well as an upper bound of the form x£ub only:
[x,fval]=fmincon('objfun',x0,A,b,Aeq,beq,lb,ub)
If only a subset of the variables has an upper bound, the components of ub corresponding to variables without upper bound are Inf. For example, if the variables are (x,y) and x£1 but y has no lower bound, then lb=[1;Inf].

- with linear inequality and equality constraints,  lower and upper bounds, and nonlinear inequality and equality constraints:
[x,fval]=fmincon('objfun',x0,A,b,Aeq,beq,lb,ub,'constraint')
The last input argument in this call  is the name of a function file (denoted  constraint in these notes and saved as constraint.m  in the working directory), in which the nonlinear constraints are coded.

Constraint function file:
constraint.m is a function file (any name can be chosen) in which both the inequality functions  c(x) and the equality constraints ceq(x) are coded and provided in the form of column vectors. The function call

[c,ceq]=constraint(x)

must retrieve c(x) and ceq(x) for given input vector x. Examples of constraint function files are given in Examples 1 and 2 below. If only inequality constraints are given, define ceq=[]. Likewise, if only equality constraints are given, define c=[].

Interpretation:
The retrieved ceq(x) is interpreted by fmincon as equality constraint ceq(x)=0. The inequalities associated with c(x) are interpreted as c(x)£0. Thus, if a constraint of the form c(x)³0 is given, rewrite this as -c(x)£0 and code -c(x) in the constraint function file.

Placeholders:
As shown above, the constraints have to passed to fmincon in the following order:
1. Linear inequality constraints
2. Linear equality constraints
3. Lower bounds
4. Upper bounds
5. Nonlinear constraints
If a certain constraint is required, all other constraints appearing before it have to be inputted as well, even if they are not required in the problem. If this is the case, their input argument is replaced by the placeholder [] (empty input).

Examples:
- If lb and (A,b) are given, but there are no other constraints, the syntax is:
[x,fval]=fmincon('objfun',x0,A,b,[],[],lb)

- If ub and (Aeq,beq) are the only constraints:
[x,fval]=fmincon('objfun',x0,[],[],Aeq,beq,[],ub)

- If only nonlinear constraints are given:
[x,fval]=fmincon('objfun',x0,[],[],[],[],[],[],'constraint')
and function file constraint.m must be provided.
 

Example 1:    top

Find the minimum of

Solution: The objective function is coded as for unconstrained minimization:

function f=objfun(x)

f=x(1)^4-x(1)^2+x(2)^2-2*x(1)+x(2);

For (a), (b) we don't need a constraint function file. The calls are (assuming x0=[value1;value2] is already defined):
(a):   [x,fval]=fmincon('objfun',x0,[],[],[],[],[0;-Inf],[Inf;0])
(b):   [x,fval]=fmincon('objfun',x0,[],[],[1,1],0,[],[1;10])

For (c)-(f)  we need a constraint function file. In each case the first line of the file constraint.m  is:

function [c,ceq]=constraint(x)

followed by an empty line. The commands below the 2nd line are:
 

For example, for (f) the full constraint function file is:

function [c,ceq]=constraint(x)

c1=x(1)^2+x(2)^2-1;
c2=1-x(1)^2+x(2)^2;
c=[c1;c2];ceq=[];

Function calls for (c)-(f):
(c):       [x,fval]=fmincon('objfun',x0,[1,1],0,[],[],[],[],'constraint')
(d)-(f):  [x,fval]=fmincon('objfun',x0,[],[],[],[],[],[],'constraint')

Approximate solutions found by fmincon:
 

Example 2:    top

Minimize and maximize the objective function

f=x(1)^3+x(2)^3+x(3)^3;

For Maximization:
function f=objfun(x)

f=x(1)^3+x(2)^3+x(3)^3;f=-f;

Constraint function file:
function [c,ceq]=constraint(x)

c=2*x(3)^2-x(2)^2;
ceq=x(1)^2+x(2)^2+x(3)^2-1;

Function calls (in command window) and answers:
Minimization:
>> x0=[0;1;2];
>> [x,fval]=fmincon('objfun',x0,[],[],[],[],[0;-Inf;-Inf],[Inf;Inf;0],'constraint')

Warning: Large-scale (trust region) method does not currently solve this type of problem,
switching to medium-scale (line search).
> In C:\MATLABR12\toolbox\optim\fmincon.m at line 213
Optimization terminated successfully:
 Magnitude of directional derivative in search direction
  less than 2*options.TolFun and maximum constraint violation
  is less than options.TolCon
Active Constraints:
     1
     3
x =
   0.92898366078939
  -0.37012154351899
                  0
fval =
  -2.20932218190572

Answer for Maximization (same call, only objective function file was changed):
Warning: Large-scale (trust region) method does not currently solve this type of problem,
switching to medium-scale (line search).
> In C:\MATLABR12\toolbox\optim\fmincon.m at line 213
Optimization terminated successfully:
 Search direction less than 2*options.TolX and
  maximum constraint violation is less than options.TolCon
Active Constraints:
     1
x =
     0
     1
     0
fval =
    -1
 

B: Call of fmincon with gradient information provided    top

As for fminunc the performance of fmincon can be improved if gradient information is supplied. This information can be provided for the objective function, the nonlinear constraint functions, or both. Let's consider Example 1(f) again. The objective function file is extended as:

function [f,gradf]=objfun(x)

f=x(1)^4-x(1)^2+x(2)^2-2*x(1)+x(2);
gradf=[4*x(1)^3-2*x(1)-2;2*x(2)+1];

For providing the gradients of the nonlinear constraints, the constraint function file is extended as:

function [c,ceq,gradc,gradceq]=constraint(x)

c1=x(1)^2+x(2)^2-1;
c2=1-x(1)^2+x(2)^2;
c=[c1;c2];ceq=[];
gradc=[2*x(1),-2*x(1);2*x(2),2*x(2)];
gradceq=[];

Note that the the first column of gradc is the gradient-vector of the first constraint, and the second column of gradc is the gradient vector of the second constraint.

As in the unconstrained case we have to set the gradient option. We want to supply  the gradient of the objective function as well as the nonlinear constraints. The follwoing command sets this option:

>> options = optimset('GradObj','on','GradConstr','on');

In the function call these options are passed to fmincon as input argument after the name of the constraint file:

>> x0=[.1;.1];[x,fval]=fmincon('objfun',x0,[],[],[],[],[],[],'constraint',options)

Warning: Large-scale (trust region) method does not currently solve this type of problem,
switching to medium-scale (line search).
> In C:\MATLABR12\toolbox\optim\fmincon.m at line 213
Optimization terminated successfully:
 Search direction less than 2*options.TolX and
  maximum constraint violation is less than options.TolCon
Active Constraints:
     1
     2
x =
   1.00000000000000
  -0.00000171875724
fval =
  -2.00000171875428
 
 

Matlab's HELP DESCRIPTION   top

FMINCON Finds the constrained minimum of a function of several variables.
    FMINCON solves problems of the form:
        min F(X)  subject to:  A*X  <= B, Aeq*X  = Beq (linear constraints)
         X                       C(X) <= 0, Ceq(X) = 0   (nonlinear constraints)
                                 LB <= X <= UB

    X=FMINCON(FUN,X0,A,B) starts at X0 and finds a minimum X to the function
    FUN, subject to the linear inequalities A*X <= B. FUN accepts input X and
    returns a scalar function value F evaluated at X. X0 may 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 in
    the range LB <= X <= UB. Use empty matrices for LB and UB
    if no bounds exist. Set LB(i) = -Inf if X(i) is unbounded below;
    set UB(i) = Inf if X(i) is unbounded above.

    X=FMINCON(FUN,X0,A,B,Aeq,Beq,LB,UB,NONLCON) subjects the minimization to the
    constraints defined in NONLCON. The function NONLCON accepts X and returns
    the vectors C and Ceq, representing the nonlinear inequalities and equalities
    respectively. FMINCON minimizes FUN 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
    default optimization parameters replaced by values in the structure OPTIONS,
    an argument created with the OPTIMSET function.  See OPTIMSET for details.  Used
    options are Display, TolX, TolFun, TolCon, DerivativeCheck, Diagnostics, GradObj,
    GradConstr, Hessian, MaxFunEvals, MaxIter, DiffMinChange and DiffMaxChange,
    LargeScale, MaxPCGIter, PrecondBandWidth, TolPCG, TypicalX, Hessian, HessMult,
    HessPattern. Use the GradObj option to specify that FUN also returns a second
    output argument G that is the partial derivatives of the function df/dX, at the
    point X. Use the Hessian option to specify that FUN also returns a third output
    argument H that is the 2nd partial derivatives of the function (the Hessian) at the
    point X.  The Hessian is only used by the large-scale method, not the
    line-search method. Use the GradConstr option to specify that NONLCON also
    returns third and fourth output arguments GC and GCeq, where GC is the partial
    derivatives of the constraint vector of inequalities C, and GCeq is the partial
    derivatives of the constraint vector of equalities Ceq. Use OPTIONS = [] as a
    place holder if no options are set.

    X=FMINCON(FUN,X0,A,B,Aeq,Beq,LB,UB,NONLCON,OPTIONS,P1,P2,...) passes the
    problem-dependent parameters P1,P2,... directly to the functions FUN
    and NONLCON: feval(FUN,X,P1,P2,...) and feval(NONLCON,X,P1,P2,...).  Pass
    empty matrices for A, B, Aeq, Beq, OPTIONS, LB, UB, and NONLCON to use the
    default values.

    [X,FVAL]=FMINCON(FUN,X0,...) returns the value of the objective
    function FUN at the solution X.

    [X,FVAL,EXITFLAG]=FMINCON(FUN,X0,...) returns a string EXITFLAG that
    describes the exit condition of FMINCON.
    If EXITFLAG is:
       > 0 then FMINCON converged to a solution X.
       0   then the maximum number of function evaluations was reached.
       < 0 then FMINCON did not converge to a solution.

    [X,FVAL,EXITFLAG,OUTPUT]=FMINCON(FUN,X0,...) returns a structure
    OUTPUT with the number of iterations taken in OUTPUT.iterations, the number
    of function evaluations in OUTPUT.funcCount, the algorithm used in
    OUTPUT.algorithm, the number of CG iterations (if used) in OUTPUT.cgiterations,
    and the first-order optimality (if used) in OUTPUT.firstorderopt.

    [X,FVAL,EXITFLAG,OUTPUT,LAMBDA]=FMINCON(FUN,X0,...) returns the Lagrange multipliers
    at the solution X: LAMBDA.lower for LB, LAMBDA.upper for UB, LAMBDA.ineqlin is
    for the linear inequalities, LAMBDA.eqlin is for the linear equalities,
    LAMBDA.ineqnonlin is for the nonlinear inequalities, and LAMBDA.eqnonlin
    is for the nonlinear equalities.

    [X,FVAL,EXITFLAG,OUTPUT,LAMBDA,GRAD]=FMINCON(FUN,X0,...) returns the value of
    the gradient of FUN at the solution X.

    [X,FVAL,EXITFLAG,OUTPUT,LAMBDA,GRAD,HESSIAN]=FMINCON(FUN,X0,...) returns the
    value of the HESSIAN of FUN at the solution X.

    Examples
      FUN can be specified using @:
         X = fmincon(@humps,...)
      In this case, F = humps(X) returns the scalar function value F of the HUMPS function
      evaluated at X.

      FUN can also be an inline object:
         X = fmincon(inline('3*sin(x(1))+exp(x(2))'),[1;1],[],[],[],[],[0 0])
      returns X = [0;0].

    See also OPTIMSET, FMINUNC, FMINBND, FMINSEARCH, @, INLINE.   top