Solves a nonlinearily constrained optimization problem.
x = fmincon(objective,x0) x = fmincon(objective,x0,Aineq,bineq) x = fmincon(objective,x0,Aineq,bineq,Aeq,beq) x = fmincon(objective,x0,Aineq,bineq,Aeq,beq,lb,ub) x = fmincon(objective,x0,Aineq,bineq,Aeq,beq,lb,ub,nonlcon) x = fmincon(objective,x0,Aineq,bineq,Aeq,beq,lb,ub,nonlcon,options) x = fmincon(problem) [x,fval,exitflag,output,lambda,grad,hessian] = fmincon ( ... )
a function, the function to minimize. See below for the complete specifications.
a nx1 or 1xn matrix of doubles, where n is the number of variables. The initial guess for the optimization algorithm.
a nil x n matrix of doubles, where n is the number of variables and nil is the number of linear inequalities. If Aineq==[] and bineq==[], it is assumed that there is no linear inequality constraints. If (Aineq==[] & bineq<>[]), fmincon generates an error (the same happens if (Aineq<>[] & bineq==[])).
a nil x 1 matrix of doubles, where nil is the number of linear inequalities.
a nel x n matrix of doubles, where n is the number of variables and nel is the number of linear equalities. If Aeq==[] and beq==[], it is assumed that there is no linear equality constraints. If (Aeq==[] & beq<>[]), fmincon generates an error (the same happens if (Aeq<>[] & beq==[])).
a nel x 1 matrix of doubles, where nel is the number of linear inequalities.
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.
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.
a function, the nonlinear constraints. See below for the complete specifications.
a nx1 matrix of doubles, the computed solution of the optimization problem
a 1x1 matrix of doubles, the function value at x
a 1x1 matrix of floating point integers, the exit status. See below for details.
a struct, the details of the optimization process. See below for details.
a struct, the Lagrange multipliers at optimum. See below for details.
a nx1 matrix of doubles, the gradient of the objective function at optimum
a nxn matrix of doubles, the Hessian of the objective function at optimum
a structure which handles parameters allowing a fine tuning of fmincon (see the dedicated section below).
A structure with fields having the same name and meaning as the formal input parameters described below. Omitting a field amounts to specify an empty matrix in the long syntax.
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 :
f = objfun(x)
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 :
[f,g] = objfungrad(x)
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 'SpecifyObjectiveGradient' option with the statement:
options = optimoptions('fmincon','SpecifyObjectiveGradient', %t);
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 :
[c, ceq] = confun(x)
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 :
[c,ceq,DC,DCeq] = confungrad(x)
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 transpose of Jacobian matrix of the nonlinear inequality constraints and the variable DCeq must contain the transpose Jacobian matrix of the nonlinear equality constraints. The gradient of the i-th nonlinear inequality constraint is is stored in DC(:,i) (same for DCeq). Furthermore, we must enable the 'SpecifyConstraintGradient' option with the statement :
options = optimsoptions('fmincon','SpecifyConstraintGradient',%t);
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 update.
The exitflag variable allows to know the status of the optimization.
The output data structure contains detailed informations about the optimization process. It has type 'struct' and contains the following fields.
The lambda data structure contains the Lagrange multipliers at the end of optimization. It has type 'struct' and contains the following fields.
// A basic case : // we provide only the objective function and the nonlinear constraint // function : we let fmincon compute the gradients by numerical // derivatives. function f=objfun(x) f = exp(x(1))*(4*x(1)^2 + 2*x(2)^2 + 4*x(1)*x(2) + 2*x(2) + 1) endfunction function [c, ceq]=confun(x) // Nonlinear inequality constraints c = [ 1.5 + x(1)*x(2) - x(1) - x(2) -x(1)*x(2) - 10 ] // Nonlinear equality constraints ceq = [] endfunction // The initial guess x0 = [-1,1]; // The expected solution : only 4 digits are guaranteed xopt = [-9.547345885974547 1.047408305349257] fopt = 0.023551460139148 // Run fmincon [x,fval,exitflag,output,lambda,grad,hessian] = .. fmincon (objfun,x0,[],[],[],[],[],[], confun) | ![]() | ![]() |
// A case where we set the bounds of the optimization. // By default, the bounds are set to infinity. function f=objfun(x) f = exp(x(1))*(4*x(1)^2 + 2*x(2)^2 + 4*x(1)*x(2) + 2*x(2) + 1) endfunction function [c, ceq]=confun(x) // Nonlinear inequality constraints c = [ 1.5 + x(1)*x(2) - x(1) - x(2) -x(1)*x(2) - 10 ] // Nonlinear equality constraints ceq = [] endfunction // The initial guess x0 = [-1,1]; // The expected solution xopt = [0 1.5] fopt = 8.5 // Make sure that x(1)>=0, and x(2)>=0 lb = [0,0]; ub = [ ]; // Run fmincon [x,fval] = fmincon ( objfun , x0,[],[],[],[],lb,ub,confun) | ![]() | ![]() |
function f=objfun(x) f = exp(x(1))*(4*x(1)^2 + 2*x(2)^2 + 4*x(1)*x(2) + 2*x(2) + 1) endfunction function [c, ceq]=confun(x) c = [ 1.5 + x(1)*x(2) - x(1) - x(2) -x(1)*x(2) - 10] ceq = [] endfunction // Define the problem structure problem = struct(); problem.x0 = [-1,1]; problem.lb = [0,0]; problem.objective = objfun; problem.nonlcon = confun; // Run fmincon [x,fval] = fmincon(problem) | ![]() | ![]() |
// A case where we provide the gradient of the objective // function and the Jacobian matrix of the constraints. // The objective function and its gradient function [f, g]=objfun(x) p = 4*x(1)^2 + 2*x(2)^2 + 4*x(1)*x(2) + 2*x(2) + 1; e = exp(x(1)); f = e*p; if argn(1) == 2 g = e*[p+8*x(1)+4*x(2); 4*x(2)+4*x(1)+2]; end endfunction // The nonlinear constraints and their gradients function [c, ceq, dc, dceq]=confun(x) // Inequality constraints c = [ 1.5+x(1)*x(2)-x(1)-x(2) -x(1)*x(2)-10] // No inequality constraint ceq = []; if argn(1) == 4 // dc(:,i) = gradient of the i-th constraint // dc is the transpose of the Jacobian of constraints dc = [x(2)-1, -x(2) x(1)-1, -x(1)]; dceq = []; end endfunction // The Hessian of the Lagrangian function h=hessfun(x, lambda) l = lambda.ineqnonlin; e = exp(x(1)); h(1,1) = e*(16*x(1)+10*x(2)+4*x(1)*x(2)+4*x(1)^2+2*x(2)^2+9); h(1,2) = e*(6+4*x(1)+4*x(2))+l(1)-l(2); h(2,2) = 4*e; h(2,1) = h(1,2); endfunction // Define the problem structure problem = struct(); problem.x0 = [-1,1]; problem.lb = [0,0]; problem.objective = objfun; problem.nonlcon = confun; // Optimization options problem.options = optimoptions("fmincon","Display","iter",... "SpecifyObjectiveGradient",%t,"SpecifyConstraintGradient",%t,... "CheckGradients",%t,"HessianFcn",hessfun) // Run fmincon [x,fval] = fmincon(problem) | ![]() | ![]() |
The default option structure for fmincon can be obtained as the output of optimoptions('fmincon'). General information about fields which are not specfic to fmincon can be found on the dedicated page optimoptions.
Algorithm | Optimization algorithm. This version of fmincon only allows the value 'ipopt'. |
CheckGradients | Set this field to %t to check user provided gradients (objective and constraints) before starting the optimization algorithm. |
ConstraintTolerance | Absolute tolerance on the constraint violation. Successful termination requires that the max-norm of the constraint violation is less than this threshold. The valid range for this real option is 0 < ConstraintTolerance < +inf and its default value is 0.0001. |
FiniteDifferenceStepSize | this is the relative stepsize (see also 'TypicalX' below). For a given
It can be a scalar, or a vector with the same size as |
FiniteDifferenceType | This field gives the chosen approximation scheme. The possible values are
If you choose the complex step scheme check that objective and constraints function accepts complex input and handles it correctly (for example transposition operator has to be the dot-prefixed non-conjugate transposition |
SpecifyObjectiveGradient | When SpecifyObjectiveGradient is set to
and yield the exact gradient of the objective function as second output argument. When SpecifyObjectiveGradient is |
SpecifyConstraintGradient | When SpecifyConstraintGradient is set to
and yield the exact gradient (transpose of the Jacobian) of the inequality and inequality constraint as third and fourth output argument. When SpecifyConstraintGradient is |
StepTolerance | Tolerance for detecting numerically insignificant steps. If the search direction in the primal variable is, in relative terms for each component, less than this value, the algorithm accepts the full step without line search. If this happens repeatedly, the algorithm will terminate with a corresponding exit message. Its default value is 10.0*%eps. |
TypicalX | A vector of the same size as |
ScaleProblem | Select the technique used for scaling the optimization problem. Possible values are 'gradient-based' (the default) and 'none'. |
HessianApproximation | Defines the type of Hessian approximation. Possible values are
The last value is allowed only if the exact gradients of objective and constraints are given (see SpecifyConstraintGradient and SpecifyObjectiveGradient below). In that case, and if the Hessian is known to be sparse, consider using the HessPattern option. |
HessianFcn | In the general case this field defines a function computing the Hessian of the Lagragian with the prototype
When there are only bounds or linear constraints then the Hessian of the Lagrangian is the Hessian of the objective. In that case the HessianFcn field can take the value 'objective' and the objective prototype has to be
(and SpecifyObjectiveGradient must be set to |
HessPattern | Defines the sparsity pattern of the Hessian and allows to reduce the number of objective and gradient evaluations when HessianApproximation is equal to 'finite-difference'. The HessPattern field can be a sparse matrix or a sparse boolean matrix where non-zero (or %t) elements define the non-zero second derivatives. |
HonorBounds | If this field is |
OptimalityTolerance | Determines the convergence tolerance for the algorithm. The algorithm terminates successfully, if the scaled NLP error becomes smaller than this value. The valid range for this real option is 0 < OptimalityTolerance < +inf and its default value is 1.10^-08. |
InitBarrierParam | Initial value for the barrier parameter. This option determines the initial value for the barrier parameter (mu). It is only relevant in the monotone, version of the algorithm (i.e., if 'BarrierParamUpdate' is chosen as 'monotone'). The valid range for this real option is 0 < InitBarrierParam < +inf and its default value is 0.1. |
BarrierParamUpdate | Update strategy for barrier parameter. Determines which barrier parameter update strategy is to be used. Possible values are 'monotone' (the default) or 'adaptive'. |
OutputFcn | See optimoptions |
PlotFcn | See optimoptions |