===================
                            CLAPACK README FILE
                            ===================


This README file describes how we transform LAPACK from FORTRAN into ANSI C,
and how to install the resulting C library, called CLAPACK.  CLAPACK must be 
compiled with an ANSI Standard C compiler.  If the C compiler on your machine 
is an old-style C compiler, you will have to use gcc to compile the package.  

First, we describe how to install CLAPACK, and then describe how we produced it
and how to maintain it.

                     Procedure for installing CLAPACK:
==============================================================================

(1) 'tar xvf clapack.tar' to build the following directory structure:
    CLAPACK/README      this file
    CLAPACK/BLAS/       C source for BLAS
    CLAPACK/F2CLIBS/    f2c I/O functions (libI77) and math functions (libF77)
    CLAPACK/SRC/        C source of LAPACK routines
    CLAPACK/TESTING/    driver routines to test correctness
    CLAPACK/TIMING/     driver routines to measure performance
    CLAPACK/Translate/  software for translation and subsequent clean up,
                        including CompletePolish as described below.
    CLAPACK/make.inc	compiler, compile flags and library definitions, 
			included in all Makefiles.
		        NOTE: It's better to use gcc compiler on some older
			Sun systems.

(2) Build the f2c libraries by doing:
      cd CLAPACK/F2CLIBS/libF77; make 
      cd CLAPACK/F2CLIBS/libI77; make

##############################################################################
WARNING: 1) If your system lacks onexit() and you are not using an ANSI C 
            compiler, then you should uncomment the following two lines
            (for compiling main.o) found within /F2CLIBS/libF77/makefile :
               	main.o: main.c
		$(CC) -c -DNO_ONEXIT -DSkip_f2c_Undefs main.c
            On at least some Sun systems, it is better to
            uncomment the following two lines:
        	main.o: main.c
                $(CC) -c -Donexit=on_exit -DSkip_f2c_Undefs main.c
         2) On at least some Sun systems, the type declaration in 
            libI77/rawio.h: extern FILE *fdopen(int, char*)
 	    is not consistent with the one defined in stdio.h. In this case
            you should comment out this line.
	  
##############################################################################

(3) Build the archive containing BLAS source code by doing:
      cd CLAPACK/BLAS/SRC; make

(4) Compile and run the BLAS TESTING code by doing:
      cd CLAPACK/BLAS/TESTING; make -f Makeblat2
      cd CLAPACK/BLAS
	xblat2s < sblat2.in
	xblat2d < dblat2.in
	xblat2c < cblat2.in
	xblat2z < zblat2.in
      cd CLAPACK/BLAS/TESTING; make -f Makeblat3
      cd CLAPACK/BLAS
	xblat3s < sblat3.in
	xblat3d < dblat3.in
	xblat3c < cblat3.in
	xblat3z < zblat3.in

    Inspect the output files *.SUMM to confirm that no errors occurred.

{NOTE: If a compiling error involving _atexit appears then see information
       within the WARNING above.}

{NOTE: For the highest performance, it is best to use a version of the BLAS
       optimized for your particular machine. This may be done by modifying
       the line
          BLASLIB      = ../../blas$(PLAT).a
       in CLAPACK/make.inc to point to the optimized BLAS.}

(5) Build the archive containing lapack source code by doing:
      cd CLAPACK/SRC; make

(6) Compile the matrix generation software, the eigenroutine TESTING
    code, the linear system TESTING code, and run the LAPACK tests 
    by doing:
      cd CLAPACK/TESTING/MATGEN; make
      cd CLAPACK/TESTING; make

    Inspect the output files *.out to confirm that no errors occurred.

(7) Build the archive containing the eigensystem routines, compile
    eigenroutine TIMING code, and the linear system TIMING code
    by doing:
      cd CLAPACK/TIMING; make

(8) Run the LAPACK timing tests by doing:
      cd CLAPACK/TIMING; make
      xlintims < sblasa.in > sblasa.out
      xlintims < sblasb.in > sblasb.out
      xlintims < sblasc.in > sblasc.out

      repeat timing of blas for c, d, and z

NOTE:  If your particular system does not have enough memory to complete
       the above compilations you can do the following steps instead:

I.   Compile the matrix generation software, the eigenroutine TESTING code,
     the linear system TESTING code, and run the LAPACK tests separately
     by doing:
	cd CLAPACK/TESTING/MATGEN; make
	cd CLAPACK/TESTING/EIG; make
	cd CLAPACK/TESTING/LIN; make
	cd CLAPACK/TESTING; make
II.  Build the archive containing the eigensystem routines, compile
     eigenroutine TIMING code, and the linear system TIMING code
     separately by doing:
	cd CLAPACK/TIMING/EIG/EIGSRC; make
	cd CLAPACK/TIMING/EIG; make
	cd CLAPACK/TIMING/LIN; make
	continue with step (8)
III. After the executable files and libraries have been created for each
     of the compiles, the object files should be removed by doing:
	make clean
IV.  Each 'make' may be accomplished just for one or a subset of the 
     precisions desired.  For example:
	make single
	make single complex
	make single double complex complex16
     Using make without any arguments will compile all four precisions.

============================================================================

Now we describe how we produced CLAPACK, and how to maintain it.

In addition to the routines translated from SRC, one needs to have 
f2c.h available to compile C source; this is in F2CLIBS. The library 
F2CLIBS/libF77.a needs to be linked with all routines as well. The library 
F2CLIB/libI77.a needs to be linked when running the TESTING or TIMING 
code, but not when using SRC code alone.

The basic translation is done by the Fortran-to-C translator f2c, which
was written by David Gay at Bell Labs, with subsequent cleanup to improve 
readability.  The software in the SRC directory, which contains the LAPACK 
library proper (i.e. no testing code, timing code, or BLAS), is cleaned up 
most completely, and so is easiest to read. We exploit the facts that these 
routines do almost no I/O (the few lines of I/O in xLAMCH and XERBLA have 
the ungainly f2c output replaced by hand; see below), and that they have a 
standard format for leading comments. The routines in TESTING, TIMING and 
BLAS are translated, but not cleaned up completely, and so they work but are 
not as easy to read.

This file describes the translation process in sufficient detail for future 
maintainers of the software.  The process is almost entirely automated, 
except for a few files that require some modification by hand.

0. All the software developed for translation and subsequent clean up
   is in the Translate/ directory.

1. For LAPACK/SRC and BLAS/SRC, translate and clean up by invoking 
  '../Translate/CompletePolish *.f' from within LAPACK/SRC and BLAS/SRC.
   CompletePolish invokes five procedures:
   (1-2) run_stripper: f2c | lenscrub
         f2c, written by David Gay at Bell Labs, does the main translation
         from fortran into ANSI C (suitable for compilation with gcc).
         A lex file (lenscrub.l), originally written by David Gay and
         modified by us, removes the unwanted string length arguments 
         introduced by f2c, but does not change the f2c FORTRAN I/O functions 
         or the ILAENV routine.
   (3)   run_macro: 
         better vector and array indexing; from George Levy and Shah 
	 Datardina at NAG.
   (4)   run_comment: 
         A lex file (comment.l) compresses consecutive comment lines into 
         big chunks by stripping all the "*/{whitespace}/*" sequences.
   (5)   run_splitter: 
         A sed script (split.sed) breaks the translated program into several
         pieces and re-arranges them for better legibility.

2. For LAPACK/TESTING, LAPACK/TIMING and LAPACK/BLAS/TESTING, we only need to 
   invoke Translate/PartialPolish, which consists of (1-2) and (4) in step 1, 
   and not the other clean-ups.

3. The routines requiring special treatment are:
   dlamch.c, slamch.c, dsecnd.c, second.c, lsamen.c, xerbla.c and zeispack.c.

  (1) xLAMCH.f should be translated as follows:
     (1) Break xLAMCH.f into 6 files: xLAMC[0-5].f corresponding to the 
         4 SUBROUTINES and 2 FUNCTIONS it contains.
     (2) Translate and clean-up each of the 6 files individually using 
         CompletePolish.
     (3) cat xLAMC[0-5].c into xLAMCH.c 

  (2) In xLAMCH and XERBLA: change the I/O to use standard C I/O (printf)
      instead of calls to the f2c I/O library. This will permit us to run 
      code from SRC without linking the f2c I/O library libI77 (TESTING and 
      TIMING code will use libI77).  There are simple write statements 
      (just one per subroutine) in the Fortran versions of
   	   dlamc2
   	   dlamch
   	   slamc2
   	   slamch
   	   xerbla
      corresponding to s_wsfe and do_fio in
	   dlamch
	   slamch
	   xerbla

      NOTE: Do the same for BLAS/SRC/xerbla.c
     
  (3) second.c and dsecnd.c must be re-written to call the timing function in C.

  (4) lsamen.c
      Replace i_len() with the strlen() library call in C.

  (5) At the beginning of TIMING/EIG/zeispack.c, add the following line:
	#define cdabs_ z_abs /* Fix to non-standard complex double abs */

4. In each subdirectory that needs f2c.h, we make a symbolic link to the
   master copy LAPACK/F2CLIBS/f2c.h. For example, in LAPACK/SRC, we do the 
   following: "ln -s ../F2CLIBS/f2c.h f2c.h"

James Demmel
Xiaoye Li		
Chris Puscasiu
Steve Timson

UC Berkeley
Sept 27 1993


{Revised by Susan Ostrouchov and Jude Toth}
 {The University of Tennessee at Knoxville}
             {October 15, 1993}

{Revised by Xiaoye Li and James Demmel}
 {University of California at Berkeley}
             {November 22, 1994}