octave_packages/optim-1.2.0/fminunc_compat.m

   1 ## Copyright (C) 2002 Etienne Grossmann <etienne@egdn.net>
   2 ##
   3 ## This program is free software; you can redistribute it and/or modify it under
   4 ## the terms of the GNU General Public License as published by the Free Software
   5 ## Foundation; either version 3 of the License, or (at your option) any later
   6 ## version.
   7 ##
   8 ## This program is distributed in the hope that it will be useful, but WITHOUT
   9 ## ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  10 ## FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
  11 ## details.
  12 ##
  13 ## You should have received a copy of the GNU General Public License along with
  14 ## this program; if not, see <http://www.gnu.org/licenses/>.
  15
  16 ## [x,v,flag,out,df,d2f] = fminunc_compat (f,x,opt,...) - M*tlab-like optimization
  17 ##
  18 ## Imitation of m*tlab's fminunc(). The optional 'opt' argument is a struct,
  19 ## e.g. produced by 'optimset()'. 'fminunc_compat' has been deprecated in
  20 ## favor of 'fminunc', which is now part of core Octave. This function
  21 ## will possibly be removed from future versions of the 'optim' package.
  22 ##
  23 ## Supported options
  24 ## -----------------
  25 ## Diagnostics, [off|on] : Be verbose
  26 ## Display    , [off|iter|notify|final]
  27 ##                       : Be verbose unless value is "off"
  28 ## GradObj    , [off|on] : Function's 2nd return value is derivatives
  29 ## Hessian    , [off|on] : Function's 2nd and 3rd return value are
  30 ##                         derivatives and Hessian.
  31 ## TolFun     , scalar   : Termination criterion (see 'ftol' in minimize())
  32 ## TolX       , scalar   : Termination criterion (see 'utol' in minimize())
  33 ## MaxFunEvals, int      : Max. number of function evaluations
  34 ## MaxIter    , int      : Max. number of algorithm iterations
  35 ##
  36 ## These non-m*tlab are provided to facilitate porting code to octave:
  37 ## -----------------------
  38 ## "MinEquiv" , [off|on] : Don't minimize 'fun', but instead return the
  39 ##                         option passed to minimize().
  40 ##
  41 ## "Backend"  , [off|on] : Don't minimize 'fun', but instead return
  42 ##                         [backend, opt], the name of the backend
  43 ##                         optimization function that is used and the
  44 ##                         optional arguments that will be passed to it. See
  45 ##                         the 'backend' option of minimize().
  46 ##
  47 ## This function is a front-end to minimize().
  48
  49 function [x,fval,flag,out,df,d2f] = fminunc_compat (fun,x0,opt,varargin)
  50
  51   persistent warned = false;
  52   if (! warned)
  53     warned = true;
  54     warning ("Octave:deprecated-function",
  55              "`fminunc_compat' has been deprecated, and will be removed in the future. Use `fminunc' from Octave core instead.");
  56   endif
  57
  58 if nargin < 3, opt = struct (); end
  59 if nargin > 3,
  60   args = {x0, varargin{:}};
  61 else
  62   args = {x0};
  63 end
  64
  65 ## Do some checks ####################################################
  66 ws = es = "";
  67
  68 ## Check for unknown options
  69 ## All known options
  70 opn = [" DerivativeCheck Diagnostics DiffMaxChange DiffMinChange",\
  71        " Display GoalsExactAchieve GradConstr GradObj Hessian HessMult",\
  72        " HessPattern HessUpdate Jacobian JacobMult JacobPattern",\
  73        " LargeScale LevenbergMarquardt LineSearchType MaxFunEvals MaxIter",\
  74        " MaxPCGIter MeritFunction MinAbsMax PrecondBandWidth TolCon",\
  75        " TolFun TolPCG TolX TypicalX ",\
  76        " MinEquiv Backend "];
  77
  78 for [v,k] = opt
  79   if ! findstr ([" ",k," "],opn)
  80     es = [es,sprintf("Unknown option '%s'\n",k)];
  81   end
  82 end
  83 ## Check for ignored options
  84 ## All ignored options
  85 iop = [" DerivativeCheck DiffMaxChange DiffMinChange",\
  86        " Display GoalsExactAchieve GradConstr HessMult",\
  87        " HessPattern HessUpdate JacobMult JacobPattern",\
  88        " LargeScale LevenbergMarquardt LineSearchType",\
  89        " MaxPCGIter MeritFunction MinAbsMax PrecondBandWidth TolCon",\
  90        " TolPCG TypicalX "];
  91 for [v,k] = opt
  92   if ! findstr ([" ",k," "],iop)
  93     ws = [ws,sprintf("Ignoring option '%s'\n",k)];
  94   end
  95 end
  96
  97 if length (ws) && ! length (es), warning (ws);
  98 elseif              length (es), error ([ws,es]);
  99 end
 100
 101 ## Transform fminunc options into minimize() options
 102
 103 opm = struct();         # minimize() options
 104
 105 equiv = struct ("TolX"       , "utol"   , "TolFun"     , "ftol",\
 106                 "MaxFunEvals", "maxev"  , "MaxIter"    , "maxit",\
 107                 "GradObj"    , "jac"    , "Hessian"    , "hess",\
 108                 "Display"    , "verbose", "Diagnostics", "verbose",\
 109                 "Backend"    , "backend");
 110
 111 for [v,k] = equiv
 112   if isfield (opt,k)
 113     opm = setfield (opm, getfield(equiv,k), getfield(opt,k));
 114   end
 115 end
 116
 117                                 # Transform "off" into 0, other strings into
 118                                 # 1.
 119 for [v,k] = opm
 120   if ischar (v)
 121     if strcmp (v,"off")
 122       opm = setfield (opm, k,0);
 123     else
 124       opm = setfield (opm, k,1);
 125     end
 126   end
 127 end
 128
 129 unary_opt = " hess jac backend verbose ";
 130 opml = {};
 131 for [v,k] = opm
 132   if findstr ([" ",k," "], unary_opt)
 133     opml(end+1) = {k};          # append k
 134   else
 135     opml(end+[1,2]) = {k,v};    # append k and v
 136   end
 137 end
 138                                 # Return only options to minimize() ##
 139 if isfield (opt, "MinEquiv")
 140   x = opml;
 141   if nargout > 1
 142     warning ("Only 1 return value is defined with the 'MinEquiv' option");
 143   end
 144   return
 145                                 # Use the backend option #############
 146 elseif isfield (opm, "backend")
 147   [x,fval] = minimize (fun, args, opml);
 148   if nargout > 2
 149     warning ("Only 2 return values are defined with the 'Backend' option");
 150   end
 151   return
 152 else                            # Do the minimization ################
 153   [x,fval,out] = minimize (fun, args, opml);
 154
 155   if isfield (opm, "maxev")
 156     flag = out(1) < getfield(opm,"maxev");
 157   else
 158     flag = 1;
 159   end
 160
 161   if nargout > 4
 162     [dummy,df,d2f] = feval (fun, x, args{2:end});
 163   elseif nargout > 3
 164     [dummy,df] = feval (fun, x, args{2:end});
 165   end
 166 end