% -*- texinfo -*-
% @deftypefn {Function File} {[@var{x0},@var{v},@var{nev}]} cg_min ( @var{f},@var{df},@var{args},@var{ctl} )
% NonLinear Conjugate Gradient method to minimize function @var{f}.
%
% @subheading Arguments
% @itemize @bullet
% @item @var{f} : string : Name of function. Return a real value
% @item @var{df} : string : Name of f's derivative. Returns a (R*C) x 1 vector
% @item @var{args}: cell : Arguments passed to f.@*
% @item @var{ctl} : 5-vec : (Optional) Control variables, described below
% @end itemize
%
% @subheading Returned values
% @itemize @bullet
% @item @var{x0} : matrix : Local minimum of f
% @item @var{v} : real : Value of f in x0
% @item @var{nev} : 1 x 2 : Number of evaluations of f and of df
% @end itemize
%
% @subheading Control Variables
% @itemize @bullet
% @item @var{ctl}(1) : 1 or 2 : Select stopping criterion amongst :
% @item @var{ctl}(1)==0 : Default value
% @item @var{ctl}(1)==1 : Stopping criterion : Stop search when value doesn't
% improve, as tested by @math{ ctl(2) > Deltaf/max(|f(x)|,1) }
% where Deltaf is the decrease in f observed in the last iteration
% (each iteration consists R*C line searches).
% @item @var{ctl}(1)==2 : Stopping criterion : Stop search when updates are small,
% as tested by @math{ ctl(2) > 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.
% @item @var{ctl}(2) : Threshold used in stopping tests. Default=10*eps
% @item @var{ctl}(2)==0 : Default value
% @item @var{ctl}(3) : Position of the minimized argument in args Default=1
% @item @var{ctl}(3)==0 : Default value
% @item @var{ctl}(4) : Maximum number of function evaluations Default=inf
% @item @var{ctl}(4)==0 : Default value
% @item @var{ctl}(5) : Type of optimization:
% @item @var{ctl}(5)==1 : 'Fletcher-Reves' method
% @item @var{ctl}(5)==2 : 'Polak-Ribiere' (Default)
% @item @var{ctl}(5)==3 : 'Hestenes-Stiefel' method
% @end itemize
%
% @var{ctl} may have length smaller than 4. Default values will be used if ctl is
% not passed or if nan values are given.
% @subheading Example:
%
% function r=df( l ) b=[1;0;-1]; r = -( 2*l@{1@} - 2*b + rand(size(l{1}))); @*
% function r=ff( l ) b=[1;0;-1]; r = (l@{1@}-b)' * (l@{1@}-b); @*
% ll = @{ [10; 2; 3] @}; @*
% ctl(5) = 3; @*
% [x0,v,nev]=cg_min( 'ff', 'df', ll, ctl ) @*
%
% Comment: In general, BFGS method seems to be better performin in many cases but requires more computation per iteration
% @seealso{ bfgsmin, http://en.wikipedia.org/wiki/Nonlinear_conjugate_gradient }
% @end deftypefn