Man Linux: Main Page and Category List

NAME

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

SYNOPSIS

       include <minpack.h>

       void lmstr1_ ( 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);

       void lmstr_ ( 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 );

DESCRIPTION

       The purpose of lmstr_ 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 function which  calculates
       the functions and the rows of the Jacobian.

       lmstr1_  performs  the  same  function  but  has  a  simplified calling
       sequence.

       lmder(3) and lmder1(3) perform the same function but do not attempt  to
       minimize storage.

   Language notes
       These  functions  are written in FORTRAN. If calling from C, keep these
       points in mind:

       Name mangling.
              With g77 version 2.95 or 3.0, all the function names end  in  an
              underscore.  This may change with future versions of g77.

       Compile with g77.
              Even  if your program is all C code, you should link with g77 so
              it will pull  in  the  FORTRAN  libraries  automatically.   It’s
              easiest  just to use g77 to 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 array z and 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-supplied Function
       fcn is the name of the user-supplied subroutine  which  calculates  the
       functions. In FORTRAN, 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,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, fcn should 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. */
         }

       iflag is an input integer which specifies whether a function  value  or
       Jacobian  row  is  to  be calculated.  The value of iflag should not be
       changed by fcn unless the user wants to terminate execution  of  lmstr_
       (or lmstr1_). In this case set iflag to a negative integer.

   Parameters for both lmstr_ and lmstr1_
       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.

       fjrow is an output array of length n which is set to  one  row  of  the
       Jacobian evaluated at x.

       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.

   Parameters for lmstr1_
       tol  is  a  nonnegative  input  variable.   Termination occurs when the
       algorithm estimates either that  the  relative  error  in  the  sum  of
       squares  is  at  most  tol or that the relative error between x and the
       solution is at most tol.

       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  algorithm estimates that the relative error in the  sum  of
       squares is at most tol.

         info  =  2  algorithm estimates that the relative error between x and
       the solution is at most tol.

         info = 3  conditions for info = 1 and info = 2 both hold.

         info = 4  fvec is orthogonal  to  the  columns  of  the  Jacobian  to
       machine precision.

         info = 5  number of calls to fcn has reached or exceeded 100*(n+1).

         info  =  6   tol  is  too  small.  no further reduction in the sum of
       squares is possible.

         info = 7  tol is too small. no further improvement in the approximate
       solution x is possible.

       wa is a work array of length lwa.

       lwa  is  an  integer  input  variable  not  less than m*n + 5*n + m for
       lmder1, or 5*n+m for lmstr1_.

   Parameters for lmstr_
       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.

       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 the latter is 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
       with iflag = 1.

       njev  is  an  integer output variable set to the number of calls to fcn
       with iflag = 2.

       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.

SEE ALSO

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

AUTHORS

       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).