% [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)
%
%
% Extra arguments are either a succession of option-value pairs or a single
% list or struct of option-value pairs (for unary options, the value in the
% struct is ignored).
%
% OPTIONS : DERIVATIVES Derivatives may be used if one of these options
% --------------------- uesd. Otherwise, the Nelder-Mean (see
% nelder_mead_min) method is 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.
%
% 'hess' : Use [fx,dfx,d2fx] = leval (f, args) to compute 1st and
% 2nd derivatives, and use a Newton-like method (d2_min).
%
% 'd2i', d2i : Name of a function that returns the value of f, of its
% 1st and pseudo-inverse of second derivatives :
% [fx,dfx,id2fx] = 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).
%
% 'ihess' : Use [fx,dfx,id2fx] = leval (f, args) to compute 1st
% derivative and the pseudo-inverse of 2nd derivatives,
% and use a Newton-like method (d2_min).
%
% NOTE : df, d2f or d2i take the same arguments as f.
%
% 'order', n : Use derivatives of order n. If the n'th order derivative
% is not specified by 'df', 'd2f' or 'd2i', it will be
% computed numerically. Currently, only order 1 works.
%
% 'ndiff' : Use a variable metric method (bfgs) using numerical
% differentiation.
%
% OPTIONS : STOPPING CRITERIA Default is to use 'tol'
% ---------------------------
% 'ftol', ftol : 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
%
% 'utol', utol : 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.
%
% 'dtol',dtol : Stop search when derivatives are small, as tested by
%
% dtol > 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 function evaluations <inf>
%
% 'narg' , narg : Position of the minimized argument in args <1>
% 'isz' , step : Initial step size (only for 0 and 1st order method) <1>
% Should correspond to expected distance to minimum
% 'verbose' : Display messages during execution
%
% 'backend' : Instead of performing the minimization itself, return
% [backend, control], the name and control argument of the
% backend used by minimize. Minimimzation can then be
% obtained without the overhead of minimize by calling, if
% a 0 or 1st order method is used :
%
% [x,v,nev] = feval (backend, args, control)
%
% or, if a 2nd order method is used :
%
% [x,v,nev] = feval (backend, control.d2f, args, control)
%