Home > freetb4matlab > optimization > fsolve.m

fsolve

PURPOSE ^

% Solve a system of nonlinear equations defined by the function @var{fcn}.

SYNOPSIS ^

function [x, fvec, info, output, fjac] = fsolve (fcn, x0, options = struct )

DESCRIPTION ^

% -*- 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

CROSS-REFERENCE INFORMATION ^

This function calls: This function is called by:
Generated on Fri 22-May-2009 15:13:00 by m2html © 2003