MATLAB LBFGS wrapper v1.1 Copyright 2005-2006 Liam Stewart http://www.cs.toronto.edu/~liam/software.shtml Requirements ------------ MATLAB 7 or later is required. The L-BFGS code is not distributed with the wrapper; it can be obtained from: http://www.ece.northwestern.edu/~ciyou/code/lbcode.html routines.f from the L-BFGS tarball needs to be in the lbfgs directory before compilation. A C compiler and a fortran compiler are required to build the optimization routines and the wrapper. Both compilers must be supported by MATLAB. This software has been successfully tested on Intel machines running Red Hat Linux (using the GNU C and fortran compilers). I have had reports that the wrapper can be built and used on Windows. It should work on MacOS X provided that you have a supported fortran compiler (GNU fortran is not supported). Installation ------------ Unpack this package. Two directories will be created: lbfgs and LHSutils. lbfgs contains the lbfgs wrapper; LHSutils contains general utility functions needed by the wrapper. Copy the file routines.f from the L-BFGS distribution to the lbfgs directory. To build the mex files, start MATLAB, change to the lbfgs directory, and run the install_lbfgs script: cd /path/to/lbfgs install_lbfgs Both the lbfgs and the LHSutils directories should be added to the matlab search path (see the path command) in your ~/matlab/startup.m scripts. Usage ----- See lbfgs.m and test_lbfgs.m. A user-defined callback function can be passed to the optimization function through the options structure. A callback can be used to record values during the optimization process or implement special visualization routines. With anonymous functions and partial function application, it is possible to use callbacks to implement early stopping routines based on a validation set (for example, during training of machine learning models). The function is required to have the following signature: [stop,ud] = callback(x,iter,state,ud,opts) where x current value of the variable being optimized. iter a structure that contains information about the current iteration. At present this contains the following fields: it - iteration number f - function value at x g - gradient at x state a string describing where the optimization function is. It may be one of the following: init - the optimization process has yet to start iter - one iteration has finished done - the optimization process has finished ud user data. This is an arbitrary structure that the callback can user to store information. For example, the function may choose to store a history of the function values. When state is 'iter', the user data is an empty matrix. The function can initialize the structure as it sees fit. The contents are maintained between calls as the callback returns the user data, which the wrapper uses as the user data argument the next time the callback is called. opts the options structure. It can be used by the optimization process for any purpose (eg. allocation enough space to hold the a complete history of function values). stop indicates whether or not to stop the optimization process. A non-zero value indicates that optimization should be halted. A callback can use this to stop optmization early. The callback function is called exactly once before optimization is started (state = 'init'), a number of times during optimization, once per iteration (state = 'iter'), and exactly once before the wrapper returns (state = 'done'). Changes ------- Version 1.1: - Added ability to provide a user callback function. - Included missing files assert.m and process_options.m in distribution. - Included rosenbrock.m file. Version 1.0: - Initial release. License ------- The MATLAB LBFGS wrapper is distributed under the GNU GPL. See the file COPYING for details. The function rosenbrock.m is copyright Carl Rasmussen and is distributed under the following license: (C) Copyright 1999, 2000, 2001 & 2002, Carl Edward Rasmussen Permission is granted for anyone to copy, use, or modify these programs and accompanying documents for purposes of research or education, provided this copyright notice is retained, and note is made of any changes that have been made. These programs and documents are distributed without any warranty, express or implied. As the programs were written for research purposes only, they have not been tested to the degree that would be advisable in any important application. All use of these programs is entirely at the user's own risk. Contact Information ------------------- Liam Stewart liam@cs.toronto.edu http://www.cs.toronto.edu/~liam