** README file (updated on 08/07/2007) *******************************
*                                                                    *
*  This file contains information about the (advanced or developer)  *
*  testing infrastructure STETESTER for LAPACK's symmetric tridiag.  *
*  eigensolvers.                                                     *
*                                                                    *
*  STETESTER has been compiled and tested on a variety of computer   *
*  architectures. For convenience, we provide a number of different  *
*  configurations (platform specifics) in the subdirectory INSTALL.  *
*  These may need to be changed slightly, see the installation       *
*  steps below for details.                                          *
*                                                                    *
**********************************************************************

Contents of this directory:
==========================

DATA      : test matrices and eigenvalue distributions  
INPUT     : input files and options accepted by STETESTER
INSTALL   : compilation options for different architectures
LIB       : reserved for module files and the STETESTER library 
Makefile  : generates the STESTER library and executables
README    : this file
make.inc  : include file (platform specifics)

Platform specifics:
==================

The subdirectory INSTALL contains a number of configurations/platforms
where STETESTER has been compiled and tested, including:

- AMD (niche.lbl.gov): 1.2 GHz AMD Athlon running RedHat Linux.
- ITN2 (davinci.nersc.gov): 1.4 GHz Itanium 2.
- PIII (Dell C400 laptop): 1.2 GHz Pentium III.
- P4: 4.0 GHz Pentium running Linux.
- SP3 (seaborg.nersc.gov): 375 MHz POWER 3+ (1.5 GFlops/sec). 
- IRIX64 (escher.nersc.gov): Silicon Graphics Onyx 3400, 12 600 MHz 
  IP35 processors.
- SunOS58 (nsun4.lbl.gov): Sun Blade 100, 650 MHz sparcv9 processor.
- X1 (sn702 at Cray Inc.).
- XD1 (thunder at Cray Inc.): Dual 2.2 Ghz Opteron.

Installation steps:
==================

1) Copy one of the files in the subdirectory INSTALL into ./make.inc 
   to accommodate the target architecture. For example, on an IBM
   Power 5, copy INSTALL/make.inc.AIX.SP5 to ./make.inc. It may
   be necessary to edit make.inc in order to match the user's 
   preferences and the computer environment, in particular:
   - desired compilation options,
   - LAPACK and BLAS libraries to be used,
   - location of the STETESTER library,
   - interfaces for the timing function and flops counting.
2) Generate the STETESTER library: "make stetesterlib".
3) Generate the STETESTER executable: "make dstetester.x" for the
   double precision version or "make sstetester.x" for the single
   precision version. 
4) Run the tester: "dstetester.x < INPUT/input.test.easy". With 
   this simple input file (and upon successful completion) five
   output files are generated:
   - dstetester.out.T   (tridiagonal matrices used in the tests)
   - dstetester.out.W   (eigenvalues computed by the various solvers)
   - dstetester.out.Z   (eigenvectors computed by the various solvers)
   - dstetester.out.log (timing, residuals, orthogonality level)
   - dstetester.out.m   (results in Matlab format)

See the INPUT subdirectory for additional information about the
options used in the tests and also other input files.

Input files:
===========

The subdirectory INPUT contains examples of input files for STETESTER
and a list of all options accepted by STETESTER. Explicit matrices and
eigenvalue distributions (from which symmetric tridiagonal matrices 
can be generated) are stored in the subdirectory DATA. Additional 
input files and a large collection of test matrices are available
at http://crd.lbl.gov/~osni/Codes/stetester.

Notes:
=====

1) The matrix T_zenios.dat (available in the above URL) cannot be read
   in single precision on some architectures.
2) The subroutine stegr available in LAPACK 3.0 may hang (infinite
   loop) for some difficult test cases. These problems have been
   corrected in LAPACK 3.1.
