[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: fzero documentation
From: |
Doug Stewart |
Subject: |
Re: fzero documentation |
Date: |
Mon, 29 Nov 2010 10:22:28 -0500 |
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.