% LBFGSB Call the nonlinear bound-constrained solver that uses
% limited-memory BFGS quasi-Newton updates.
%
% The basic function call is
%
% LBFGSB(x0,lb,ub,objfunc,gradfunc)
%
% The first input argument x0 is either a matrix or a cell array of
% matrices. It declares the starting point for the solver.
%
% The second and third input arguments lb and ub must be of the exact same
% structure as x0. They declare the lower and upper bounds on the
% variables, respectively. Set an entry to Inf to declare no bound.
%
% The next two input arguments must be the names of MATLAB routines
% (M-files):
%
% objfunc Calculates the objective function at the current
% point. The routine must accept as many inputs as cell
% entry in x0 (or one input if x0 is a matrix). The
% output must be a scalar representing the objective
% evaluated at the current point.
%
% gradfunc Computes the gradient of the objective at the current
% point. The input is the same as objfunc, but it must
% return as many outputs as there are inputs, and each
% of the outputs have the same matrix structure as its
% corresponding input.
%
% Optionally, one may choose to pass additional auxiliary data to the
% MATLAB callback routines listed above through the function call
% LBFGSB(...,auxdata). If auxdata is the empty matrix, no extra
% information is passed. It is important to observe that the auxiliary
% data MAY NOT CHANGE through the course of the L-BFGS optimization! The
% auxiliary data keep the same values as they possessed in the initial
% call. If you need variables that change over time, you may want to
% consider global variables (type HELP GLOBAL).
%
% LBFGSB(...,auxdata,iterfunc) specifies an additional callback routine
% which is called once per algorithm iteration. The callback routine must
% take the form ITERFUNC(T,F,X1,X2,...,AUXDATA). T is the current
% iteration of the algorithm. F is the current value of the objective. The
% inputs X1, X2,... are exactly the same as the ones passed to objfunc and
% gradfunc. Finally, extra information may be passed through the input
% AUXDATA. No outputs are expected from iterfunc. If iterfunc is the empty
% string, no routine is called.
%
% These inputs may be followed by parameter/value pairs to modify the
% default algorithm options. The algorithm option 'maxiter' sets the
% maximum number of iterations. The rest of the options 'm', 'factr' and
% 'pgtol' are described in the L-BFGS-B documentation. Note that in this
% implementation we divide factr by the machine precision, so that the
% convergence condition is satisfied when it is less than factr, not less
% than factr times the machine precision.
