*******************************************************************************
*                                                                             *
*                             RRQR Factorization                              * 
*         "Codes for Rank-Revealing Factorizations of Dense Matrices"         *
*                       by C.H.Bischof and G.Quintana-Orti.                   *
*                                                                             *
*******************************************************************************
*                         RELEASE: 1.0.5 (5-Jan-1997)                         *
*******************************************************************************


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

To use these codes, both LAPACK and BLAS libraries are strictly necessary 
and must be correctly installed in the target machine.
In addition, tuned BLAS libraries are strongly recommended to obtain 
optimal performance.


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

The distribution file, named "rrqr_acm.tar.gz", contains all the directories 
and files needed for creating, testing and timings the new RRQR codes.

The untaring of the file "rrqr_acm.tar.gz" creates the directory "rrqr_acm" 
in the current directory.  All the other directories and files needed are 
created inside "rrqr_acm".  So this file must be moved to the final position 
before installing it.

Two steps are needed to uncompress and untar the code:
1. Uncompressing the file:
	gunzip rrqr_acm.tar.gz
2. Untaring the files and directories:
	tar xf rrqr_acm.tar

Once uncompressed and untared, the directory "rrqr_acm" appears in the 
current directory. It will contain 6 subdirectories:

lib:
  This directory contain the tool to create the RRQR object library.

testing:
  This directory contains the drivers to test REAL, DOUBLE PRECISION,
  COMPLEX and COMPLEX*16 RRQR code.

timing:
  This directory contains the drivers to get the timings for REAL,
  DOUBLE PRECISION, COMPLEX and COMPLEX*16 RRQR code.

v15.acm:
  This directory contains the latest version of the REAL RRQR code.
  Besides, it contains a complete testing/timing driver for the RRQR
  code. This is the one used to get the timings shown in the paper.
 
cv15.acm:
  This directory contains the latest version of the COMPLEX RRQR code. 

matgen:
  This directory is only needed if library "tmglib.a" is not installed.
  The library "tmglib.a" (timing library) is the timing library that comes
  with the LAPACK installation package.  It contains some interesting matrix 
  generators needed by both our testing and timing codes.
  If the library "tmglib.a" is already installed in your target machine, you 
  can remove this directory.
  If you do not have this library, you can build it from this directory.


To continue the installation, jump to "rrqr_acm" directory:
	cd rrqr_acm


Steps to build the RRQR library:
================================

1. Go to "lib" directory:  
	cd lib

2. Edit the file "Makefile" and set the two macros FORTRAN and OPTS according 
   to your system requirements.
   You can find this macros at the very beginning of the file.
   For example, on SUN the macros should be set to:
     FORTRAN  = f77  # Fortran-77 compiler command.
     OPTS     = -O   # Fortran-77 compiler optimizing options.

   You might need to set other macros such as RANLIB, AR, etc.
   Ask your system administrator about these ones (usually well known 
   in UNIX environments).

3. 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 complex*16" 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 object files and the library.
The object files are left in the directory "rrqr_acm/lib".
The library is left in the directory "rrqr_acm" (the parent of directory 
"lib"), so as to allow an easy access from the testing and timing drivers.


Steps to build the testing drivers:
===================================

1. Go to the testing directory:  
	cd testing/v2

2. Edit the file "Makefile" and set the macros accordingly to your system.
   The macros you must set are the following: FORTRAN, OPTS, LOADER, LOADOPTS, 
   LAPACKLIB, TMGLIB, and BLASLIB.  You can find them at the very beginning 
   of this file.
   For example, on SUN the macros should be set to:
     FORTRAN    = f77                  # Fortran-77 compiler command.
     OPTS       = -O                   # Fortran-77 compiler optimizing options.
     LOADER     = f77                  # Fortran-77 linker command.
     LOADOPTS   = -O                   # Fortran-77 linker optimizing options.
     LAPACKLIB  = /usr/lib/lapack.a    # Path of LAPACK library.
     TMGLIB     = /usr/lib/tmglib.a    # Path of TMGLIB library.
     BLASLIB    = /usr/lib/blas.a      # Path of BLAS library.
   You may need to ask your system administrator the paths of lapack, tmglib,
   and blas libraries.

3. The command "make" will make the testing programs for the four data-types:
   REAL, DOUBLE PRECISION, 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 complex*16" to build the library for only COMPLEX*16 code, or
     whatever combination you need, such as "make single complex", etc.
   The executable files are created in the directory "testing".

4. Now you can start the tests.
   If you want to perform some complete tests on you machine, just type
   "testall". This script performs some thorough and long tests for the 
   four data types on three sets of matrices: small (files _test.sm.in), 
   medium (files _test.me.in), and large (files _test.lg.in).
   In this case, the results will be placed in files _test.sm.out, 
   _test.me.out and _test.lg.out.
   To perform some specific tests, you must type:
     xlintst_ < _test.in
   where _ must be replaced by s, d, c, or z, according to the data types
   you want to test.
   The input files (such as _test.in) tells the driver which matrix sizes, 
   matrix blocks, matrix types, etc. to test.
   You can find many examples of input files in directory "testing":
     "stest.sm.in" is an input file to perform some small tests on single 
     precision real numbers.
     "dtest.me.in" is an input file to perform some medium tests on double 
     precision real numbers.
     "ctest.lg.in" is an input file to perform some large tests on single
     precision complex numbers.g
     etc.

Note:
Be careful with matrix sizes.  If you are going to test big matrices,
you must set the parameters of files "xchkaa.f" accordingly.
The current drivers are prepared to test up to 500x500 matrices.
If you want to test larger ones, you must change the definition 
of NMAX in the mentioned files.


Steps to build the timing drivers:
==================================

1. Go to the timing directory:  "cd timing/v2"

2. Edit the file "Makefile" and set the macros accordingly to your system.
   The macros you must set are the following: FORTRAN, OPTS, LOADER, LOADOPTS, 
   LAPACKLIB, TMGLIB, and BLASLIB.
   You can find them at the very beginning of this file.
   For example, on SUN the macros should be set to:
     FORTRAN    = f77                  # Fortran-77 compiler command.
     OPTS       = -O                   # Fortran-77 compiler optimizing options.
     LOADER     = f77                  # Fortran-77 linker command.
     LOADOPTS   = -O                   # Fortran-77 linker optimizing options.
     LAPACKLIB  = /usr/lib/lapack.a    # Path of LAPACK library.
     TMGLIB     = /usr/lib/tmglib.a    # Path of TMGLIB library.
     BLASLIB    = /usr/lib/blas.a      # Path of BLAS library.
   You may need to ask your system administrator the paths of lapack, tmglib,
   and blas libraries.

3. The command "make" will make the timing programs for the four data-types.
   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 complex*16" to build the library for only COMPLEX*16 code, or
     whatever combination you need, such as "make single complex", etc.
   The executable files are created in "timing" directory.

4. Now you can start the timings.
   If you want to perform some complete timings on you machine, just type
   "timeall". This script performs some thorough and long timings for the 
   four data types on three sets of matrices: small (files _time.sm.in), 
   medium (files _time.me.in), and large (files _time.lg.in).
   In this case, the results will be placed in files _time.sm.out, 
   _time.me.out and _time.lg.out.
   To perform some specific timings, you must type:
     xlintim_ < _time.in
   where _ must be replaced by s, d, c, or z, according to the data types
   you want to test.
   The input files (such as _time.in) tells the driver which matrix sizes, 
   matrix blocks, matrix types, etc. to test.
   You can find many examples of input files in directory "timing":
     "stime.sm.in" is an input file to perform some small timings on single 
     precision real numbers.
     "dtime.me.in" is an input file to perform some medium timings on double 
     precision real numbers.
     "ctime.lg.in" is an input file to perform some large timings on single
     precision complex numbers.g
     etc.

Note: 
Be careful with matrix sizes.  If you are going to test big matrices,
you must set the parameters of files "xtimaa.f" accordingly.
The current drivers are prepared to test up to 1001x1001 matrices.
If you want to test larger ones, you must change the definition 
of NMAX in the mentioned files.


Drivers in v15.acm:
===================

1. Go to the directory "v15.acm":  "cd v15.acm"

2. Edit the file "Makefile" and set the macros accordingly to your system.
   The macros you must set are the following:  P, FORTRAN, OPTS, LOADER,
   LOADOPTS, LAPACKLIB, TMGLIB, and BLASLIB.
   You can find them at the very beginning of this file.
   For example, on SUN the macros should be set to:
     P          = s                    # Precision (s or d).
     FORTRAN    = f77                  # Fortran-77 compiler command.
     OPTS       = -O                   # Fortran-77 compiler optimizing options.
     LOADER     = f77                  # Fortran-77 linker command.
     LOADOPTS   = -O                   # Fortran-77 linker optimizing options.
     LAPACKLIB  = /usr/lib/lapack.a    # Path of LAPACK library.
     TMGLIB     = /usr/lib/tmglib.a    # Path of TMGLIB library.
     BLASLIB    = /usr/lib/blas.a      # Path of BLAS library.
   You may need to ask your system administrator the paths of lapack, tmglib,
   and blas libraries.

3. The command "make" will make the timing programs for data type specified
   in the makefile (s for single precision and d for double precision).
   The name of the executables are "sqr" for single precision and "dqr" for
   double precision.  The executable files are created in the same directory.

4. Now you can start the timings.
   To perform some specific timings, you must type:
     sqr (for single precision), and
     dqr (for double precision).
   File "sqr" is controlled by the input file "Sqr.in" and file "dqr" is 
   controlled by the input file "Dqr.in".
   These two "*.in" files specify the matrix sizes, block sizes, minimum time
   to benchmark, and other information to use during the execution.
   You can find examples of input files in directory "v15.acm".

   In this case, the name of the output file is composed of "time" plus a 
   suffix named in the first line of the input file.

Note: 
Be careful with matrix sizes.  If you are going to test big matrices,
you must set the parameters of files "xtimaa.f" accordingly.
The current drivers are prepared to test up to 1001x1001 matrices.
If you want to test larger ones, you must change the definition 
of NMAX in the mentioned files.


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

1. Go to the matrix generating directory:  "cd matgen"

2. Edit the file "Makefile" and set the macros FORTRAN and OPTS according
   to your system requirements.
   For example, on SUN the macros should be set to:
     FORTRAN  = f77  # Fortran-77 compiler command.
     OPTS     = -O   # Fortran-77 compiler optimizing options.
   You might need to set other macros such as RANLIB, AR, etc.
   Ask your system administrator about these ones (usually well known 
   in UNIX environments).

3. The command "make" will make the timing programs for the four data-types.
   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 complex*16" to build the library for only COMPLEX*16 code, or
     whatever combination you need, such as "make single complex", etc.


Known problems:
===============

We have detected that IBM ESSL library can produce residuals a bit larger
than usual when testing the code on 500x500 matrices. We have also checked
that the residuals go back under the usual threshold when using the BLAS
library obtained from Netlib, which can be obtained with LAPACK distribution.

Subroutine xBDSQR from LAPACK 2.0 seems to have an error. The same
subroutine from LAPACK 1.0b is working fine. This subroutine computes the
singular value decomposition of a bidiagonal matrix. This bug have affected
our drivers in directory "v15.acm" by showing in a few cases big residuals 
in the comparison of the singular values of A and R.


In case of problems:
====================
You can send e-mail to:
	gquintan@dsic.upv.es
	gquintan@inf.uji.es
