octave_packages/optim-1.2.0/bfgsmin.m

   1 ## Copyright (C) 2006 Michael Creel <michael.creel@uab.es>
   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 ## bfgsmin: bfgs or limited memory bfgs minimization of function
  17 ##
  18 ## Usage: [x, obj_value, convergence, iters] = bfgsmin(f, args, control)
  19 ##
  20 ## The function must be of the form
  21 ## [value, return_2,..., return_m] = f(arg_1, arg_2,..., arg_n)
  22 ## By default, minimization is w.r.t. arg_1, but it can be done
  23 ## w.r.t. any argument that is a vector. Numeric derivatives are
  24 ## used unless analytic derivatives are supplied. See bfgsmin_example.m
  25 ## for methods.
  26 ##
  27 ## Arguments:
  28 ## * f: name of function to minimize (string)
  29 ## * args: a cell array that holds all arguments of the function
  30 ##      The argument with respect to which minimization is done
  31 ##      MUST be a vector
  32 ## * control: an optional cell array of 1-8 elements. If a cell
  33 ##   array shorter than 8 elements is provided, the trailing elements
  34 ##   are provided with default values.
  35 ##      * elem 1: maximum iterations  (positive integer, or -1 or Inf for unlimited (default))
  36 ##      * elem 2: verbosity
  37 ##              0 = no screen output (default)
  38 ##              1 = only final results
  39 ##              2 = summary every iteration
  40 ##              3 = detailed information
  41 ##      * elem 3: convergence criterion
  42 ##              1 = strict (function, gradient and param change) (default)
  43 ##              0 = weak - only function convergence required
  44 ##      * elem 4: arg in f_args with respect to which minimization is done (default is first)
  45 ##      * elem 5: (optional) Memory limit for lbfgs. If it's a positive integer
  46 ##              then lbfgs will be use. Otherwise ordinary bfgs is used
  47 ##      * elem 6: function change tolerance, default 1e-12
  48 ##      * elem 7: parameter change tolerance, default 1e-6
  49 ##      * elem 8: gradient tolerance, default 1e-5
  50 ##
  51 ## Returns:
  52 ## * x: the minimizer
  53 ## * obj_value: the value of f() at x
  54 ## * convergence: 1 if normal conv, other values if not
  55 ## * iters: number of iterations performed
  56 ##
  57 ## Example: see bfgsmin_example.m
  58
  59 function [parameter, obj, convergence, iters] = bfgsmin(f, f_args, control)
  60
  61         # check number and types of arguments
  62         if ((nargin < 2) || (nargin > 3))
  63                 usage("bfgsmin: you must supply 2 or 3 arguments");
  64         endif
  65         if (!ischar(f)) usage("bfgsmin: first argument must be string holding objective function name"); endif
  66         if (!iscell(f_args)) usage("bfgsmin: second argument must cell array of function arguments"); endif
  67         if (nargin > 2)
  68                 if (!iscell(control))
  69                         usage("bfgsmin: 3rd argument must be a cell array of 1-8 elements");
  70                 endif
  71                 if (length(control) > 8)
  72                         usage("bfgsmin: 3rd argument must be a cell array of 1-8 elements");
  73                 endif
  74         else control = {};
  75         endif
  76
  77         # provide defaults for missing controls
  78         if (length(control) == 0) control{1} = -1; endif # limit on iterations
  79         if (length(control) == 1) control{2} = 0; endif # level of verbosity
  80         if (length(control) == 2) control{3} = 1; endif # strong (function, gradient and parameter change) convergence required?
  81         if (length(control) == 3) control{4} = 1; endif # argument with respect to which minimization is done
  82         if (length(control) == 4) control{5} = 0; endif # memory for lbfgs: 0 uses ordinary bfgs
  83         if (length(control) == 5) control{6} = 1e-10; endif # tolerance for function convergence
  84         if (length(control) == 6) control{7} = 1e-6; endif # tolerance for parameter convergence
  85         if (length(control) == 7) control{8} = 1e-5; endif # tolerance for gradient convergence
  86
  87         # validity checks on all controls
  88         tmp = control{1};
  89         if (((tmp !=Inf) && (tmp != -1)) && (tmp > 0 && (mod(tmp,1) != 0)))
  90                 usage("bfgsmin: 1st element of 3rd argument (iteration limit) must be Inf or positive integer");
  91         endif
  92         tmp = control{2};
  93         if ((tmp < 0) || (tmp > 3) || (mod(tmp,1) != 0))
  94                 usage("bfgsmin: 2nd element of 3rd argument (verbosity level) must be 0, 1, 2, or 3");
  95         endif
  96         tmp = control{3};
  97         if ((tmp != 0) && (tmp != 1))
  98                 usage("bfgsmin: 3rd element of 3rd argument (strong/weak convergence) must be 0 (weak) or 1 (strong)");
  99         endif
 100         tmp = control{4};
 101         if ((tmp < 1) || (tmp > length(f_args)) || (mod(tmp,1) != 0))
 102                 usage("bfgsmin: 4th element of 3rd argument (arg with respect to which minimization is done) must be an integer that indicates one of the elements of f_args");
 103         endif
 104         tmp = control{5};
 105         if ((tmp < 0) || (mod(tmp,1) != 0))
 106                 usage("bfgsmin: 5th element of 3rd argument (memory for lbfgs must be zero (regular bfgs) or a positive integer");
 107         endif
 108         tmp = control{6};
 109         if (tmp < 0)
 110                 usage("bfgsmin: 6th element of 3rd argument (tolerance for function convergence) must be a positive real number");
 111         endif
 112         tmp = control{7};
 113         if (tmp < 0)
 114                 usage("bfgsmin: 7th element of 3rd argument (tolerance for parameter convergence) must be a positive real number");
 115         endif
 116         tmp = control{8};
 117         if (tmp < 0)
 118                 usage("bfgsmin: 8th element of 3rd argument (tolerance for gradient convergence) must be a positive real number");
 119         endif
 120
 121         # check that the parameter we minimize w.r.t. is a vector
 122         minarg = control{4};
 123         theta = f_args{minarg};
 124         theta = theta(:);
 125         if (!isvector(theta)) usage("bfgsmin: minimization must be done with respect to a vector of parameters"); endif
 126         f_args{minarg} = theta;
 127
 128         # now go ahead and do the minimization
 129         [parameter, obj, convergence, iters] = __bfgsmin(f, f_args, control);
 130 endfunction