.TH L2FIT 1
.SH NAME
l2fit \- least squares fit
.SH SYNOPSIS
.B l2fit
[
.I option ...
]
.I expr
[
.I startval ...
] [
.I file ...
]
.SH DESCRIPTION
.I L2fit
fits the function given by the Fortran expression 
.I expr
to
.I "x, y
pairs in 
.I files
or in the standard input.
The expression contains variable
.B x
and parameters
.BR p (1),
.BR p "(2), ...
The values of the parameters appear in order on the standard
output.
As a side effect,
.I l2fit
writes in the current directory a
.IR troff (1)
output file
.F 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 
.F l2fit.out
before believing the data on standard output.
The options are
.TF -troff
.TP
.B -w
Weighted least squares.
For each
.I x
value there are multiple
.I y
values, the variances of which are used in weights
to improve accuracy.
.TP
.B -t
Preserve temporary files that
.I l2fit
creates.
.TP
.B -i
Invisible.  Suppress the graphs in
.FR l2fit.out .
.TP
.BR -lx , " -ly" , " -lxy
Graph scales are logarithmic in
.I x,
.I y,
or both.
.TP
.BI -x text, " -y" text
Descriptions of
.I x
and
.I y
variables to be included in output.
.TP
.BI -c text
Comment; not included in output.
.TP
.B -troff
.F l2fit.out
is
.I troff
input.
.PP
.I L2fit
attempts to find a vector 
.I p
that minimizes the sum of the squares of the residuals
.IR y [ i "] \-
.IR f ( x [ i ],
.IR p ).
The function
.I f,
given as expression
.I expr,
may contain the usual constants, operators,
library functions, the operator 
.BR ^ 
(a synonym for
.BR ** ),
and variables
.I x
and
.IR p (1),
.IR p "(2), ...
The latter variables may equivalently be written
.BR p1 ,
.BR p2 ", ...
or
.BR a ,
.BR b ", ...
.PP
The numerical work is done by the
.IR port (3)
routine
.IR dn2f,
which finds a local minimum by a Newton iteration.
Initial guesses for the parameter values may be supplied as
.I startvals
(zero by default).
To distinguish
.I files
from 
.I startvals,
file names must not begin like numbers.
.PP
If there is a single argument,
it gives a file in which the true arguments are presented one per line.
Beware of piping into
.I L2fit
with a single argument that gives an expression;
the program will interpret it as an invalid filename.
.SH EXAMPLES
.TP
.B "l2fit 'p(1)*x**2 + p(2)*x + p(3)' datafile
.br
.ns
.TP
.B "gen.data | l2fit -i 'a*x^2 + b*x + c'
Two ways to fit a quadratic function to a set of 
.I "x, y
pairs.
The second example turns off the output with the
.IR -i
switch; two arguments are required so the expression is not interpreted as a file name.
.TP
.B "l2fit -w -lx -t 'a + b*x^c' 20 -1 -.5 searchdata.d
Fit data using weighted regression and the starting parameter values
.IR a =20
.IR b =-1
.IR c = -.5.
(Each 
.I x
value has many y values.)  Present graphs with logarithmic
.I x
scales and keep all temporary files.
.SH FILES
.TF l2temp.p
.TP
.B l2temp.*
Temporaries, among which are:
.PD 0
.TP
.F l2temp.f
Fortran program to call the optimizer.
This program can be edited if your function will not fit
in a single expression.
.TP
.F l2temp.g
.IR Grap (1)
specification of the graphs.
.TP
.F l2temp.p
Report from the
.IR port (3)
routine
.IR dn2f .
This can be helpful in locating numerical problems.
.PD
.SH SEE ALSO
J. L. Bentley, M. F. Fernandez, B. W. Kernighan and N. L. Schryer,
"Template-driven interfaces for numerical subroutines",
.I "ACM Transactions on Mathematical Software,
Fall 1993.
.SH BUGS
Numerical problems, such as slow convergence or convergence to
the wrong local minimum, can often be remedied by
supplying a more appropriate expression or better starting
values.
.SH INSTALLATION
.PP
The l2fit bundle contains this README file, the l2fit program,
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
.TP
schemafile = "/usr/bin/l2fit"
.PP
To test the program, try
.TP
chmod +x gen.data
gen.data | l2fit -ctest 'a*x^2 + b*x + c'
.PP
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.
.PP
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.
.PP
If your system does not have the Port library,
you may obtain the relevant source by typing
.TP
echo "send dn2f from port" |
mail netlib@research.att.com
.PP
After installation,
you should delete this INSTALLATION section from the file manpage
before you install the documentation.
