fmincon

x = fmincon(fun,x0)
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,fval,exitflag,output,lambda,grad,hessian] = fmincon ( ... )

Parameters

fun:

a function, the function to minimize. See below for the complete specifications.

x0:

a nx1 or 1xn matrix of doubles, where n is the number of variables. The initial guess for the optimization algorithm.

A:

a nil x n matrix of doubles, where n is the number of variables and nil is the number of linear inequalities. If A==[] and b==[], it is assumed that there is no linear inequality constraints. If (A==[] & b<>[]), fmincon generates an error (the same happens if (A<>[] & b==[])).

b:

a nil x 1 matrix of doubles, where nil is the number of linear inequalities.

Aeq:

a nel x n matrix of doubles, where n is the number of variables and nel is the number of linear equalities. If A==[] and b==[], it is assumed that there is no linear equality constraints. If (Aeq==[] & beq<>[]), fmincon generates an error (the same happens if (Aeq<>[] & beq==[])).

beq:

a nel x 1 matrix of doubles, where nel is the number of linear inequalities.

lb:

a nx1 or 1xn matrix of doubles, where n is the number of variables. The lower bound for x. If lb==[], then the lower bound is automatically set to -inf.

ub:

a nx1 or 1xn matrix of doubles, where n is the number of variables. The upper bound for x. If lb==[], then the upper bound is automatically set to +inf.

nonlcon:

a function, the nonlinear constraints. See below for the complete specifications.

x:

a nx1 matrix of doubles, the computed solution of the optimization problem

fval:

a 1x1 matrix of doubles, the function value at x

exitflag:

a 1x1 matrix of floating point integers, the exit status. See below for details.

output:

a struct, the details of the optimization process. See below for details.

lambda:

a struct, the Lagrange multipliers at optimum. See below for details.

grad:

a nx1 matrix of doubles, the gradient of the objective function at optimum

hessian:

a nxn matrix of doubles, the Hessian of the objective function at optimum

options:

an optional struct, as provided by optimset

Description

Search the minimum of a constrained optimization problem specified by : find the minimum of f(x) such that

c(x)<=0, ceq(x)<=0, A*x<=b, Aeq*x=beq and lb<=x<=ub.

Currently, we use ipopt for the actual solver of fmincon.

See the demonstrations for additionnal examples.

The objective function must have header :

where x is a n x 1 matrix of doubles and f is a 1 x 1 matrix of doubles. On input, the variable x contains the current point and, on output, the variable f must contain the objective function value.

By default, fmincon uses finite differences with order 2 formulas and optimum step size in order to compute a numerical gradient of the objective function. If we can provide exact gradients, we should do so since it improves the convergence speed of the optimization algorithm. In order to use exact gradients, we must update the header of the objective function to :

where x is a n x 1 matrix of doubles, f is a 1 x 1 matrix of doubles and G is a n x 1 matrix of doubles. On input, the variable x contains the current point and, on output, the variable f must contain the objective function value and the variable G must contain the gradient of the objective function. Furthermore, we must enable the "GradObj" option with the statement : This will let fmincon know that the exact gradient of the objective function is known, so that it can change the calling sequence to the objective function.

The constraint function must have header :

where x is a n x 1 matrix of doubles, c is a nni x 1 matrix of doubles and ceq is a nne x 1 matrix of doubles (nni : number of nonlinear inequality constraints, nne : number of nonlinear equality constraints). On input, the variable x contains the current point and, on output, the variable c must contain the nonlinear inequality constraints and ceq must contain the nonlinear equality constraints.

By default, fmincon uses finite differences with order 2 formulas and optimum step size in order to compute a numerical gradient of the constraint function. In order to use exact gradients, we must update the header of the constraint function to :

where x is a n x 1 matrix of doubles, c is a nni x 1 matrix of doubles, ceq is a nne x 1 matrix of doubles, DC is a n x nni matrix of doubles and DCeq is a n x nne matrix of doubles. On input, the variable x contains the current point and, on output, the variable c must contain the nonlinear inequality constraint function value, the variable ceq must contain the nonlinear equality constraint function value, the variable DC must contain the Jacobian matrix of the nonlinear inequality constraints and the variable DCeq must contain the Jacobian matrix of the nonlinear equality constraints. The i-th nonlinear inequality constraint is associated to the i-th column of the matrix DC, i.e, it is stored in DC(:,i) (same for DCeq). Furthermore, we must enable the "GradObj" option with the statement :

By default, fmincon uses a L-BFGS formula to compute an approximation of the Hessian of the Lagrangian. Notice that this is different from Matlab's fmincon, which default is to use a BFGS.

The exitflag variable allows to know the status of the optimization.

• exitflag=0 : Number of iterations exceeded options.MaxIter or number of function evaluations exceeded options.FunEvals.
• exitflag=1 : First-order optimality measure was less than options.TolFun, and maximum constraint violation was less than options.TolCon.
• exitflag=-1 : The output function terminated the algorithm.
• exitflag=-2 : No feasible point was found.
• exitflag=%nan : Other type of termination.

The output data structure contains detailed informations about the optimization process. It has type "struct" and contains the following fields.

• output.iterations: the number of iterations performed during the search
• output.funcCount: the number of function evaluations during the search
• output.stepsize: an empty matrix
• output.algorithm : the string containing the name of the algorithm. In the current version, algorithm="ipopt".
• output.firstorderopt: the max-norm of the first-order KKT conditions.
• output.constrviolation: the max-norm of the constraint violation.
• output.cgiterations: the number of preconditionned conjugate gradient steps. In the current version, cgiterations=0.
• output.message: a string containing a message describing the status of the optimization.

The lambda data structure contains the Lagrange multipliers at the end of optimization. It has type "struct" and contains the following fields.

• lambda.lower: the Lagrange multipliers for the lower bound constraints. In the current version, an empty matrix.
• lambda.upper: the Lagrange multipliers for the upper bound constraints. In the current version, an empty matrix.
• lambda.eqlin: the Lagrange multipliers for the linear equality constraints.
• lambda.eqnonlin: the Lagrange multipliers for the nonlinear equality constraints.
• lambda.ineqlin: the Lagrange multipliers for the linear inequality constraints.
• lambda.ineqnonlin: the Lagrange multipliers for the nonlinear inequality constraints.

TODO : exitflag=2 : Change in x was less than options.TolX and maximum constraint violation was less than options.TolCon. TODO : exitflag=-3 : Current point x went below options.ObjectiveLimit and maximum constraint violation was less than options.TolCon. TODO : fill lambda.lower and lambda.upper consistently. See ticket #111 : http://forge.scilab.org/index.php/p/sci-ipopt/issues/111/ TODO : test with A, b TODO : test with Aeq, beq TODO : test with ceq TODO : avoid using global for ipopt_data TODO : implement Display option TODO : implement FinDiffType option TODO : implement MaxFunEvals option TODO : implement DerivativeCheck option TODO : implement MaxIter option TODO : implement OutputFcn option TODO : implement PlotFcns option TODO : implement TolFun option TODO : implement TolCon option TODO : implement TolX option TODO : implement Hessian option TODO : check that the hessian output argument is Hessian of f only TODO : test all exitflag values

Examples

Examples

Examples

Authors

• Michael Baudin, DIGITEO, 2010