
This package includes implementations of least squares solvers that 
are more efficient than the existing least squares solvers, such as 
those available in LAPACK, in the low-rank case.  For a discussion 
of the background of the algorithm used see the paper "Algorithm 
xxx: an Efficient Algorithm for Solving Rank-Deficient Least Squares 
Problems" by Leslie Foster and Rajesh Kommu, submitted to ACM 
Transactions on Mathematical Software.

This document describes how to install the package, how to run 
testing programs, how to run timing programs and how to run other 
example programs.  Also the document has a description of the 
contents of the directories in the package.

Requirements:
=============

The package requires the source code from the standard LAPACK 
package to be available. This can be obtained by downloading either 
the file lapack.tgz (for Unix) or the file lapack-pc.zip (for 
Windows) from www.netlib.org/lapack and unpacking (with, for 
example, gunzip and tar xf in Unix or Winzip in Windows) them.  The 
LAPACK files need to be unpacked but they do not need to be 
installed by executing the makefiles that are part of LAPACK.

The package also requires that a BLAS library is available.  Machine 
specific BLAS are usually available from computer manufacturers. See 
www.netlib.org/blas/faq.html#1.6.  Fortran versions of the BLAS are 
included as part of the LAPACK downloads mentioned above and also 
are available from www.netlib.org/blas.  However for optimal 
performance, tuned versions of these libraries are preferable. 

Quick Start
=========== 

This section describes how to use existing makefiles to install the 
complete package for computers running Sun OS with Sun's f77 
Fortran, Linux with g77 Fortran or Windows with Compaq (also called 
Digital and HP) Fortran.  This section also describes how to compile 
and run a simple example in any computer environment.

First unpack the package.  This depends on the form that you receive 
the package.  If it is in a tar/ gzipped file then in Unix 
uncompress and untar xgelsz.tar.gz via the following two steps:
1.  gunzip xgelsz.tar.gz
2.  tar xf xgelsz.tar
In Windows uncompress xgelsz.tar.gz using a tool such as Winzip.

Move to the top level XGELSZ directory and copy, from the 
XGELSZ/INSTALL directory, either make.inc.LINUX, make.inc.SUN, or 
make.inc.win32, depending on your operating system, to a file named 
make.inc in the XGELSZ directory.

In the make.inc file 
1. Modify the line with "LAPACK = " to "LAPACK = (directory where 
LAPACK is installed)" and 
2. Modify the line with "BLASLIB = " to "BLASLIB = (file or files 
where the BLAS library or libraries reside)".  Examples of suitable 
BLASLIB lines are given at the end of this section.
3. In Windows, but not Unix, it is also necessary to modify the line 
"HOME    = " to "HOME = (directory where XGELSZ is located)." 

In Unix type "make -f makeunix" or in Windows type "nmake -f 
makewin32".   This will install the entire package.  

After the package is installed one may move to XGELSZ/TESTING and 
look at the files ctest.out, dtest.out, stest.out or ztest.out.  
These files summarize tests of the new xGELSZ routines as well as 
the LAPACK least squares routines xGELS, xGELSX, xGELSY, xGELSS and 
xGELSD (where the leading x is C, D, S or Z).  Here and in the 
following C, D, S and Z represent, respectively, complex, double, 
single and complex double precisions. Any failures will be reported 
in these files.

One may also move to XGELSZ/TIMING and look at the files ctime.out, 
dtime.out, stime.out or ztime.out.  These files report, for a 300 by 
300 matrix, the times taken by the new xGELSZ routines as well as 
the LAPACK least squares routines xGELS, xGELSX, xGELSY, xGELSS and 
xGELSD (where the leading x is C, D, S or Z).

In addition one may move to XGELSZ/EXAMPLES.  A plot similar to 
Figures 1 and 2 of the paper by Foster and Kommu may be produced by 
typing "dfig12 < fig12.in", by starting Matlab, by moving in Matlab 
to the directory XGELSZ/EXAMPLES and by typing "plotfig12" in 
Matlab.  A plot similar to Figure 3 of the paper by Foster and Kommu 
may be produced by typing "dfig3 < fig3.in", by starting Matlab, by 
moving in Matlab to the directory XGELSZ/EXAMPLES and by typing 
plotfig3 in Matlab.

One can also run a simple example without executing any of the above 
makefiles. Move to the directory XGELSZ/EXAMPLES/SRC and run either
(fortran compiler) cexample.f cgelsz_subs.f cgelsz_blas.f slamch.f
or
(fortran compiler) dexample.f dgelsz_subs.f dgelsz_blas.f dlamch.f
or
(fortran compiler) sexample.f sgelsz_subs.f sgelsz_blas.f slamch.f
or
(fortran compiler) dexample.f dgelsz_subs.f dgelsz_blas.f dlamch.f
where (fortran compiler) is the name of the Fortran compiler.  The 
resulting executables provide a sample run for each precision.

Finally in this section we will provide some additional information 
about BLAS libraries and the BLASLIB line in make.inc.
Samples of the BLASLIB line are:
a.  For Linux using Intel's MKL library and a Pentium 4 processor:
"BLASLIB= (mkl directory)/libguide.so (mkl directory)/libmkl_p4.so".
Here (mkl directory) is the directory with the MKL libraries and a 
typical value is /opt/intel/mkl/lib/32. To have access to these 
libraries an environment variable LD_LIBRARY_PATH must be set 
properly.  If needed this can be done, for example, by typing 
"setenv LD_LIBRARY_PATH = /opt/intel/mkl/lib/32" from the Linux 
shell prompt.
b.  For Windows using Intel's MKL library and a Pentium 4 processor:
"BLASLIB= (mkl directory)\mkl_p4.lib (mkl directory)\mkl_s.lib".  
Here (mkl directory) is the directory with the MKL libraries and 
must be filled in.
c.  For a Sun Computer using the Sun Performance library:
 "BLASLIB = -xlic_lib=sunperf". 
d.  For a Linux computer using the compiled Fortran BLAS as created 
by a makefile in LAPACK (see below): 
"BLASLIB = $(LAPACK)/blas_LINUX.a".
e.  For a Windows computer using the compiled Fortran BLAS as 
created by a makefile in LAPACK (see below): 
"BLASLIB = $(LAPACK)\blas_win32.lib".

To create a BLAS library from the Fortran code that is part of the 
standard LAPACK download:
a. Create an appropriate make.inc file in the LAPACK directory.  You 
may need to copy an appropriate file from the LAPACK/INSTALL 
directory.  In make.inc set the "BLASLIB = " line to "BLASLIB = 
../../blas$(PLAT).a" or, in Windows, "BLASLIB = 
..\..\blas$(PLAT).lib". For Windows but not Unix you will need to 
modify the "HOME = " line in the make.inc file to be "HOME = 
(location of the LAPACK directory)".  
b.  Move to the LAPACK/BLAS/SRC directory and type "make" in Unix or 
"nmake" in Windows.
The library will be created in the LAPACK directory.

Information that is more detailed than this Quick Start section is 
given below.


Contents of the distribution file:
==================================

After unpacking the package the following directory structure is 
created:

XGELSZ
  EXAMPLES
     SRC
  INSTALL
  SRC
  TESTING
    LIN
    MATGEN
  TIMING
    LIN
      LINSRC

The XGELSZ directory contains the subdirectories described below and 
makefiles that can be used to build the package.  This directory is 
created in the directory where xgelsz.tar.gz was saved.

Note that the directory XGELSZ and its subdirectories (except for 
XGELSZ/EXAMPLES/SRC) include routines that are new and those LAPACK 
routines that have been modified to include testing and timing of 
the new routines. As mentioned above LAPACK needs to be downloaded 
and unzipped but it is not necessary to actually build LAPACK by 
executing LAPACK's makefiles. The xGELSZ makefiles will build the 
portions of LAPACK that are needed. 

The XGELSZ/INSTALL directory has this README file which describes 
how to install and build the code. In addition this directory 
contains changelog.pdf which is a summary of the new routines and a 
description of the LAPACK timing and testing routines that have been 
modified to allow timing and testing of the xGELSZ routines.  Also 
the directory contains the three files make.inc.LINUX, make.inc.SUN 
and make.inc.win32 that define machine specific values needed by the 
package makefiles.  In addition the directory contains 
nagpolish_lapack.opt which is a file of options for NAG's nag_polish 
utility.  These options were used to format all the Fortran code in 
a manner consistent with the style used by LAPACK. 

The XGELSZ/EXAMPLES directory and its subdirectory contain several 
examples illustrating the use of the code in this package.  The 
XGELSZ/EXAMPLES directory includes Fortran code and input files that 
will generate data for plots similar to those in Figures 1, 2 and 3 
in the paper of Foster and Kommu, sample input files for this code 
and makefiles to build the examples.  Matlab code that is needed to 
generate the plots is also included. The subdirectory 
XGELSZ/EXAMPLES/SRC is a self-contained directory with code to 
generate a simple example.  The fourteen Fortran files in the 
directory are sufficient to compile and run a simple example in each 
of the four precision -- single, double, complex and complex*16.  
This subdirectory contains code for the new routines as well as code 
from existing LAPACK routines. No code outside the directory is 
needed.

The XGELSZ/SRC directory contains the new routines -- the driver 
routines xGELSZ and the auxiliary routines xLAQP3, xLAQPP, and 
xLAQPQ. These routines are available in single, complex, double and 
double complex precisions.  Also the directory has makefiles that 
will build a library of these routines and the  LAPACK routines 
described in the LAPACK User's Guide.

The XGELSZ/TESTING directory contains several subdirectories, test 
data files that are used as input to the test programs and makefiles 
that can be used to build the testing libraries. The 
XGELSZ/TESTING/LIN directory contains source code for routines that 
test the code in XGELSZ/SRC. These routines are modifications of 
LAPACK routines. The XGELSZ/TESTING/MATGEN directory includes 
makefiles that build the LAPACK matrix generator library tmglib. The 
testing routines in XGELSZ/TESTING call routines from the test 
matrix generator library. 

The XGELSZ/TIMING directory contains several subdirectories, the 
timing data files that are used as input to the timing programs and 
makefiles that can be used to build the timing libraries. The 
XGELSZ/TIMING/LIN directory contains source code for routines used 
to report the timing results. These routines are modifications of 
LAPACK routines.  The XGELSZ/TIMING/LIN/LINSRC directory contains 
instrumented versions of the xGELSZ routines found in the XGELSZ/SRC 
directory.  These instrumented versions gather statistics about the 
times required for various portions of the least squares code.

Configuring the build process for a specific platform:
========================================================

The build process is configured by creating a make.inc file in the 
XGELSZ directory. Individual makefiles in the various directories 
need not be changed.  If the package is being implemented on a 
Windows, Linux or Sun computer then one can follow the procedure 
outlined in the Quick Start section.  Depending on the BLAS library 
that is used you may also want to change the values of SCFROMBLAS or 
DZFROMBLAS.  The current values work for the MKL, Sun Performance 
and generic Fortran BLAS.

If the package is not being implemented on a Windows, Linux or Sun 
computer then make.inc.LINUX, make.inc.SUN, and make.inc.WIN32 
provide models that can be modified for other operating systems. 
Also the INSTALL directory in the standard LAPACK distribution may 
have some useful examples.  The following symbols are defined in the 
make.inc file:

HOME  
  This defines the location of the XGELSZ directory.  It is needed 
in Windows but not Unix.
LAPACK
  The directory containing the standard LAPACK code.
BLASLIB
  The fully specified location of the BLAS library
PLAT  
  This specifies a platform identifying string. 
FORTRAN
  Specifies the Fortran compiler that is to be used.
OPTS
  Compiler specific options.
DRVOPTS
  Special options for building the driver programs; can be the same 
as OPTS.
NOOPT
  Used for specifying compilation with optimizations turned off. 
LOADER
  Specifies the linker for building the executable.
LOADOPTS
  Linker specific options.
ARCH
  Specifies the archiver for building a library.
ARCHFLAGS
  Archiver specific options.
RANLIB
  Tool that generates an index to the contents of an archive, for 
faster access.  If your platform does not have such a tool, set 
RANLIB=echo .
LINSRCLIB
  Name for the library that contains the instrumented versions of 
the least squares routines.
SCFROMBLAS
  Any single and complex precision routines in BLASLIB, that may 
need to be replaced.  Refer to the platform specific issues at the 
end of this document.
DZFROMBLAS
  Any double and complex16 precision routines in BLASLIB, that may 
need to be replaced.  Refer to the platform specific issues at the 
end of this document.

Steps to build the entire library
================================== 

0. Uncompressed the package and make the changes to make.inc 
described earlier.

1.  In Unix type "make -f makeunix" or in Windows type "nmake -f 
makewin32".   This will install the entire package.  


Steps to build a library xGELSZ and LAPACK routines:
====================================================

The LAPACK library that is built in this section contains all the 
routines described in the LAPACK 3.0 User's Guide, Third Edition 
(SIAM Press, 1999) and also contains the new xGELSZ routines. 

In the following instructions, "make" on Unix platforms should be 
replaced by "make -f makeunix" and on Windows, "make" should be 
replaced by "nmake -f makewin32". Similary, "make single" should be 
replaced by "make -f makeunix single" on Unix and "nmake -f 
makewin32 single" on Windows, respectively. The same is true for the 
other precisions (double, complex, complex16).
  
0. Uncompressed the package and make the changes to make.inc 
described in previous sections.

1. cd to "XGELSZ/SRC" directory:  

2. Type "make" to build the library for the four data types: single, 
double, complex and complex16.
   If not all the data-types are needed, type: 
     "make single" to build the library for only REAL code, 
     "make double" to build the library for only DOUBLE PRECISION 
           code,
     "make complex" to build the library for only COMPLEX code, or
     "make complex16" to build the library for only COMPLEX*16 code, 
      or whatever combination you need, such as 
     "make single complex", etc.

This step will build the library in the XGELSZ directory. The 
library will be named lapack$(PLAT) where $(PLAT) indicates the 
current platform as defined in make.inc.

Steps to build the test matrix generator library:
================================================= 

The test matrix generator library that is built in this section 
contains utilities that can be used to generate test matrices.  The 
library that is built is identical to the test matrix library that 
is built when installing LAPACK 3.0.

In the following instructions, "make" on Unix platforms should be 
replaced by "make -f makeunix" and on Windows, "make" should be 
replaced by "nmake -f makewin32". Similarly, "make single" should be 
replaced by "make -f makeunix single" on Unix and "nmake -f 
makewin32 single" on Windows, respectively. The same is true for the 
other precisions (double, complex, complex16).
  
0. After the package is uncompressed make the changes to make.inc 
described in previous sections.

1. cd to "XGELSZ/TESTING/MATGEN" directory:  

2. Type "make" to build the library for the four data-types: single, 
double, complex and complex*16.
   If not all the data-types are needed, type: 
     "make single" to build the library for only REAL code, 
     "make double" to build the library for only DOUBLE PRECISION 
           code,
     "make complex" to build the library for only COMPLEX code, or
     "make complex16" to build the library for only COMPLEX*16 code, 
      or whatever combination you need, such as 
     "make single complex", etc.

This step will build the library in the XGELSZ directory. The 
library will be named tmglib$(PLAT) where $(PLAT) indicates the 
current platform as defined in make.inc.

Steps to build the testing drivers: 
(Needs lapackPLAT.a and tmglibPLAT.a)
===================================== 

This section produces test drivers that can test all the existing 
LAPACK linear equation (and least squares) solvers and can also test 
the new xGELSZ routines.  The drivers produced by this section test 
the routines that can handle rank-deficient least squares problems 
by using matrices of full rank and matrices of rank min(m,n) / 10 
where the matrix is m by n.  This is a change from LAPACK which used 
test matrices of full rank and of rank 3 * min(m,n) / 4.  A sample 
input file is run by the makefile.  This run tests the new routines 
xGELSZ as well as existing LAPACK routines xGELS (which uses the QR 
factorization without pivoting), xGELSX (which uses the QR 
factorization with pivoting and BLAS-2), xGELSY (which uses the QR 
factorization with pivoting and BLAS-3), xGELSS (which uses the 
singular value decomposition) and xGELSD (which uses a divide and 
conquer implementation of the singular value decomposition).

In the following instructions, "make" on Unix platforms should be 
replaced by "make -f makeunix" and on Windows, "make" should be 
replaced by "nmake -f makewin32". Similary, "make l" should be 
replaced by "make -f makeunix single" on Unix and "nmake -f 
makewin32 single" on Windows, respectively. The same is true for the 
other precisions (double, complex, complex16).
  
0. After the package is uncompressed make the changes to make.inc 
described in previous sections.

1. cd to the XGELSZ/TESTING directory:  

2. Type "make" to build the library for the four data-types: single, 
double, complex and complex*16.
   If not all the data-types are needed, type: 
     "make single" to build the library for only REAL code, 
     "make double" to build the library for only DOUBLE PRECISION 
           code,
     "make complex" to build the library for only COMPLEX code, or
     "make complex16" to build the library for only COMPLEX*16 
            code, 
      or whatever combination you need, such as 
     "make single complex", etc.

3. In addition to creating the executable files the testing routines 
are run with the input file xtest.in (where x is c, d, s or z).  
This tests the above routines for a variety of selections of 
parameters and calculates a number of different test ratios.  If any 
of the ratios are too large a failure message is reported in the 
output file xtest.out.

4. To perform additional tests one can modify xtest.in and type:
     xlintstd < dtest.in   (for double precision)
     xlintstz < ztest.in   (for complex double precision)
     xlintsts < stest.in   (for single precision)
     xlintstc < ctest.in   (for complex precision)
Documentation describing the format for xtest.in is contained in the 
xtest.in files and in the xchkaa.f programs (where x is c, d, s or 
z).  The files dtest2.in, ztest2.in, stest2.in and ctest2.in are 
included in the XGELSZ/TESTING directory and can be used to test the 
code for larger matrices than the matrices in the xtest.in files.

The test drivers created - xlintstc, xlintstd, xlintsts and xlintstc 
- are in the XGELSZ/TESTING directories.

Note:
The current drivers are prepared to test up to 132x132 matrices. If 
you want to test larger matrices, you must change the definition of 
NMAX in xchkaa.f (where x is c, d, s, or z).


Steps to build the timing drivers:
(Needs lapackPLAT.a and tmglibPLAT.a)
===================================== 

This section produces timing drivers that can time all the existing 
LAPACK linear equation (and least squares) solvers and can also test 
the new xGELSZ routines.  The drivers produced by this section time 
the routines that can handle rank-deficient least squares problems 
by using matrices of full rank and matrices of rank min(m,n) / 10 
where the matrix is m by n.  This is a change from LAPACK which used 
test matrices of full rank and of rank 3 * min(m,n) / 4.  A sample 
input file is run by the makefile.  This will time the new routines 
xGELSZ as well as existing LAPACK routines xGELS (which uses the QR 
factorization without pivoting), xGELSX (which uses the QR 
factorization with pivoting and BLAS-2), xGELSY (which uses the QR 
factorization with pivoting and BLAS-3), xGELSS (which uses the 
singular value decomposition) and xGELSD (which uses a divide and 
conquer implementation of the singular value decomposition).

In the following instructions, "make" on Unix platforms should be 
replaced by "make -f makeunix" and on Windows, "make" should be 
replaced by "nmake -f makewin32". Similarly, "make single" should be 
replaced by "make -f makeunix single" on Unix and "nmake -f 
makewin32 single" on Windows, respectively. The same is true for the 
other precisions (double, complex, complex16).
  
0. After the package is uncompressed make the changes to make.inc 
described in previous sections.

1. cd to the XGELSZ/TIMING

2. Type "make" to build the library for the four data-types: single, 
double, complex and complex*16.
   If not all the data-types are needed, type: 
     "make single" to build the library for only REAL code, 
     "make double" to build the library for only DOUBLE PRECISION 
           code,
     "make complex" to build the library for only COMPLEX code, or
     "make complex16" to build the library for only COMPLEX*16 
           code, 
      or whatever combination you need, such as 
     "make single complex", etc.

3. In addition to creating the executable files the testing routines 
are run with the input file xtime.in (where x is c, d, s or z).  
This file times the above routines for a single 300 by 300 matrix 
and reports the times of the routines in the file xtime.out.

4.. To perform additional tests one can modify xtime.in and type:
     xlintimd < dtime.in   (for double precision)
     xlintimz < ztime.in   (for complex double precision)
     xlintims < stime.in   (for single precision)
     xlintimc < ctime.in   (for complex precision)
Documentation describing the format for xtime.in is contained in the 
xtime.in files and in the xtimaa.f programs (where x is c, d, s or 
z).

The test drivers created - xlintimc, xlintimd, xlintims and xlintimc 
- are in the XGELSZ/TIMING directories.


Notes:
(1)The current drivers are prepared to test up to 512x512 matrices. 
If you want to test larger matrices, you must change the definition 
of NMAX in xtimaa.f (where x is c, d, s, or z).

(2) The image sizes of xlintimd and xlintimz can be relatively 
large.  If the image size is larger than allowed on a computer then 
the parameter MXNLDA in XGELSZ/TIMING/LIN/dtimaa.f and 
XGELSZ/TIMING/LIN/ztimaa.f can be changed from from MXNLDA = 2 to 
MXNLDA = 1.

Steps to build the example programs: (Needs lapackPLAT.a)
========================================================== 

The sample programs produced by the makefiles in the XGELSZ/EXAMPLES 
directory can be used to generate figures like those in Figures 1, 2 
and 3 in the paper by Foster and Kommu that compare the run times 
and accuracy of the programs.  

In the following instructions, "make" on Unix platforms should be 
replaced by "make -f makeunix" and on Windows, "make" should be 
replaced by "nmake -f makewin32". Similary, "make single" should be 
replaced by "make -f makeunix single" on Unix and "nmake -f 
makewin32 single" on Windows, respectively. The same is true for the 
other precisions (double, complex, complex16).
  
0. After the package is uncompressed make the changes to make.inc 
described in previous sections.

1. cd to the XGELSZ/EXAMPLES

2. The command "make" will make the xfig12 and the xfig3 programs 
for the four data-types.
   If not all the data-types are needed, type: 
     "make single" to build only the sfig12 and sfig3 programs
     "make double" to build only the dfig12 and dfig3 programs
     "make complex" to build only the cfig12 and cfig3 programs
     "make complex*16" to build only the zfig12 and zfig3 programs, 
      or whatever combination you need, such as 
     "make single complex", etc.

The executable files cfig12, dfig12, sfig12, zfig12, cfig3, dfig3, 
sfig3 and zfig3 are created in the "EXAMPLES" directory.

Figures 1 and 2 in the paper by Foster and Kommu compare the run 
times for the new routine xGELSZ and the LAPACK routines xGELSY and 
xGELSD.  The routines xGELSY and xGELSD are the routines that are 
recommended in LAPACK 3.0 for solving rank deficient linear 
equations and least squares problems.  To produce plots similar to 
Figures 1 and 2:
a.   Move to the XGELSZ/EXAMPLES directory
b.   Type "xfig12 < (input file)" where x is either c, d, s or z and 
where the input file is one of fig12.in, fig12_1.in or fig12_2.in.  
The input file fig12.in should take about a minute to run and 
produces a rough plot comparing the run times for 100 by 100 
matrices.  The input file fig12_1.in uses 1600 by 1600 matrices to 
produce data suitable for Figure 1 in the paper by Foster and Kommu.  
It may take several hours to run. The input file fig12_2.in uses 100 
by 100 matrices to produce data suitable for Figure 2 in the paper 
by Foster and Kommu.  It takes about 10 minutes to run.  If one 
wishes to create input files for matrices of other sizes note that 
there is documentation about the input format in fig12.in, 
fig12_1.in, fig12_3.in and in the comments in the xfig12.f programs 
(where x is either c, d, s or z).
c.    Start Matlab and move, from inside Matlab, to the directory 
XGELSZ/EXAMPLES.
d.    Type plotfig12 from inside Matlab.

Figure 3 in the paper by Foster and Kommu compares the accuracy of 
the new routines xGELSZ and the LAPACK routines xGELSY and xGELSD.  
The routines xGELSY and xGELSD are the routines that are recommended 
in LAPACK 3.0 for solving rank deficient linear equations and least 
squares problems.  Figure 3 plots histograms of four ratios that are 
used by the LAPACK testing facilities to verify that LAPACK's least 
square routines are working correctly.  These ratios are described 
in the paper of Foster and Kommu and should all be less than 30 if 
the routines are working correctly.  To make these plots

a.   Move to the XGELSZ/EXAMPLES directory
b.   Type "xfig3 < (input file)" where x is either c, d, s or z and 
where the input file is one of fig3.in or fig12_3.in.  The input 
file fig12.in produces data suitable for a rough graph similar to 
Figure 3 of the paper except using matrices of size 25 by 30.  It 
should take less than a minute to run.  The input file fig12_3.in 
uses 250 by 300 matrices to produce data suitable for Figure 3 in 
the paper by Foster and Kommu.  It may take several hours to run.  
If one wishes to create input files for matrices of other sizes note 
that there is documentation about the input format in fig3.in, 
fig3_3.in, and in the comments in the program xfig3.f (where x is 
either c, d, s or z).
c.    Start Matlab and move from inside Matlab to the directory 
XGELSZ/EXAMPLES.
d.    Type plotfig3 from inside Matlab.

The EXAMPLES directory also includes the EXAMPLES/SRC subdirectory.  
As mentioned in the Quick Start section this is a self-contained 
subdirectory.  The xexamples.f files(where the leading x is c, d, s 
or d) are drivers that create a simple 5 by 3 example, call xGELSZ 
and print results.  The files xgelsz_subs.f contain, for each 
precision, the xGELSZ subroutine and all the LAPACK subroutines, 
except for those in dlamch.f and slamch.f, that are needed by 
xGELSZ.  The xgelsz_blas.f files contain all the BLAS routines 
needed by xGELSZ.  Finally dlamch.f and slamch.f are files from 
LAPACK for determining machine constants.  Note that it may be 
necessary to compile dlamch.f and slamch.f without optimization (see 
the section on platform specific issues).  Also note that 
xgelsz_blas.f can be replaced by a machine specific BLAS library.  
Code to generate these examples is described in the Quick Start 
section.  This code would need modification to change the 
optimization level or to include machine specific BLAS libraries.

Software Quality
================ 

The code in this package has been developed following good software 
engineering practices such as those outlined in 
(http://www.netlib.org/lapack/maintenance.html).  For example, as 
mentioned earlier, NAG's nag_polish utility 
(http://www.nag.co.uk/nagware/NQ.asp) has been used to format the 
Fortran code in a manner consistent with the style used by LAPACK.  
Also the static analyzer ftnchek 
(http://www.dsm.fordham.edu/~ftnchek) has been used to check for 
semantic errors and portability testing has been done by using 
appropriate compiler flags.  In addition the code has been tested 
for a variety of different computers and operating systems.  For 
example for a variety of computers and operating systems the code 
passed the test suite used by LAPACK to test LAPACK's least squares 
routines as well as other tests.  We considered the guidelines 
discussed in "A Theoreticians Guide to the Experimental Analysis of 
Algorithms" (http://www.research.att.com/~dsj/papers/experguide.pdf) 
in evaluating our numerical experimentation.
 
Platform specific Issues:
=========================
[1]  Problems with Intel's Math Kernel Library, version 5.2, on 
Linux and Windows.

The versions of SNRM2, SCNRM2, and CDOTC that ship with MKL 5.2 have 
some bugs. The workaround for this problem is to include the Fortran 
versions of snrm2.f, scnrm2.f, and cdotc.f in the build process. The 
make.inc.LINUX and make.inc.win32 files that are in the INSTALL 
directory will include these three Fortran BLAS routines. They can 
be excluded from the build if your platform or version of MKL does 
not have this problem. To exclude these files from the build 
process, set the SCFROMBLAS and/or the DZFROMBLAS variables to a 
blank string in make.inc. 

[2]  The image sizes of xlintimd and xlintimz

As mentioned in the section describing the steps to build the timing 
drivers the image sizes of xlintimd and xlintimz, the executable 
versions of the double precision and complex double precision 
routines that compare the times for our routines and other LAPACK 
routines, can be relatively large. If the image size is larger than 
allowed on a computer then the parameter MXNLDA in 
XGELSZ/TIMING/LIN/dtimaa.f and XGELSZ/TIMING/LIN/ztimaa.f can be 
changed from MXNLDA = 2 to MXNLDA = 1.

[3]  LAPACK's timing programs second.f and dsecnd.f should be 
different on Unix and some Windows computers.

Our testing found that the timing programs, second.f and dsecnd.f 
used by the Unix installation of LAPACK 
(http://www.netlib.org/lapack/lapack.tgz ) can be inaccurate on some 
computers using Windows and Digital Fortran version 6.1.  The 
Windows version of LAPACK (http://www.netlib.org/lapack/lapack-
pc.zip ) contains different versions of second.f and dsecnd.f that 
work correctly on Windows.  Our makefiles will choose the proper 
versions as long as the appropriate version of LAPACK is installed 
on your computer.

[4]  Caution with the LAPACK routines dlamch.f and slamch.f.

These routines determine various machine parameter and the values 
determined can be incorrect if the routines are compiled using 
optimization.  This is a well known problem and the makefiles in the 
standard LAPACK implementation turn off optimization when compiling 
dlamch.f and slamch.f.  We do the same in our makefiles.
