lsqcurvefit - Solve nonlinear curve-fitting (data-fitting) problems in least-squares sense

fun

The function you want to fit. fun is a function that takes two inputs: a vector or matrix x, and a vector or matrix xdata. fun returns a vector or matrix F, the objective function evaluated at x and xdata. The function fun can be specified as a function handle for a function file:

x = lsqcurvefit(@myfun,x0,xdata,ydata)

where myfun is a MATLAB function such as

function F = myfun(x,xdata)
F = ...     % Compute function values at x, xdata

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

f = @(x,xdata)x(1)*xdata.^2+x(2)*sin(xdata);
x = lsqcurvefit(f,x0,xdata,ydata);

lsqcurvefit internally converts matrix x or F to vectors using linear indexing.

Note   fun should return fun(x,xdata), and not the sum-of-squares sum((fun(x,xdata)-ydata).^2). lsqcurvefit implicitly squares and sums fun(x,xdata)-ydata.

If the Jacobian can also be computed and the Jacobian option is 'on', set by

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

then the function fun must return, in a second output argument, the Jacobian value J, a matrix, at x. By checking the value of nargout, the function can avoid computing J when fun is called with only one output argument (in the case where the optimization algorithm only needs the value of F but not J).

function [F,J] = myfun(x,xdata)
F = ...          % objective function values at x
if nargout > 1   % two output arguments
   J = ...   % Jacobian of the function evaluated at x
end

If fun returns a vector (matrix) of m components and x has length n, where n is the length of x0, then the Jacobian J is an m-by-n matrix where J(i,j) is the partial derivative of F(i) with respect to x(j). (The Jacobian J is the transpose of the gradient of F.) For more information, see Writing Vector and Matrix Objective Functions.

options

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

objective

x0

xdata

ydata

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

Function converged to a solution x.

2

Change in x was less than the specified tolerance.

3

Change in the residual was less than the specified tolerance.

4

Magnitude of search direction smaller than the specified tolerance.

0

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

-1

Output function terminated the algorithm.

-2

Problem is infeasible: the bounds lb and ub are inconsistent.

-4

Optimization could not make further progress.

lambda

Structure containing the Lagrange multipliers at the solution x (separated by constraint type). The fields of the structure are

Lower bounds lb

Upper bounds ub

output

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

Measure of first-order optimality (trust-region-reflective algorithm, [ ] for others).

Number of iterations taken

Number of function evaluations

Total number of PCG iterations (trust-region-reflective algorithm, [ ] for others)

Optimization algorithm used

Final displacement in x (Levenberg-Marquardt algorithm).

Exit message

Algorithm

Choose between 'trust-region-reflective' (default) and 'levenberg-marquardt'. Set the initial Levenberg-Marquardt parameter λ by setting Algorithm to a cell array such as {'levenberg-marquardt',.005}. The default λ = 0.01.

The Algorithm option specifies a preference for which algorithm to use. It is only a preference, because certain conditions must be met to use each algorithm. For the trust-region-reflective algorithm, the nonlinear system of equations cannot be underdetermined; that is, the number of equations (the number of elements of F returned by fun) must be at least as many as the length of x. The Levenberg-Marquardt algorithm does not handle bound constraints. For more information on choosing the algorithm, see Choosing the Algorithm.

Compare user-supplied derivatives (gradients of objective or constraints) 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 Inf.

DiffMinChange

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

Display

Level of display. 'off' displays no output, and 'final' (default) displays just the final output.

Scalar or vector step size factor. When you set FinDiffRelStep to a vector v, forward finite differences delta are

delta = v.*sign(x).*max(abs(x),TypicalX);

and central finite differences are

delta = v.*max(abs(x),TypicalX);

Scalar FinDiffRelStep expands to a vector. The default is sqrt(eps) for forward finite differences, and eps^(1/3) for central finite differences.

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

The algorithm is careful to obey bounds when estimating both types of finite differences. So, for example, it could take a backward, rather than a forward, difference to avoid evaluating at a point outside bounds.

FunValCheck

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

Jacobian

If 'on', lsqcurvefit uses a user-defined Jacobian (defined in fun), or Jacobian information (when using JacobMult), for the objective function. If 'off' (default), lsqcurvefit approximates the Jacobian using finite differences.

MaxFunEvals

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

MaxIter

Maximum number of iterations allowed, a positive integer. The default 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.

• @optimplotresnorm plots the norm of the residuals.

• @optimplotstepsize plots the step size.

• @optimplotfirstorderopt plots the first-order optimality measure.

For information on writing a custom plot function, see Plot Functions.

TolFun

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

TolX

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

TypicalX

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). lsqcurvefit uses TypicalX for scaling finite differences for gradient estimation.

JacobMult

Function handle for Jacobian multiply function. For large-scale structured problems, this function computes the Jacobian matrix product J*Y, J'*Y, or J'*(J*Y) without actually forming J. The function is of the form

W = jmfun(Jinfo,Y,flag) 

where Jinfo contains the matrix used to compute J*Y (or J'*Y, or J'*(J*Y)). The first argument Jinfo must be the same as the second argument returned by the objective function fun, for example, in

[F,Jinfo] = fun(x)

Y is a matrix that has the same number of rows as there are dimensions in the problem. flag determines which product to compute:

• If flag == 0 then W = J'*(J*Y).

• If flag > 0 then W = J*Y.

• If flag < 0 then W = J'*Y.

In each case, J is not formed explicitly. lsqcurvefit uses Jinfo to compute the preconditioner. See Passing Extra Parameters for information on how to supply values for any additional parameters jmfun needs.

Note   'Jacobian' must be set to 'on' for lsqcurvefit to pass Jinfo from fun to jmfun.

See Example: Nonlinear Minimization with a Dense but Structured Hessian and Equality Constraints and Example: Jacobian Multiply Function with Linear Least Squares for similar examples.

JacobPattern

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

MaxPCGIter

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

PrecondBandWidth

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

TolPCG

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

ScaleProblem

'Jacobian' can sometimes improve the convergence of a poorly-scaled problem; the default is 'none'.

• Provide sparsity structure of the Jacobian or compute the Jacobian in fun.

• The Jacobian should be sparse.