changeset 25740:b1e0e58971f9

fminbnd.m: Update solver options to be Matlab compatible. * NEWS: Announce changes in solver options for fminbnd. * fminbnd.m: Add additional calling forms to docstring. Rewrite docstring to alphabetize options structure. Add information about values of default options for fminbnd. Change default TolX to 1e-4, and MaxIter, MaxFunEvals to 500. Add field "algorithm" to output struct with same value as Matlab.
author Rik <rik@octave.org>
date Fri, 03 Aug 2018 15:23:45 -0700
parents 8eec0403a370
children a3f2b06c599a
files NEWS scripts/optimization/fminbnd.m
diffstat 2 files changed, 64 insertions(+), 32 deletions(-) [+]
line wrap: on
line diff
--- a/NEWS	Fri Aug 03 14:46:08 2018 -0700
+++ b/NEWS	Fri Aug 03 15:23:45 2018 -0700
@@ -32,9 +32,19 @@
         TolX         |     1e-6       |     1e-7
         Updating     |     "off"      |     "on"
 
- ** The fminsearch function has changed default TolFun accuracy to 1e-4
-    from 1e-7.  This change was made for Matlab compatibility, but may
-    result in different results from existing code.
+ ** The fminsearch function has changed default solver options for
+    Matlab compatibility.  The accuracy option TolFun is now 1e-4 rather
+    than 1e-7.  This *may* result in existing code producing different
+    results.
+
+ ** The fminbnd function has changed defaults for Matlab compatibility.
+    This *may* result in existing code producing different results.
+
+          Option     |  New Default   |  Old Default
+      ------------------------------------------------
+        MaxFunEvals  |      500       |     Inf
+        MaxIter      |      500       |     Inf
+        TolX         |     1e-4       |     1e-8
 
  ** Figure graphic objects have a new property "Number" which is
     read-only and will return the handle (number) of the figure.
--- a/scripts/optimization/fminbnd.m	Fri Aug 03 14:46:08 2018 -0700
+++ b/scripts/optimization/fminbnd.m	Fri Aug 03 15:23:45 2018 -0700
@@ -19,37 +19,58 @@
 ## Author: Jaroslav Hajek <highegg@gmail.com>
 
 ## -*- texinfo -*-
-## @deftypefn {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminbnd (@var{fun}, @var{a}, @var{b}, @var{options})
+## @deftypefn  {} {@var{x} =} fminbnd (@var{fun}, @var{a}, @var{b})
+## @deftypefnx {} {@var{x} =} fminbnd (@var{fun}, @var{a}, @var{b}, @var{options})
+## @deftypefnx {} {[@var{x}, @var{fval}, @var{info}, @var{output}] =} fminbnd (@dots{})
 ## Find a minimum point of a univariate function.
 ##
-## @var{fun} should be a function handle or name.  @var{a}, @var{b} specify a
-## starting interval.  @var{options} is a structure specifying additional
-## options.  Currently, @code{fminbnd} recognizes these options:
-## @qcode{"FunValCheck"}, @qcode{"OutputFcn"}, @qcode{"TolX"},
-## @qcode{"MaxIter"}, @qcode{"MaxFunEvals"}.  For a description of these
-## options, see @ref{XREFoptimset,,optimset}.
+## @var{fun} must be a function handle or name.
+##
+## The starting interval is specified by @var{a} (left boundary) and @var{b}
+## (right boundary).  The endpoints must be finite.
+##
+## @var{options} is a structure specifying additional parameters which
+## control the algorithm.  Currently, @code{fminbnd} recognizes these options:
+## @qcode{"Display"}, @qcode{"FunValCheck"}, @qcode{"MaxFunEvals"},
+## @qcode{"MaxIter"}, @qcode{"OutputFcn"}, @qcode{"TolX"}.
+##
+## @qcode{"MaxFunEvals"} proscribes the maximum number of function evaluations
+## before optimization is halted.  The default value is 500.
+## The value must be a positive integer.
 ##
-## On exit, the function returns @var{x}, the approximate minimum point and
-## @var{fval}, the function value thereof.
+## @qcode{"MaxIter"} proscribes the maximum number of algorithm iterations
+## before optimization is halted.  The default value is 500.
+## The value must be a positive integer.
+##
+## @qcode{"TolX"} specifies the termination tolerance for the solution @var{x}.
+## The default is @code{1e-4}.
 ##
-## @var{info} is an exit flag that can have these values:
+## For a description of the other options, see @ref{XREFoptimset,,optimset}.
+## To initialize an options structure with default values for @code{fminbnd}
+## use @code{options = optimset ("fminbnd")}.
+##
+## On exit, the function returns @var{x}, the approximate minimum point, and
+## @var{fval}, the function evaluated @var{x}.
+##
+## The third output @var{info} reports whether the algorithm succeeded and may
+## take one of the following values:
 ##
 ## @itemize
 ## @item 1
 ## The algorithm converged to a solution.
 ##
 ## @item 0
-## Maximum number of iterations or function evaluations has been exhausted.
+## Iteration limit (either @code{MaxIter} or @code{MaxFunEvals}) exceeded.
 ##
 ## @item -1
-## The algorithm has been terminated from user output function.
+## The algorithm was terminated by a user @code{OutputFcn}.
 ## @end itemize
 ##
-## Notes: The search for a minimum is restricted to be in the interval bound by
-## @var{a} and @var{b}.  If you only have an initial point to begin searching
-## from you will need to use an unconstrained minimization algorithm such as
-## @code{fminunc} or @code{fminsearch}.  @code{fminbnd} internally uses a
-## Golden Section search strategy.
+## Programming Notes: The search for a minimum is restricted to be in the
+## finite interval bound by @var{a} and @var{b}.  If you have only one initial
+## point to begin searching from then you will need to use an unconstrained
+## minimization algorithm such as @code{fminunc} or @code{fminsearch}.
+## @code{fminbnd} internally uses a Golden Section search strategy.
 ## @seealso{fzero, fminunc, fminsearch, optimset}
 ## @end deftypefn
 
@@ -63,9 +84,10 @@
 function [x, fval, info, output] = fminbnd (fun, a, b, options = struct ())
 
   ## Get default options if requested.
-  if (nargin == 1 && ischar (fun) && strcmp (fun, 'defaults'))
-    x = optimset ("MaxIter", Inf, "MaxFunEvals", Inf, "TolX", 1e-8,
-                  "OutputFcn", [], "FunValCheck", "off");
+  if (nargin == 1 && ischar (fun) && strcmp (fun, "defaults"))
+    x = optimset ("Display", "notify", "FunValCheck", "off",
+                  "MaxFunEvals", 500, "MaxIter", 500,
+                  "OutputFcn", [], "TolX", 1e-4);
     return;
   endif
 
@@ -85,9 +107,9 @@
   displ = optimget (options, "Display", "notify");
   funvalchk = strcmpi (optimget (options, "FunValCheck", "off"), "on");
   outfcn = optimget (options, "OutputFcn");
-  tolx = optimget (options, "TolX", 1e-8);
-  maxiter = optimget (options, "MaxIter", Inf);
-  maxfev = optimget (options, "MaxFunEvals", Inf);
+  tolx = optimget (options, "TolX", 1e-4);
+  maxiter = optimget (options, "MaxIter", 500);
+  maxfev = optimget (options, "MaxFunEvals", 500);
 
   if (funvalchk)
     ## Replace fun with a guarded version.
@@ -160,9 +182,8 @@
     if (dogs)
       ## Default to golden section step.
 
-      ## WARNING: This is also the "initial" procedure following
-      ## MATLAB nomenclature.  After the loop we'll fix the string
-      ## for the first step.
+      ## WARNING: This is also the "initial" procedure following MATLAB
+      ## nomenclature.  After the loop we'll fix the string for the first step.
       iter(niter+1).procedure = "golden";
 
       e = ifelse (x >= xm, a - x, b - x);
@@ -225,13 +246,13 @@
   switch (displ)
     case "iter"
       print_formatted_table (iter);
-      print_exit_msg (info, struct("TolX", tolx, "fx", fval));
+      print_exit_msg (info, struct ("TolX", tolx, "fx", fval));
     case "notify"
       if (info == 0)
-        print_exit_msg (info, struct("fx",fval));
+        print_exit_msg (info, struct ("fx",fval));
       endif
     case "final"
-      print_exit_msg (info, struct("TolX", tolx, "fx", fval));
+      print_exit_msg (info, struct ("TolX", tolx, "fx", fval));
     case "off"
       "skip";
     otherwise
@@ -240,6 +261,7 @@
 
   output.iterations = niter;
   output.funcCount = nfev;
+  output.algorithm = "golden section search, parabolic interpolation";
   output.bracket = [a, b];
   ## FIXME: bracketf possibly unavailable.