Function File: fmincon (objf, x0)
Function File: fmincon (objf, x0, A, b)
Function File: fmincon (objf, x0, A, b, Aeq, beq)
Function File: fmincon (objf, x0, A, b, Aeq, beq, lb, ub)
Function File: fmincon (objf, x0, A, b, Aeq, beq, lb, ub, nonlcon)
Function File: fmincon (objf, x0, A, b, Aeq, beq, lb, ub, nonlcon, options)
Function File: fmincon (problem)
Function File: [x, fval, cvg, outp] = fmincon (…)

Compatibility frontend for nonlinear minimization of a scalar objective function.

This function is for Matlab compatibility and provides a subset of the functionality of nonlin_min.

objf: objective function. It gets the real parameters as argument.

x0: real vector or array of initial parameters.

A, b: Inequality constraints of the parameters p with A * p - b <= 0.

Aeq, beq: Equality constraints of the parameters p with A * p - b = 0.

lb, ub: Bounds of the parameters p with lb <= p <= ub. Vectors or arrays. If the number of elements is smaller than the number of parameters, as many bounds as present are applied, starting with the first parameter. This is for compatibility with Matlab.

nonlcon: Nonlinear constraints. Function returning the current values of nonlinear inequality constraints (constrained to <= 0) in the first output and the current values of nonlinear equality constraints in the second output.

options: structure whose fields stand for optional settings referred to below. The fields can be set by optimset().

An argument can be set to [] to indicate that its value is not set.

fmincon may also be called with a single structure argument with the fields objective, x0, Aineq, bineq, Aeq, beq, lb, ub, nonlcon and options, resembling the separate input arguments above. Additionally, the structure must have the field solver, set to "fmincon".

The returned values are the final parameters x, the final value of the objective function fval, an integer cvg indicating if and how optimization succeeded or failed, and a structure outp with additional information, curently with possible fields: iterations, the number of iterations, funcCount, the number of objective function calls (indirect calls by gradient function not counted), constrviolation, the maximum of the constraint violations. The backend may define additional fields. cvg is greater than zero for success and less than or equal to zero for failure; its possible values depend on the used backend and currently can be 0 (maximum number of iterations exceeded), 1 (success without further specification of criteria), 2 (parameter change less than specified precision in two consecutive iterations), 3 (improvement in objective function less than specified), -1 (algorithm aborted by a user function), or -4 (algorithm got stuck).

Options:

Algorithm

interior-point, sqp, and sqp-legacy are mapped to optims lm_feasible algorithm (the default) to satisfy constraints throughout the optimization. active-set is mapped to octave_sqp, which may perform better if constraints only need to be satisfied for the result. Other algorithms are available with nonlin_min.

OutputFcn

Similar to the setting user_interaction — see optim_doc(). Differently, OutputFcn returns only one output argument, the stop flag.

GradObj

If set to "on", objf must return the gradient of the objective function as a second output. The default is "off".

GradConstr

If set to "on", nonlcon must return the Jacobians of the inequality- and equality-constraints as third and fourth output, respectively.

HessianFcn

If set to "objective", objf must not only return the gradient as the second, but also the Hessian as the third output.

Display, FinDiffRelStep, FinDiffType, TypicalX, MaxIter, TolFun, TolX,

See documentation of these options in optim_doc().

For description of individual backends, type optim_doc ("scalar optimization") and choose the backend in the menu.

Demonstration 1

The following code

 ## Example for default optimization (Levenberg/Marquardt with
 ## BFGS), one non-linear equality constraint. Constrained optimum is
 ## at p = [0; 1].
 objective_function = @ (p) p(1)^2 + p(2)^2;
 pin = [-2; 5];
 constraint_function = @ (p) - (p(1)^2 + 1 - p(2));
 [p, objf, cvg, outp] = fmincon (objective_function, pin, [], [], [], [], [], [], @ (p) {[], constraint_function(p)}{:})

Produces the following output

p =

  -1.0909e-08
   1.0000e+00

objf = 1.0000
cvg = 3
outp =

  scalar structure containing the fields:

    user_interaction =

      scalar structure containing the fields:

        stop = [](0x1)
        info = {}(0x1)

    niter = 7
    nobjf = 12
    constrviolation = 2.1094e-15

Package: optim