% 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.
%
% Interface has been written by Peter Carbonetto.
% Compilation instructions by Hannes Nickisch, 2010-07-19
function x = lbfgsb(x,varargin)
  
  fprintf('\n\n\n')
  fprintf('##########################################################################\n')
  fprintf('In order to use the L-BFGS minimiser you have to compile Peter Carbonetto''s\n')
  fprintf('"Matlab interface for L-BFGS-B" [1]. The challenge here is the Fortran 77 code.\n')
  fprintf('We provide a Makefile suitable for Linux 32/64 bit and Mac whenever you have g77\n')
  fprintf('properly installed.Under Ubuntu, you can achieve this by installing the package\n')
  fprintf('fort77, for example.\n\n')

  fprintf('Compilation is done by editing lbfgsb/Makefile. In any case, you need to\n')
  fprintf('provide MATLAB_HOME which can be found by the commands ''locate matlab'' or \n')
  fprintf('''find / -name "matlab"''. You can choose between two compilation modes:\n')
  fprintf('a) using the mex utility by Matlab                                     [default]\n')
  fprintf('   provide MEX, then type ''make mex''\n\n')

  fprintf('b) without mex utility by Matlab\n')
  fprintf('  provide MEX_SUFFIX and MATLAB_LIB, then type ''make nomex''\n\n')

  fprintf('In Ubuntu 10.04 LTS, the libg2c library needed for both a) and b) is not\n')
  fprintf('included per default. If ''ls /usr/lib/libg2c.*'' does not list anything\n')
  fprintf('this is the case on your machine. You then whant to install the packages\n')
  fprintf('gcc-3.4-base and libg2c0 e.g. from\n')
  fprintf('http://packages.ubuntu.com/hardy/gcc-3.4-base and\n')
  fprintf('http://packages.ubuntu.com/hardy/libg2c0.\n')
  fprintf('After installation, you have to create a symbolic link by ''cd /usr/lib'' and\n')
  fprintf('''ln -s libg2c.so.0 libg2c.so''.\n\n')

  fprintf('[1] http://www.cs.ubc.ca/~pcarbo/lbfgsb-for-matlab.html\n')
  fprintf('[2] http://www.mathworks.com/support/compilers/R2010a\n')
  fprintf('##########################################################################\n')
  fprintf('\n\n\n')
  
  error
