octave_packages/m/optimization/optimset.m

   1 ## Copyright (C) 2007-2012 John W. Eaton
   2 ## Copyright (C) 2009 VZLU Prague
   3 ##
   4 ## This file is part of Octave.
   5 ##
   6 ## Octave is free software; you can redistribute it and/or modify it
   7 ## under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 3 of the License, or (at
   9 ## your option) any later version.
  10 ##
  11 ## Octave is distributed in the hope that it will be useful, but
  12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 ## General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with Octave; see the file COPYING.  If not, see
  18 ## <http://www.gnu.org/licenses/>.
  19
  20 ## -*- texinfo -*-
  21 ## @deftypefn  {Function File} {} optimset ()
  22 ## @deftypefnx {Function File} {} optimset (@var{par}, @var{val}, @dots{})
  23 ## @deftypefnx {Function File} {} optimset (@var{old}, @var{par}, @var{val}, @dots{})
  24 ## @deftypefnx {Function File} {} optimset (@var{old}, @var{new})
  25 ## Create options struct for optimization functions.
  26 ##
  27 ## Valid parameters are:
  28 ## @itemize @bullet
  29 ## @item AutoScaling
  30 ##
  31 ## @item ComplexEqn
  32 ##
  33 ## @item FinDiffType
  34 ##
  35 ## @item FunValCheck
  36 ## When enabled, display an error if the objective function returns a complex
  37 ## value or NaN@.  Must be set to "on" or "off" [default].
  38 ##
  39 ## @item GradObj
  40 ## When set to "on", the function to be minimized must return a second argument
  41 ## which is the gradient, or first derivative, of the function at the point
  42 ## @var{x}.  If set to "off" [default], the gradient is computed via finite
  43 ## differences.
  44 ##
  45 ## @item Jacobian
  46 ## When set to "on", the function to be minimized must return a second argument
  47 ## which is the Jacobian, or first derivative, of the function at the point
  48 ## @var{x}.  If set to "off" [default], the Jacobian is computed via finite
  49 ## differences.
  50 ##
  51 ## @item MaxFunEvals
  52 ## Maximum number of function evaluations before optimization stops.
  53 ## Must be a positive integer.
  54 ##
  55 ## @item MaxIter
  56 ## Maximum number of algorithm iterations before optimization stops.
  57 ## Must be a positive integer.
  58 ##
  59 ## @item OutputFcn
  60 ## A user-defined function executed once per algorithm iteration.
  61 ##
  62 ## @item TolFun
  63 ## Termination criterion for the function output.  If the difference in the
  64 ## calculated objective function between one algorithm iteration and the next
  65 ## is less than @code{TolFun} the optimization stops.  Must be a positive
  66 ## scalar.
  67 ##
  68 ## @item TolX
  69 ## Termination criterion for the function input.  If the difference in @var{x},
  70 ## the current search point, between one algorithm iteration and the next is
  71 ## less than @code{TolX} the optimization stops.  Must be a positive scalar.
  72 ##
  73 ## @item TypicalX
  74 ##
  75 ## @item Updating
  76 ## @end itemize
  77 ## @end deftypefn
  78
  79 function retval = optimset (varargin)
  80
  81   nargs = nargin ();
  82
  83   ## Add more as needed.
  84   opts = __all_opts__ ();
  85
  86   if (nargs == 0)
  87     if (nargout == 0)
  88       ## Display possibilities.
  89       puts ("\nAll possible optimization options:\n\n");
  90       printf ("  %s\n", opts{:});
  91       puts ("\n");
  92     else
  93       ## Return struct with all options initialized to []
  94       retval = cell2struct (repmat ({[]}, size (opts)), opts, 2);
  95     endif
  96   elseif (nargs == 1 && ischar (varargin{1}))
  97     ## Return defaults for named function.
  98     fcn = varargin{1};
  99     try
 100       retval = feval (fcn, "defaults");
 101     catch
 102       error ("optimset: no defaults for function `%s'", fcn);
 103     end_try_catch
 104   elseif (nargs == 2 && isstruct (varargin{1}) && isstruct (varargin{2}))
 105     ## Set slots in old from nonempties in new.  Should we be checking
 106     ## to ensure that the field names are expected?
 107     old = varargin{1};
 108     new = varargin{2};
 109     fnames = fieldnames (old);
 110     ## skip validation if we're in the internal query
 111     validation = ! isempty (opts);
 112     lopts = tolower (opts);
 113     for [val, key] = new
 114       if (validation)
 115         ## Case insensitive lookup in all options.
 116         i = lookup (lopts, tolower (key));
 117         ## Validate option.
 118         if (i > 0 && strcmpi (opts{i}, key))
 119           ## Use correct case.
 120           key = opts{i};
 121         else
 122           warning ("unrecognized option: %s", key);
 123         endif
 124       endif
 125       old.(key) = val;
 126     endfor
 127     retval = old;
 128   elseif (rem (nargs, 2) && isstruct (varargin{1}))
 129     ## Set values in old from name/value pairs.
 130     pairs = reshape (varargin(2:end), 2, []);
 131     retval = optimset (varargin{1}, cell2struct (pairs(2, :), pairs(1, :), 2));
 132   elseif (rem (nargs, 2) == 0)
 133     ## Create struct.  Default values are replaced by those specified by
 134     ## name/value pairs.
 135     pairs = reshape (varargin, 2, []);
 136     retval = optimset (struct (), cell2struct (pairs(2, :), pairs(1, :), 2));
 137   else
 138     print_usage ();
 139   endif
 140
 141 endfunction
 142
 143
 144 %!assert (optimget (optimset ('tolx', 1e-2), 'tOLx'), 1e-2)
 145 %!assert (isfield (optimset ('tolFun', 1e-3), 'TolFun'))
 146
 147 %!error (optimset ("%NOT_A_REAL_FUNCTION_NAME%"))
 148