% -*- texinfo -*-
% @deftypefn {Function File} {} [X, FX, INFO] = fzero (FCN, APPROX, OPTIONS)
%
% Given FCN, the name of a function of the form `F (X)', and an initial
% approximation APPROX, `fzero' solves the scalar nonlinear equation such that
% `F(X) == 0'. Depending on APPROX, `fzero' uses different algorithms to solve
% the problem: either the Brent's method or the Powell's method of `fsolve'.
%
% @deftypefnx {Function File} {} [X, FX, INFO] = fzero (FCN, APPROX, OPTIONS,P1,P2,...)
%
% Call FCN with FCN(X,P1,P2,...).
%
% @table @asis
% @item INPUT ARGUMENTS
% @end table
%
% @table @asis
% @item APPROX can be a vector with two components,
% @example
% A = APPROX(1) and B = APPROX(2),
% @end example
% which localizes the zero of F, that is, it is assumed that X lies between A and
% B. If APPROX is a scalar, it is treated as an initial guess for X.
%
% If APPROX is a vector of length 2 and F takes different signs at A and B,
% F(A)*F(B) < 0, then the Brent's zero finding algorithm [1] is used with error
% tolerance criterion
% @example
% reltol*|X|+abstol (see OPTIONS).
% @end example
% This algorithm combines
% superlinear convergence (for sufficiently regular functions) with the
% robustness of bisection.
%
% Whether F has identical signs at A and B, or APPROX is a single scalar value,
% then `fzero' falls back to another method and `fsolve(FCN, X0)' is called, with
% the starting value X0 equal to (A+B)/2 or APPROX, respectively. Only absolute
% residual tolerance, abstol, is used then, due to the limitations of the `fsolve_options'
% function. See OPTIONS and `help fsolve' for details.
%
% @item OPTIONS is a structure, with the following fields:
%
% @table @asis
% @item 'abstol' - absolute (error for Brent's or residual for fsolve)
% tolerance. Default = 1e-6.
%
% @item 'reltol' - relative error tolerance (only Brent's method). Default = 1e-6.
%
% @item 'prl' - print level, how much diagnostics to print. Default = 0, no
% diagnostics output.
% @end table
%
% If OPTIONS argument is omitted, or a specific field is not present in the
% OPTIONS structure, default values will be used.
% @end table
%
% @table @asis
% @item OUTPUT ARGUMENTS
% @end table
%
% @table @asis
% @item The computed approximation to the zero of FCN is returned in X. FX is then equal
% to FCN(X). If the iteration converged, INFO == 1. If Brent's method is used,
% and the function seems discontinuous, INFO is set to -5. If fsolve is used,
% INFO is determined by its convergence.
% @end table
%
% @table @asis
% @item EXAMPLES
% @end table
%
% @example
% fzero('sin',[-2 1]) will use Brent's method to find the solution to
% sin(x) = 0 in the interval [-2, 1]
% @end example
%
% @example
% [x, fx, info] = fzero('sin',-2) will use fsolve to find a solution to
% sin(x)=0 near -2.
% @end example
%
% @example
% options.abstol = 1e-2; fzero('sin',-2, options) will use fsolve to
% find a solution to sin(x)=0 near -2 with the absolute tolerance 1e-2.
% @end example
%
% @table @asis
% @item REFERENCES
% [1] Brent, R. P. 'Algorithms for minimization without derivatives' (1971).
% @end table
% @end deftypefn
% @seealso{fsolve}