Re: fzero documentation

[Doug Stewart]

On Mon, Nov 29, 2010 at 5:56 AM, Bart Vandewoestyne
<address@hidden> wrote:
> Hello all,
>
> Today, while preparing a lab session for my students, I was playing around 
> with
> fzero and I noticed some inconsistencies in the documentation.  I'm not sure 
> if
> this is the place to report them and if these are fixed in later releases of
> Octave... Feel free to forward my mail to the appropriate place.
>
> My comments concern Octave 3.2.4 on Ubuntu 10.10 (installed using the 
> packaging
> system).
>
> 1) the OUTPUT output argument of fzero is not documented.
>
> 2) the help of fzero mentions 'x0 specifies a starting point'.  Trying with 
> the
> equation x+log(x)=0 (solution is 0.56714) gives me:
>
>  octave:3> fzero(@(x) x+log(x), 0.5)
>  ans =  0.56714
>
>  octave:4> fzero(@(x) x+log(x), 0.9)
>  error: fzero: zero point is not bracketed
>  error: called from:
>  error:   /usr/share/octave/3.2.4/m/optimization/fzero.m at line
>  255, column 1
>
>  octave:4> fzero(@(x) x+log(x), [0 1])
>  ans =  0.56714
>
> so in certain situations a single starting point works, but in other 
> situations
> this doesn't work and one has to specify a starting interval.  This is not
> clear from the help...
>
> 3) The help of fzero refers to the optimset command for a description of
> certain options that one can specify.  However, `help optimset' does not show
> me any info regarding these options.  All I get is:
>
>  octave:5> help optimset
>  `optimset' is a function from the file 
> /usr/share/octave/3.2.4/m/optimization/optimset.m
>
>   -- Function File:  optimset ()
>   -- Function File:  optimset (PAR, VAL, ...)
>   -- Function File:  optimset (OLD, PAR, VAL, ...)
>   -- Function File:  optimset (OLD, NEW)
>       Create options struct for optimization functions.
>
>
>  Additional help for built-in functions and operators is
>  available in the on-line version of the manual.  Use the command
>  `doc <topic>' to search the manual index.
>
>  Help and information about Octave is also available on the WWW
>  at http://www.octave.org and via the address@hidden
>  mailing list.
>
>
> Kind regards,
> Bart
>
> --


Hi Bart :  The help for fzero is much improved in the latest sources. see below

I am going to try and Improve the comments for optimset.

Doug Stewart
##
## Author: Jaroslav Hajek <address@hidden>

## -*- texinfo -*-
## @deftypefn  {Function File} {} fzero (@var{fun}, @var{x0})
## @deftypefnx {Function File} {} fzero (@var{fun}, @var{x0}, @var{options})
## @deftypefnx {Function File} address@hidden, @var{fval}, @var{info},
@var{output}] =} fzero (@dots{})
## Find a zero of a univariate function.
##
## @var{fun} should be a function handle or name.  @var{x0} should be a
## two-element vector specifying two points which bracket a zero.  In
## other words, there must be a change in sign of the function between
## @var{x0}(1) and @var{x0}(2).  More mathematically, the following must hold
##
## @example
## sign (@var{fun}(@var{x0}(1))) * sign (@var{fun}(@var{x0}(2))) <= 0
## @end example
##
## If @var{x0} is a single scalar then several nearby and distant
## values are probed in an attempt to obtain a valid bracketing.  If this
## is not successful, the function fails.
## @var{options} is a structure specifying additional options.
## Currently, @code{fzero}
## recognizes these options: @code{"FunValCheck"}, @code{"OutputFcn"},
## @code{"TolX"}, @code{"MaxIter"}, @code{"MaxFunEvals"}.
## For a description of these options, see @ref{doc-optimset,,optimset}.
##
## On exit, the function returns @var{x}, the approximate zero point
## and @var{fval}, the function value thereof.
## @var{info} is an exit flag that can have these values:
##
## @itemize
## @item 1
##  The algorithm converged to a solution.
##
## @item 0
##  Maximum number of iterations or function evaluations has been reached.
##
## @item -1
## The algorithm has been terminated from user output function.
##
## @item -5
## The algorithm may have converged to a singular point.
## @end itemize
##
## @var{output} is a structure containing runtime information about the
## @code{fzero} algorithm.  Fields in the structure are:
##
## @itemize
## @item iterations
##  Number of iterations through loop.
##
## @item nfev
##  Number of function evaluations.
##
## @item bracketx
##  A two-element vector with the final bracketing of the zero along the x-axis.
##
## @item brackety
##  A two-element vector with the final bracketing of the zero along the y-axis.
## @end itemize
## @seealso{optimset, fsolve}
## @end deftypefn

## This is essentially the ACM algorithm 748: Enclosing Zeros of
## Continuous Functions due to Alefeld, Potra and Shi, ACM Transactions
## on Mathematical Software, Vol. 21, No. 3, September 1995. Although
## the workflow should be the same, the structure of the algorithm has
## been transformed non-trivially; instead of the authors' approach of
## sequentially calling building blocks subprograms we implement here a
## FSM version using one interior point determination and one bracketing
## per iteration, thus reducing the number of temporary variables and
## simplifying the algorithm structure. Further, this approach reduces
## the need for external functions and error handling. The algorithm has
## also been slightly modified.