% -*- texinfo -*-
% @deftypefn {Function File} {} fsolve (@var{fcn}, @var{x0}, @var{options})
% @deftypefnx {Function File} {[@var{x}, @var{fvec}, @var{info}, @var{output}, @var{fjac}]} = fsolve (@var{fcn}, @dots{})
% Solve a system of nonlinear equations defined by the function @var{fcn}.
% @var{fcn} should accepts 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 @var{x} such
% that @code{@var{fcn} (@var{x})} gives (approximately) all zeros.
% @var{x0} determines a starting guess. The shape of @var{x0} is preserved
% in all calls to @var{fcn}, but otherwise it is treated as a column vector.
% @var{options} is a structure specifying additional options.
% Currently, @code{fsolve} recognizes these options:
% @code{'FunValCheck'}, @code{'OutputFcn'}, @code{'TolX'},
% @code{'TolFun'}, @code{'MaxIter'}, @code{'MaxFunEvals'},
% @code{'Jacobian'}, @code{'Updating'} and @code{'ComplexEqn'}.
%
% If @code{'Jacobian'} is @code{'on'}, it specifies that @var{fcn},
% called with 2 output arguments, also returns the Jacobian matrix
% of right-hand sides at the requested point. @code{'TolX'} specifies
% the termination tolerance in the unknown variables, while
% @code{'TolFun'} is a tolerance for equations. Default is @code{1e-7}
% for both @code{'TolX'} and @code{'TolFun'}.
% If @code{'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), this option provides no advantage and should be set to
% false.
%
% @code{'ComplexEqn'} is @code{'on'}, @code{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,
% should unpack the real and imaginary parts of the system to get a real
% system.
%
% For description of the other options, see @code{optimset}.
%
% On return, @var{fval} contains the value of the function @var{fcn}
% evaluated at @var{x}, and @var{info} may be one of the following values:
%
% @table @asis
% @item 1
% Converged to a solution point. Relative residual error is less than specified
% by TolFun.
% @item 2
% Last relative step size was less that TolX.
% @item 3
% Last relative decrease in residual was less than TolF.
% @item 0
% Iteration limit exceeded.
% @item -3
% The trust region radius became excessively small.
% @end table
%
% Note: If you only have a single nonlinear equation of one variable, using
% @code{fzero} is usually a much better idea.
% @seealso{fzero, optimset}
%
% Note about user-supplied jacobians:
% As an inherent property of the algorithm, 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:
%
% @example
% 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.
% end
% else
% %% outputfcn call.
% if (all (x == sav0.x))
% sav = sav0;
% end
% %% maybe output iteration status, etc.
% end
%
%
% %% @dots{}.
%
% fsolve (@@user_func, x0, optimset ('OutputFcn', @@user_func, @dots{}))
% @end example
%%
% @end deftypefn