C*** readme
#
# FILE: README
#
This directory contains files of:

1.  Fortran source code for the eigenvalue assignment subroutines:
      dmevas  (double precision)  in file  dmevas.f
      smevas  (single precision)  in file  smevas.f
    These files also contain supporting subroutines. 

2.  Fortran source code for the staircase reduction and back 
    transformation subroutines:
      dstair, dbktrn  (double precision)  in file  dstair.f
      sstair, sbktrn  (single precision)  in file  sstair.f

3.  Fortran source code for those routines used from the BLAS,
    LAPACK and EISPACK libraries, in the files blas.f, lapack.f,
    and eispk.f, respectively.  The routines from EISPACK are
    used only in the demonstration programs (see below).

4.  Fortran source code for the demonstration programs in files:
      ddemo.f  (double precision)
      sdemo.f  (single precision)
    The demonstration program _demo calls the user callable routines
    _stair, _mevas, and _bktrn  before computing the eigenvalues of
    the closed loop matrix (A-B*F).  The computed eigenvalues may then
    be compared with the given eigenvalues, bearing in mind that the
    eigenproblem need not be well conditioned.

5.  A  Makefile (for UNIX users) to create executables as follows:
      < make ddemo >  creates double precision executable  ddemo.x
      < make sdemo >  creates single precision executable  sdemo.x
      < make > will also create the double precision executable ddemo.x

    Non-UNIX users should compile and link:
      For the double precision demonstration program:
          ddemo.f, dmevas.f, dstair.f, lapack.f, blas.f eispk.f
      For the single precision demonstration program: 
          sdemo.f, smevas.f, sstair.f, lapack.f, blas.f eispk.f

6.  A suite of test data files:
      test*.dat     (* = 01, 02, ..., 20)
    These are to be used by the demonstration programs.  The test data 
    are designed to execute the major branches of the eigenvalue assignment
    routines. The resulting closed loop matrices are not necessarily well
    conditioned with respect to the eigenvalue problem.  In single precision
    there may then be discrepancies between the allocated eigenvalues and the
    eigenvalues computed from the closed loop matrix, but this should not be
    construed as a problem with the algorithm or with the subroutine. Direct
    comparison of the computed  F  matrices in single and double precision
    should remove any lingering doubts. Brief comments on each test can be
    found in the file test.doc.

7.  Command files  *.sh  of UNIX shell scripts to run each executable:
      ddemo.sh  runs  ddemo.x  with input  test*.dat, (*=01,...,20)
                                  output is directed to file  ddemo.log
      sdemo.sh  runs  sdemo.x  with input  test*.dat, (*=01,...,20)
                                  output is directed to file  sdemo.log

8.  Logs of the output from the demonstration programs run with the above
    shell scripts and data files on an HP 9000/720 computer:
      dlog.ref contains the double precision output.
      slog.ref contains the single precision output.
