<< fmincon fmincon API Functions >>
fmincon >> fmincon > fmincon

fmincon

Solves a nonlinearily constrained optimization problem.

Calling Sequence

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 ( ... )

Parameters

objective:

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.

Aineq:

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==[])).

bineq:

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 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==[])).

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:

a structure which handles parameters allowing a fine tuning of fmincon (see the dedicated section below).

problem:

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.

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.

\begin{eqnarray} \mbox{min}_{x} & f(x) \\ \mbox{subject to} & c(x) \leq 0 \\ & c_{eq}(x) = 0 \\ & Ax \leq b \\ & A_{eq} x = b_{eq} \\ & lb \leq x \leq ub \end{eqnarray}

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.

Example

// 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)

Example

// 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]=objfungrad(x)
  [lhs,rhs] = argn()
  f = exp(x(1))*(4*x(1)^2+2*x(2)^2+4*x(1)*x(2)+2*x(2)+1)
  if ( lhs  > 1 ) then
    G = [ f + exp(x(1)) * (8*x(1) + 4*x(2))
    exp(x(1))*(4*x(1)+4*x(2)+2) ]
  end
endfunction

// The nonlinear constraints and the Jacobian
// matrix of the constraints
function [c, ceq, DC, DCeq]=confungrad(x)
  // Inequality constraints
  c(1) = 1.5 + x(1) * x(2) - x(1) - x(2)
  c(2) = -x(1) * x(2)-10
  // No nonlinear equality constraints
  ceq = []
  [lhs,rhs] = argn()
  if ( lhs > 2 ) then
    // DC(:,i) = gradient of the i-th constraint
    // DC = [
    //   Dc1/Dx1  Dc2/Dx1
    //   Dc1/Dx2  Dc2/Dx2
    //   ]
    DC= [ x(2)-1, -x(2)
          x(1)-1, -x(1) ]
    DCeq = []
  end
endfunction

// Test with both gradient of objective and gradient of constraints
options = optimoptions('fmincon','SpecifyObjectiveGradient',%t,'SpecifyConstraintGradient',%t);

// 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] = ..
fmincon(objfungrad,x0,[],[],[],[],[],[], confungrad,options)

Example

// 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)

Same example with a problem structure

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)

fmincon options

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 x the actual step is

sign(x).*FiniteDifferenceStepSize.*max(TypicalX,x)

It can be a scalar, or a vector with the same size as x. Its default value depends on the chosen approximation scheme: sqrt(%eps) for the 'forward' scheme, %eps^(1/3) for the 'centered' scheme and 1e-100 for the 'complexStep' scheme.

FiniteDifferenceType

This field gives the chosen approximation scheme. The possible values are

  • 'forward' (the usual forward order 1 scheme)
  • 'centered' (the default order 2 centered scheme)
  • 'complexStep' (the order 2 complex step scheme)

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 %t the objective function must have the prototype

[f,g] = objfungrad(x)

and yield the exact gradient of the objective function as second output argument. When SpecifyObjectiveGradient is %f (the default) the gradient is approximated by finite differences.

SpecifyConstraintGradient

When SpecifyConstraintGradient is set to %t the constraints function must have the prototype

[c,ceq,dc,dceq] = constrgrad(x)

and yield the exact gradient (transpose of the Jacobian) of the inequality and inequality constraint as third and fourth output argument. When SpecifyConstraintGradient is %f (the default) these gradients are approximated by finite differences.

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 x0, with typical magnitude of components. The default value is ones(x0).

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

  • 'bfgs' for classical BFGS update formula
  • {'lbfgs',n} for limited-memory BFGS update (default value for n is 6)
  • 'finite-difference'

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

H = hessian(x,lambda)

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

[f,g,H] = objective(x)

(and SpecifyObjectiveGradient must be set to %t).

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 %f, the bounds given by the user may be slightly relaxed (typical factor is sqrt(%eps)). The default value is %t.

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

See Also

Authors


Report an issue
<< fmincon fmincon API Functions >>