Navigation

Operators and Keywords

Function List:

C++ API

: fsolve (fcn, x0, options)
: [x, fvec, info, output, fjac] = fsolve (fcn, …)

Solve a system of nonlinear equations defined by the function fcn.

fcn should accept a vector (array) defining the unknown variables, and return a vector of left-hand sides of the equations. Right-hand sides are defined to be zeros. In other words, this function attempts to determine a vector x such that fcn (x) gives (approximately) all zeros.

x0 determines a starting guess. The shape of x0 is preserved in all calls to fcn, but otherwise it is treated as a column vector.

options is a structure specifying additional options. Currently, fsolve recognizes these options: "FunValCheck", "OutputFcn", "TolX", "TolFun", "MaxIter", "MaxFunEvals", "Jacobian", "Updating", "ComplexEqn" "TypicalX", "AutoScaling" and "FinDiffType".

If "Jacobian" is "on", it specifies that fcn, called with 2 output arguments also returns the Jacobian matrix of right-hand sides at the requested point. "TolX" specifies the termination tolerance in the unknown variables, while "TolFun" is a tolerance for equations. Default is 1e-7 for both "TolX" and "TolFun".

If "AutoScaling" is on, the variables will be automatically scaled according to the column norms of the (estimated) Jacobian. As a result, TolF becomes scaling-independent. By default, this option is off because it may sometimes deliver unexpected (though mathematically correct) results.

If "Updating" is "on", the function will attempt to use Broyden updates to update the Jacobian, in order to reduce the amount of Jacobian calculations. If your user function always calculates the Jacobian (regardless of number of output arguments) then this option provides no advantage and should be set to false.

"ComplexEqn" is "on", fsolve will attempt to solve complex equations in complex variables, assuming that the equations possess a complex derivative (i.e., are holomorphic). If this is not what you want, you should unpack the real and imaginary parts of the system to get a real system.

For description of the other options, see optimset.

On return, fval contains the value of the function fcn evaluated at x.

info may be one of the following values:

1

Converged to a solution point. Relative residual error is less than specified by TolFun.

2

Last relative step size was less that TolX.

3

Last relative decrease in residual was less than TolF.

0

Iteration limit exceeded.

-3

The trust region radius became excessively small.

Note: If you only have a single nonlinear equation of one variable, using fzero is usually a much better idea.

Note about user-supplied Jacobians: As an inherent property of the algorithm, a Jacobian is always requested for a solution vector whose residual vector is already known, and it is the last accepted successful step. Often this will be one of the last two calls, but not always. If the savings by reusing intermediate results from residual calculation in Jacobian calculation are significant, the best strategy is to employ OutputFcn: After a vector is evaluated for residuals, if OutputFcn is called with that vector, then the intermediate results should be saved for future Jacobian evaluation, and should be kept until a Jacobian evaluation is requested or until OutputFcn is called with a different vector, in which case they should be dropped in favor of this most recent vector. A short example how this can be achieved follows: 

function [fvec, fjac] = user_func (x, optimvalues, state)
persistent sav = [], sav0 = [];
if (nargin == 1)
  ## evaluation call
  if (nargout == 1)
    sav0.x = x; # mark saved vector
    ## calculate fvec, save results to sav0.
  elseif (nargout == 2)
    ## calculate fjac using sav.
  endif
else
  ## outputfcn call.
  if (all (x == sav0.x))
    sav = sav0;
  endif
  ## maybe output iteration status, etc.
endif
endfunction

## …

fsolve (@user_func, x0, optimset ("OutputFcn", @user_func, …))

See also: fzero, optimset.

Package: octave