1  % LEVMAR matlab MEX interface to the levmar nonlinear least squares minimization


2  % library available from http://www.ics.forth.gr/~lourakis/levmar/


3  %


4  % Usage: levmar can be used in any of the 8 following ways:


5  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'unc', ...)


6  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'bc', lb, ub, ...)


7  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'lec', A, b, ...)


8  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'blec', lb, ub, A, b, wghts, ...)


9  %


10  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'bleic', lb, ub, A, b, C, d, ...)


11  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'blic', lb, ub, C, d, ...)


12  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'leic', A, b, C, d, ...)


13  % [ret, popt, info, covar]=levmar(fname, jacname, p0, x, itmax, opts, 'lic', C, d, ...)


14  %


15  %


16  % The dots at the end denote any additional, problem specific data that are passed uninterpreted to


17  % all invocations of fname and jacname, see below for details.


18  %


19  % In the following, the word "vector" is meant to imply either a row or a column vector.


20  %


21  % required input arguments:


22  %  fname: String defining the name of a matlab function implementing the function to be minimized.


23  % fname will be called as fname(p, ...), where p denotes the parameter vector and the dots any


24  % additional data passed as extra arguments during the invocation of levmar (refer to Meyer's


25  % problem in lmdemo.m for an example).


26  %


27  %  p0: vector of doubles holding the initial parameters estimates.


28  %


29  %  x: vector of doubles holding the measurements vector.


30  %


31  %  itmax: maximum number of iterations.


32  %


33  %  opts: vector of doubles specifying the minimization parameters, as follows:


34  % opts(1) scale factor for the initial damping factor


35  % opts(2) stopping threshold for J^T e_inf


36  % opts(3) stopping threshold for Dp_2


37  % opts(4) stopping threshold for e_2


38  % opts(5) step used in finite difference approximation to the Jacobian.


39  % If an empty vector (i.e. []) is specified, defaults are used.


40  %


41  % optional input arguments:


42  %  jacname: String defining the name of matlab function implementing the Jacobian of function fname.


43  % jacname will be called as jacname(p, ...) where p is again the parameter vector and the dots


44  % denote any additional data passed as extra arguments to the invocation of levmar. If omitted,


45  % the Jacobian is approximated with finite differences through repeated invocations of fname.


46  %


47  %  type: String defining the minimization type. It should be one of the following:


48  % 'unc' specifies unconstrained minimization.


49  % 'bc' specifies minimization subject to box constraints.


50  % 'lec' specifies minimization subject to linear equation constraints.


51  % 'blec' specifies minimization subject to box and linear equation constraints.


52  % 'bleic' specifies minimization subject to box, linear equation and inequality constraints.


53  % 'blic' specifies minimization subject to box and linear inequality constraints.


54  % 'leic' specifies minimization subject to linear equation and inequality constraints.


55  % 'lic' specifies minimization subject to linear inequality constraints.


56  % If omitted, a default of 'unc' is assumed. Depending on the minimization type, the MEX


57  % interface will invoke one of dlevmar_XXX, dlevmar_bc_XXX, dlevmar_lec_XXX, dlevmar_blec_XXX or dlevmar_bleic_XXX


58  %


59  %  lb, ub: vectors of doubles specifying lower and upper bounds for p, respectively


60  %


61  %  A, b: k x m matrix and k vector specifying linear equation constraints for p, i.e. A*p=b


62  % A should have full rank.


63  %


64  %  C, d: k x m matrix and k vector specifying linear inequality constraints for p, i.e. C*p>=d


65  % A should have full rank.


66  %


67  %  wghts: vector of doubles specifying the weights for the penalty terms corresponding to


68  % the box constraints, see lmblec_core.c for more details. If omitted and a 'blec' type


69  % minimization is to be carried out, default weights are used.


70  %


71  %


72  % output arguments


73  %  ret: return value of levmar, corresponding to the number of iterations if successful, 1 otherwise.


74  %


75  %  popt: estimated minimizer, i.e. minimized parameters vector.


76  %


77  %  info: optional array of doubles, which upon return provides information regarding the minimization.


78  % See lm_core.c for more details.


79  %


80  %  covar: optional covariance matrix corresponding to the estimated minimizer.


81  %


82 


83  error('levmar.m is used only for providing documentation to levmar; make sure that levmar.c has been compiled using mex');

