Original FORTRAN documentation
==============================
|
|    subroutine lmdif
|
|    the purpose of lmdif is to minimize the sum of the squares of
|    m nonlinear functions in n variables by a modification of
|    the levenberg-marquardt algorithm. the user must provide a
|    subroutine which calculates the functions. the jacobian is
|    then calculated by a forward-difference approximation.
|
|    the subroutine statement is
|
|      subroutine lmdif(fcn,m,n,x,fvec,ftol,xtol,gtol,maxfev,epsfcn,
|                       diag,mode,factor,nprint,info,nfev,fjac,
|                       ldfjac,ipvt,qtf,wa1,wa2,wa3,wa4)
|
|    where
|
|      fcn is the name of the user-supplied subroutine which
|        calculates the functions. fcn must be declared
|        in an external statement in the user calling
|        program, and should be written as follows.
|
|        subroutine fcn(m,n,x,fvec,iflag)
|        integer m,n,iflag
|        double precision x(n),fvec(m)
|        ----------
|        calculate the functions at x and
|        return this vector in fvec.
|        ----------
|        return
|        end
|
|        the value of iflag should not be changed by fcn unless
|        the user wants to terminate execution of lmdif.
|        in this case set iflag to a negative integer.
|
|      m is a positive integer input variable set to the number
|        of functions.
|
|      n is a positive integer input variable set to the number
|        of variables. n must not exceed m.
|
|      x is an array of length n. on input x must contain
|        an initial estimate of the solution vector. on output x
|        contains the final estimate of the solution vector.
|
|      fvec is an output array of length m which contains
|        the functions evaluated at the output x.
|
|      ftol is a nonnegative input variable. termination
|        occurs when both the actual and predicted relative
|        reductions in the sum of squares are at most ftol.
|        therefore, ftol measures the relative error desired
|        in the sum of squares.
|
|      xtol is a nonnegative input variable. termination
|        occurs when the relative error between two consecutive
|        iterates is at most xtol. therefore, xtol measures the
|        relative error desired in the approximate solution.
|
|      gtol is a nonnegative input variable. termination
|        occurs when the cosine of the angle between fvec and
|        any column of the jacobian is at most gtol in absolute
|        value. therefore, gtol measures the orthogonality
|        desired between the function vector and the columns
|        of the jacobian.
|
|      maxfev is a positive integer input variable. termination
|        occurs when the number of calls to fcn is at least
|        maxfev by the end of an iteration.
|
|      epsfcn is an input variable used in determining a suitable
|        step length for the forward-difference approximation. this
|        approximation assumes that the relative errors in the
|        functions are of the order of epsfcn. if epsfcn is less
|        than the machine precision, it is assumed that the relative
|        errors in the functions are of the order of the machine
|        precision.
|
|      diag is an array of length n. if mode = 1 (see
|        below), diag is internally set. if mode = 2, diag
|        must contain positive entries that serve as
|        multiplicative scale factors for the variables.
|
|      mode is an integer input variable. if mode = 1, the
|        variables will be scaled internally. if mode = 2,
|        the scaling is specified by the input diag. other
|        values of mode are equivalent to mode = 1.
|
|      factor is a positive input variable used in determining the
|        initial step bound. this bound is set to the product of
|        factor and the euclidean norm of diag\*x if nonzero, or else
|        to factor itself. in most cases factor should lie in the
|        interval (.1,100.). 100. is a generally recommended value.
|
|      nprint is an integer input variable that enables controlled
|        printing of iterates if it is positive. in this case,
|        fcn is called with iflag = 0 at the beginning of the first
|        iteration and every nprint iterations thereafter and
|        immediately prior to return, with x and fvec available
|        for printing. if nprint is not positive, no special calls
|        of fcn with iflag = 0 are made.
|
|      info is 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 most ftol.
|
|        info = 2  relative error between two consecutive iterates
|                  is at most xtol.
|
|        info = 3  conditions for info = 1 and info = 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 to fcn has reached or
|                  exceeded maxfev.
|
|        info = 6  ftol is too small. no further reduction in
|                  the sum of squares is possible.
|
|        info = 7  xtol is too small. no further improvement in
|                  the approximate solution x is possible.
|
|        info = 8  gtol is too small. fvec is orthogonal to the
|                  columns of the jacobian to machine precision.
|
|      nfev is an integer output variable set to the number of
|        calls to fcn.
|
|      fjac is an output m by n array. the upper n by n submatrix
|        of fjac contains an upper triangular matrix r with
|        diagonal elements of nonincreasing magnitude such that
|
|               t    t         t
|              p \*(jac \*jac)\*p = r \*r,
|
|        where p is a permutation matrix and jac is the final
|        calculated jacobian. column j of p is column ipvt(j)
|        (see below) of the identity matrix. the lower trapezoidal
|        part of fjac contains information generated during
|        the computation of r.
|
|      ldfjac is a positive integer input variable not less than m
|        which specifies the leading dimension of the array fjac.
|
|      ipvt is an integer output array of length n. ipvt
|        defines a permutation matrix p such that jac\*p = q\*r,
|        where jac is the final calculated jacobian, q is
|        orthogonal (not stored), and r is upper triangular
|        with diagonal elements of nonincreasing magnitude.
|        column j of p is column ipvt(j) of the identity matrix.
|
|      qtf is an output array of length n which contains
|        the first n elements of the vector (q transpose)\*fvec.
|
|      wa1, wa2, and wa3 are work arrays of length n.
|
|      wa4 is a work array of length m.
|
|    subprograms called
|
|      user-supplied ...... fcn
|
|      minpack-supplied ... dpmpar,enorm,fdjac2,,qrfac
|
|      fortran-supplied ... dabs,dmax1,dmin1,dsqrt,mod
|
|    argonne national laboratory. minpack project. march 1980.
|    burton s. garbow, kenneth e. hillstrom, jorge j. more