NAME
     l2fit - least squares fit
SYNOPSIS
     l2fit [ option ... ] expr [ startval ... ] [ file ... ]
DESCRIPTION
     L2fit fits the function given by the Fortran expression expr
     to x, y pairs in files or in the standard input.  The
     expression contains variable x and parameters p(1), p(2),
     ...  The values of the parameters appear in order on the
     standard output.  As a side effect, l2fit writes in the cur-
     rent directory a troff(1) output file l2fit.out that gives a
     one-page summary of the fit with numbers, such as standard
     errors, and graphs of the function and of residuals.  Study
     l2fit.out before believing the data on standard output.  The
     options are
     -w      Weighted least squares.  For each x value there are
             multiple y values, the variances of which are used
             in weights to improve accuracy.
     -t      Preserve temporary files that l2fit creates.
     -i      Invisible.  Suppress the graphs in l2fit.out.
     -lx, -ly, -lxy
             Graph scales are logarithmic in x, y, or both.
     -xtext, -ytext
             Descriptions of x and y variables to be included in
             output.
     -ctext  Comment; not included in output.
     -troff  l2fit.out is troff input.
     L2fit attempts to find a vector p that minimizes the sum of
     the squares of the residuals y[i] - f(x[i], p).  The func-
     tion f, given as expression expr, may contain the usual con-
     stants, operators, library functions, the operator ^ (a syn-
     onym for **), and variables x and p(1), p(2), ...  The lat-
     ter variables may equivalently be written p1, p2, ...  or a,
     b, ...
     The numerical work is done by the port(3) routine dn2f,
     which finds a local minimum by a Newton iteration.  Initial
     guesses for the parameter values may be supplied as
     startvals (zero by default).  To distinguish files from
     startvals, file names must not begin like numbers.
     If there is a single argument, it gives a file in which the
     true arguments are presented one per line.  Beware of piping
     into L2fit with a single argument that gives an expression;
     the program will interpret it as an invalid filename.
EXAMPLES
     l2fit 'p(1)*x**2 + p(2)*x + p(3)' datafile
     gen.data | l2fit -i 'a*x^2 + b*x + c'
          Two ways to fit a quadratic function to a set of x, y
          pairs.  The second example turns off the output with
          the -i switch; two arguments are required so the
          expression is not interpreted as a file name.
     l2fit -w -lx -t 'a + b*x^c' 20 -1 -.5 searchdata.d
          Fit data using weighted regression and the starting
          parameter values a=20 b=-1 c=-.5.  (Each x value has
          many y values.)  Present graphs with logarithmic x
          scales and keep all temporary files.
FILES
     l2temp.*  Temporaries, among which are:
     l2temp.f  Fortran program to call the optimizer.  This pro-
               gram can be edited if your function will not fit
               in a single expression.
     l2temp.g  Grap(1) specification of the graphs.
     l2temp.p  Report from the port(3) routine dn2f.  This can be
               helpful in locating numerical problems.
SEE ALSO
     J. L. Bentley, M. F. Fernandez, B. W. Kernighan and N. L.
     Schryer, "Template-driven interfaces for numerical subrou-
     tines", ACM Transactions on Mathematical Software, Fall
     1993.
BUGS
     Numerical problems, such as slow convergence or convergence
     to the wrong local minimum, can often be remedied by supply-
     ing a more appropriate expression or better starting values.
INSTALLATION
     The l2fit bundle contains this README file, the l2fit pro-
     gram, a manpage file, and the program gen.data.  To install
     the program, move l2fit to a suitable bin directory and make
     it executable (e.g., "chmod +x l2fit").  The third line of
     the Awk program is a first-hack assignment to the variable
     schemafile; change it to the complete-path address of the
     l2fit file, such as
     schemafile = "/usr/bin/l2fit"
     To test the program, try
     chmod +x gen.data
          gen.data | l2fit -ctest 'a*x^2 + b*x + c'
     The output values should be near 2, -10, 12.  The graphs in
     l2fit.out should show that the function is a close fit to
     the data, and the residuals are a sine times a uniform.
     The l2fit program requires up-to-date versions of f77, pic,
     troff, Awk (including the functions in the 1985 version),
     grap (including the ^ operator installed in 1989), and the
     Port library.  If l2fit does not work, check to make sure
     that your system has current versions.
     If your system does not have the Port library, you may
     obtain the relevant source by typing
     echo "send dn2f from port" |
          mail netlib@research.att.com
     After installation, you should delete this INSTALLATION sec-
     tion from the file manpage before you install the documenta-
     tion.
