fminunc - Find minimum of unconstrained multivariable function

fun

The function to be minimized. fun is a function that accepts a vector x and returns a scalar f, the objective function evaluated at x. The function fun can be specified as a function handle for an M-file function

x = fminunc(@myfun,x0)

where myfun is a MATLAB function such as

function f = myfun(x)
f = ...            % Compute function value at x

fun can also be a function handle for an anonymous function.

x = fminunc(@(x)norm(x)^2,x0);

If the gradient of fun can also be computed and the GradObj option is 'on', as set by

options = optimset('GradObj','on')

then the function fun must return, in the second output argument, the gradient value g, a vector, at x. The gradient is the partial derivatives ∂f/∂x_i of f at the point x. That is, the ith component of g is the partial derivative of f with respect to the ith component of x.

If the Hessian matrix can also be computed and the Hessian option is 'on', i.e., options = optimset('Hessian','on'), then the function fun must return the Hessian value H, a symmetric matrix, at x in a third output argument. The Hessian matrix is the second partial derivatives matrix of f at the point x. That is, the (i,j)th component of H is the second partial derivative of f with respect to x_i and x_j, ∂²f/∂x_i∂x_j. The Hessian is by definition a symmetric matrix.

Writing Objective Functions explains how to "conditionalize" the gradients and Hessians for use in solvers that do not accept them. Passing Extra Parameters explains how to parameterize fun, if necessary.

options

Options provides the function-specific details for the options values.

objective

x0

solver

options

exitflag

Integer identifying the reason the algorithm terminated. The following lists the values of exitflag and the corresponding reasons the algorithm terminated.

1

Magnitude of gradient smaller than the TolFun tolerance.

2

Change in x was smaller than the TolX tolerance.

3

Change in the objective function value was less than the TolFun tolerance.

5

Predicted decrease in the objective function was less than the TolFun tolerance.

0

Number of iterations exceeded options.MaxIter or number of function evaluations exceeded options.FunEvals.

-1

Algorithm was terminated by the output function.

grad

Gradient at x

hessian

Hessian at x

output

Structure containing information about the optimization. The fields of the structure are

Number of iterations taken

Number of function evaluations

Measure of first-order optimality

Optimization algorithm used

Total number of PCG iterations (large-scale algorithm only)

Final displacement in x (medium-scale algorithm only)

Exit message

Use large-scale algorithm if possible when set to the default 'on'. Use medium-scale algorithm when set to 'off'.

Compare user-supplied derivatives (gradient of objective) to finite-differencing derivatives. The choices are 'on' or the default 'off'.

Display diagnostic information about the function to be minimized or solved. The choices are 'on' or the default 'off'.

DiffMaxChange

Maximum change in variables for finite-difference gradients (a positive scalar). The default is 0.1.

DiffMinChange

Minimum change in variables for finite-difference gradients (a positive scalar). The default is 1e-8.

Level of display:

• 'off' displays no output.

• 'iter' displays output at each iteration, and gives the default exit message.

• 'iter-detailed' displays output at each iteration, and gives the technical exit message.

• 'notify' displays output only if the function does not converge, and gives the default exit message.

• 'notify-detailed' displays output only if the function does not converge, and gives the technical exit message.

• 'final' (default) displays just the final output, and gives the default exit message.

• 'final-detailed' displays just the final output, and gives the technical exit message.

Check whether objective function values are valid. 'on' displays an error when the objective function returns a value that is complex, Inf, or NaN. The default, 'off', displays no error.

Gradient for the objective function defined by the user. See the preceding description of fun to see how to define the gradient in fun. Set to 'on' to have fminunc use a user-defined gradient of the objective function. The default 'off' causes fminunc to estimate gradients using finite differences. You must provide the gradient, and set GradObj to 'on', to use the large-scale algorithm. This option is not required for the medium-scale algorithm.

Maximum number of function evaluations allowed, a positive integer. The default value is 100*numberOfVariables.

Maximum number of iterations allowed, a positive integer. The default value is 400.

Specify one or more user-defined functions that an optimization function calls at each iteration, either as a function handle or as a cell array of function handles. The default is none ([]). See Output Function.

PlotFcns

Plots various measures of progress while the algorithm executes. Select from predefined plots or write your own. Pass a function handle or a cell array of function handles. The default is none ([]).

• @optimplotx plots the current point.

• @optimplotfunccount plots the function count.

• @optimplotfval plots the function value.

• @optimplotstepsize plots the step size.

• @optimplotfirstorderopt plots the first-order optimality measure.

Termination tolerance on the function value, a positive scalar. The default is 1e-6.

Termination tolerance on x, a positive scalar. The default value is 1e-6.

Typical x values. The number of elements in TypicalX is equal to the number of elements in x0, the starting point. The default value is ones(numberofvariables,1). fminunc uses TypicalX for scaling finite differences for gradient estimation.

If 'on', fminunc uses a user-defined Hessian for the objective function. The Hessian is either defined in the objective function (see fun), or is indirectly defined when using HessMult.

If 'off' (default), fminunc approximates the Hessian using finite differences.

Function handle for Hessian multiply function. For large-scale structured problems, this function computes the Hessian matrix product H*Y without actually forming H. The function is of the form

W = hmfun(Hinfo,Y)

where Hinfo contains the matrix used to compute H*Y.

The first argument must be the same as the third argument returned by the objective function fun, for example by

[f,g,Hinfo] = fun(x)

Y is a matrix that has the same number of rows as there are dimensions in the problem. W = H*Y although H is not formed explicitly. fminunc uses Hinfo to compute the preconditioner. See Passing Extra Parameters for information on how to supply values for any additional parameters hmfun needs.

Note   'Hessian' must be set to 'on' for fminunc to pass Hinfo from fun to hmfun.

See Example: Nonlinear Minimization with a Dense but Structured Hessian and Equality Constraints for an example.

Sparsity pattern of the Hessian for finite differencing. If it is not convenient to compute the sparse Hessian matrix H in fun, the large-scale method in fminunc can approximate H via sparse finite differences (of the gradient) provided the sparsity structure of H —i.e., locations of the nonzeros—is supplied as the value for HessPattern. In the worst case, if the structure is unknown, you can set HessPattern to be a dense matrix and a full finite-difference approximation is computed at each iteration (this is the default). This can be very expensive for large problems, so it is usually worth the effort to determine the sparsity structure.

Maximum number of PCG (preconditioned conjugate gradient) iterations, a positive scalar. The default is max(1,floor(numberOfVariables/2)). For more information, see Algorithms.

Upper bandwidth of preconditioner for PCG, a nonnegative integer. By default, fminunc uses diagonal preconditioning (upper bandwidth of 0). For some problems, increasing the bandwidth reduces the number of PCG iterations. Setting PrecondBandWidth to Inf uses a direct factorization (Cholesky) rather than the conjugate gradients (CG). The direct factorization is computationally more expensive than CG, but produces a better quality step towards the solution.

Termination tolerance on the PCG iteration, a positive scalar. The default is 0.1.

Finite differences, used to estimate gradients, are either 'forward' (the default), or 'central' (centered). 'central' takes twice as many function evaluations, but should be more accurate.

Method for choosing the search direction in the Quasi-Newton algorithm. The choices are:

• 'bfgs', the default

• 'dfp'

• 'steepdesc'

  See Hessian Update for a description of these methods.

Initial quasi-Newton matrix. This option is only available if you set InitialHessType to 'user-supplied'. In that case, you can set InitialHessMatrix to one of the following:

• A positive scalar — The initial matrix is the scalar times the identity.

• A vector of positive values— The initial matrix is a diagonal matrix with the entries of the vector on the diagonal. This vector should be the same size as the x0 vector, the initial point.

Initial quasi-Newton matrix type. The options are:

• 'identity'

• 'scaled-identity', the default

• 'user-supplied' — See InitialHessMatrix

Must provide gradient for f(x) in fun.

• Provide sparsity structure of the Hessian, or compute the Hessian in fun.

• The Hessian should be sparse.