Man Linux: Main Page and Category List

lmstr_, lmstr1_ - minimize the sum of squares of m nonlinear functions, with user supplied Jacobian and minimal storage

include<minpack.h>voidlmstr1_(void(*fcn)(int*m,int*n,double*x,double*fvec,double*fjrow,int*iflag),int*m,int*n,double*x,double*fvec,double*fjac,int*ldfjac,double*tol,int*info,int*iwa,double*wa,int*kwa);voidlmstr_(void(*fcn)(int*m,int*n,double*x,double*fvec,double*fjrow,int*iflag),int*m,int*n,double*x,double*fvec,double*fjac,int*ldfjac,double*ftol,double*xtol,double*gtol,int*maxfev,double*diag,int*mode,double*factor,int*nprint,int*info,int*nfev,int*njev,int*ipvt,double*qtf,double*wa1,double*wa2,double*wa3,double*wa4);

The purpose oflmstr_is to minimize the sum of the squares ofmnonlinear functions innvariables by a modification of the Levenberg- Marquardt algorithm. The user must provide a function which calculates the functions and the rows of the Jacobian.lmstr1_performs the same function but has a simplified calling sequence.lmder(3) andlmder1(3) perform the same function but do not attempt to minimize storage.LanguagenotesThese functions are written in FORTRAN. If calling from C, keep these points in mind: Name mangling. Withg77version 2.95 or 3.0, all the function names end in an underscore. This may change with future versions ofg77. Compile withg77. Even if your program is all C code, you should link withg77so it will pull in the FORTRAN libraries automatically. It’s easiest just to useg77to do all the compiling. (It handles C just fine.) Call by reference. All function parameters must be pointers. Column-major arrays. Suppose a function returns an array with 5 rows and 3 columns in an arrayzand in the call you have declared a leading dimension of 7. The FORTRAN and equivalent C references are: z(1,1) z[0] z(2,1) z[1] z(5,1) z[4] z(1,2) z[7] z(1,3) z[14] z(i,j) z[(i-1) + (j-1)*7]User-suppliedFunctionfcnis the name of the user-supplied subroutine which calculates the functions. In FORTRAN,fcnmust be declared in an external statement in the user calling program, and should be written as follows: subroutine fcn(m,n,x,fvec,fjrow,iflag) integer m,n,iflag double precision x(n),fvec(m),fjrow(n) ---------- if iflag = 1 calculate the functions at x and return this vector in fvec. Do not alter fjac. if iflag = i calculate row (i-1) of the Jacobian at x and return this vector in fjrow. ---------- return end In C,fcnshould be written as follows: void fcn(int m, int n, double *x, double *fvec, double *fjrow, int *iflag) { /* If iflag = 1 calculate the functions at x and return the values in fvec[0] through fvec[m-1]. Do not alter fjac. If iflag = i calculate row (i-1) of the Jacobian at x and return the vector in fjrow. */ }iflagis an input integer which specifies whether a function value or Jacobian row is to be calculated. The value ofiflagshould not be changed byfcnunless the user wants to terminate execution oflmstr_(orlmstr1_). In this case setiflagto a negative integer.Parametersforbothlmstr_andlmstr1_mis a positive integer input variable set to the number of functions.nis a positive integer input variable set to the number of variables.nmust not exceedm.xis an array of lengthn. On inputxmust contain an initial estimate of the solution vector. On outputxcontains the final estimate of the solution vector.fvecis an output array of lengthmwhich contains the functions evaluated at the outputx.fjrowis an output array of lengthnwhich is set to one row of the Jacobian evaluated atx.fjacis an outputmbynarray. The uppernbynsubmatrix offjaccontains an upper triangular matrixrwith diagonal elements of nonincreasing magnitude such that t t t p *(jac *jac)*p = r *r, wherepis a permutation matrix andjacis the final calculated Jacobian. Columnjofpis columnipvt(j) (see below) of the identity matrix. The lower trapezoidal part offjaccontains information generated during the computation ofr.ldfjacis a positive integer input variable not less thanmwhich specifies the leading dimension of the arrayfjac.Parametersforlmstr1_tolis a nonnegative input variable. Termination occurs when the algorithm estimates either that the relative error in the sum of squares is at mosttolor that the relative error betweenxand the solution is at mosttol.infois an integer output variable. if the user has terminated execution,infois set to the (negative) value of iflag. see description offcn. otherwise,infois set as follows.info= 0 improper input parameters.info= 1 algorithm estimates that the relative error in the sum of squares is at mosttol.info= 2 algorithm estimates that the relative error between x and the solution is at mosttol.info= 3 conditions forinfo= 1 andinfo= 2 both hold.info= 4fvecis orthogonal to the columns of the Jacobian to machine precision.info= 5 number of calls tofcnhas reached or exceeded 100*(n+1).info= 6tolis too small. no further reduction in the sum of squares is possible.info= 7tolis too small. no further improvement in the approximate solution x is possible.wais a work array of lengthlwa.lwais an integer input variable not less thanm*n+ 5*n+mforlmder1, or 5*n+mforlmstr1_.Parametersforlmstr_ftolis a nonnegative input variable. Termination occurs when both the actual and predicted relative reductions in the sum of squares are at mostftol. Therefore,ftolmeasures the relative error desired in the sum of squares.xtolis a nonnegative input variable. Termination occurs when the relative error between two consecutive iterates is at mostxtol. Therefore,xtolmeasures the relative error desired in the approximate solution.gtolis a nonnegative input variable. Termination occurs when the cosine of the angle betweenfvecand any column of the Jacobian is at mostgtolin absolute value. Therefore,gtolmeasures the orthogonality desired between the function vector and the columns of the Jacobian.maxfevis a positive integer input variable. Termination occurs when the number of calls tofcnis at leastmaxfevby the end of an iteration.diagis an array of lengthn. Ifmode= 1 (see below),diagis internally set. Ifmode= 2,diagmust contain positive entries that serve as multiplicative scale factors for the variables.modeis an integer input variable. Ifmode= 1, the variables will be scaled internally. Ifmode= 2, the scaling is specified by the inputdiag. Other values of mode are equivalent tomode= 1.factoris a positive input variable used in determining the initial step bound. This bound is set to the product offactorand the euclidean norm ofdiag*xif the latter is nonzero, or else tofactoritself. In most cases factor should lie in the interval (.1,100.). 100. is a generally recommended value.nprintis an integer input variable that enables controlled printing of iterates if it is positive. In this case, fcn is called withiflag= 0 at the beginning of the first iteration and everynprintiterations thereafter and immediately prior to return, withxandfvecavailable for printing. Ifnprintis not positive, no special calls of fcn withiflag= 0 are made.infois an integer output variable. If the user has terminated execution, info is set to the (negative) value of iflag. See description of fcn. Otherwise, info is set as follows.info= 0 improper input parameters.info= 1 both actual and predicted relative reductions in the sum of squares are at mostftol.info= 2 relative error between two consecutive iterates is at mostxtol.info= 3 conditions forinfo= 1 andinfo= 2 both hold.info= 4 the cosine of the angle between fvec and any column of the Jacobian is at most gtol in absolute value.info= 5 number of calls tofcnhas reached or exceeded maxfev.info= 6ftolis too small. No further reduction in the sum of squares is possible.info= 7xtolis too small. No further improvement in the approximate solution x is possible.info= 8gtolis too small.fvecis orthogonal to the columns of the Jacobian to machine precision.nfevis an integer output variable set to the number of calls tofcnwithiflag= 1.njevis an integer output variable set to the number of calls to fcn withiflag= 2.ipvtis an integer output array of lengthn.ipvtdefines a permutation matrixpsuch thatjac*p=q*r, wherejacis the final calculated Jacobian,qis orthogonal (not stored), andris upper triangular with diagonal elements of nonincreasing magnitude. Columnjofpis columnipvt(j) of the identity matrix.qtfis an output array of lengthnwhich contains the firstnelements of the vector (qtranspose)*fvec.wa1,wa2, andwa3are work arrays of lengthn.wa4is a work array of lengthm.

lmdif(3),lmdif1(3),lmder(3),lmder1(3).

Jorge More’, Burt Garbow, and Ken Hillstrom at Argonne National Laboratory. This manual page was written by Jim Van Zandt <jrv@debian.org>, for the Debian GNU/Linux system (but may be used by others).