minimize

(uc_optim/minimize.m)

Function Synopsis

[x,v,nev,...] = minimize (f,args,...)

Help text

 [x,v,nev,...] = minimize (f,args,...) - Minimize f

 ARGUMENTS
 f    : string  : Name of function. Must return a real value
 args : list or : List of arguments to f (by default, minimize the first)
        matrix  : f's only argument

 RETURNED VALUES
 x   : matrix  : Local minimum of f. Let's suppose x is M-by-N.
 v   : real    : Value of f in x0
 nev : integer : Number of function evaluations 
     or 1 x 2  : Number of function and derivative evaluations (if
                 derivatives are used)

 OPTIONS : DERIVATIVES   You may provide one of the following options.
 ---------------------   Otherwise, the Nelder-Mean (see nelder_mead_min)
                         method is used.

 'df' , df      : Name of a function that returns the derivatives of f
                  in x : [dfx] = feval (df, x) where dfx is 1x(M*N). The
                  conjugate gradient method (see cg_min) will be used.

 'd2f', d2f     : Name of a function that returns the value of f, of its
                  1st and 2nd derivatives : [fx,dfx,d2fx] = feval (d2f, x)
                  where fx is a real number, dfx is 1x(M*N) and d2fx is
                  (M*N)x(M*N). A Newton-like method (d2_min) will be used.

 'd2i', d2i     : Name of a function that returns the value of f, of its
                  1st and pseudo-inverse of second derivatives : 
                  [fx,dfx,id2ix] = feval (d2i, x) where fx is a real
                  number, dfx is 1x(M*N) and d2ix is (M*N)x(M*N).
                  A Newton-like method will be used (see d2_min).

            NOTE : df, d2f or d2i take the same arguments as f.

 OPTIONS : STOPPING CRITERIA  Default is to use 'tol'
 ---------------------------
 'tol', tol     : Stop search when value doesn't improve, as tested by

              ftol > Deltaf/max(|f(x)|,1)

                 where Deltaf is the decrease in f observed in the last
                 iteration.                                 Default=10*eps

 'ftol', ftol   : Stop search when updates are small, as tested by

              tol > max { dx(i)/max(|x(i)|,1) | i in 1..N }

                 where  dx is the change in the x that occured in the last
                 iteration.

 'gtol',gtol    : Stop search when derivatives are small, as tested by

              gtol > max { df(i)*max(|x(i)|,1)/max(v,1) | i in 1..N }

                 where x is the current minimum, v is func(x) and df is
                 the derivative of f in x. This option is ignored if
                 derivatives are not used in optimization.

 MISC. OPTIONS
 -------------
 'maxev', m     : Maximum number of iterations               Default=inf

 'narg',  narg  : Position of the minimized argument in args Default=1

Listing of function file uc_optim/minimize.m

## [x,v,nev,...] = minimize (f,args,...) - Minimize f
##
## ARGUMENTS
## f    : string  : Name of function. Must return a real value
## args : list or : List of arguments to f (by default, minimize the first)
##        matrix  : f's only argument
##
## RETURNED VALUES
## x   : matrix  : Local minimum of f. Let's suppose x is M-by-N.
## v   : real    : Value of f in x0
## nev : integer : Number of function evaluations 
##     or 1 x 2  : Number of function and derivative evaluations (if
##                 derivatives are used)
## 
## OPTIONS : DERIVATIVES   You may provide one of the following options.
## ---------------------   Otherwise, the Nelder-Mean (see nelder_mead_min)
##                         method is used.
## 
## 'df' , df      : Name of a function that returns the derivatives of f
##                  in x : [dfx] = feval (df, x) where dfx is 1x(M*N). The
##                  conjugate gradient method (see cg_min) will be used.
##
## 'd2f', d2f     : Name of a function that returns the value of f, of its
##                  1st and 2nd derivatives : [fx,dfx,d2fx] = feval (d2f, x)
##                  where fx is a real number, dfx is 1x(M*N) and d2fx is
##                  (M*N)x(M*N). A Newton-like method (d2_min) will be used.
##
##
## 'd2i', d2i     : Name of a function that returns the value of f, of its
##                  1st and pseudo-inverse of second derivatives : 
##                  [fx,dfx,id2ix] = feval (d2i, x) where fx is a real
##                  number, dfx is 1x(M*N) and d2ix is (M*N)x(M*N).
##                  A Newton-like method will be used (see d2_min).
##
##            NOTE : df, d2f or d2i take the same arguments as f.
## 
## OPTIONS : STOPPING CRITERIA  Default is to use 'tol'
## ---------------------------
## 'tol', tol     : Stop search when value doesn't improve, as tested by
##
##              ftol > Deltaf/max(|f(x)|,1)
##
##                 where Deltaf is the decrease in f observed in the last
##                 iteration.                                 Default=10*eps
##
## 'ftol', ftol   : Stop search when updates are small, as tested by
##
##              tol > max { dx(i)/max(|x(i)|,1) | i in 1..N }
##
##                 where  dx is the change in the x that occured in the last
##                 iteration.
##
## 'gtol',gtol    : Stop search when derivatives are small, as tested by
##
##              gtol > max { df(i)*max(|x(i)|,1)/max(v,1) | i in 1..N }
##
##                 where x is the current minimum, v is func(x) and df is
##                 the derivative of f in x. This option is ignored if
##                 derivatives are not used in optimization.
##
## MISC. OPTIONS
## -------------
## 'maxev', m     : Maximum number of iterations               Default=inf
##
## 'narg',  narg  : Position of the minimized argument in args Default=1
function [x,v,nev,...] = minimize (f,args,...)

verbose = 0;

df = d2f = d2i = "";
tol = ftol = gtol = nan;

crit = tol = narg = maxev = nan;

# ####################################################################
# Read the options ###################################################
# ####################################################################
# Options with a value
opt1 = " tol ftol gtol df d2f d2i maxev narg " ;
# Boolean options 
opt0 = " verbose " ;
filename = "minimize";

va_start() ;
nargin = nargin - 2 ;

read_options

if     ! isnan (tol) , crit = 1;
elseif ! isnan (ftol), crit = 2; tol = ftol;
elseif ! isnan (gtol), crit = 3; tol = gtol;
end

if     length (d2i), method = "d2_min"; 
elseif length (d2f), method = "d2_min", 
elseif length (df),  method = "cg_min";
else                 method = "nelder_mead_min";
end


ctl = nan*zeros (1,6);
ctl(1) = crit;
ctl(2) = tol;
ctl(3) = narg;
ctl(4) = maxev;

if strcmp (method, "d2_min"),
  ctl = ctl(1:5); 
  if length (d2i), ctl(5) = 1; d2f = d2i; end
  [x, v, nev, h] = d2_min (f, d2f, args, ctl);
  if nargout > 3, vr_val (h); end
  
elseif strcmp (method, "cg_min")
  ctl = ctl(1:4);
  [x, v, nev] = cg_min (f, df, args, ctl);
else 
  [x, v, nev] = nelder_mead_min (f, args, ctl);
end