*******************************************************************************
*                                                                             *
*                                    HAPACK                                   * 
*      Fortran 77 routines for solving skew-Hamiltonian and Hamiltonian       *
*                               eigenvalue problems                           *
*                         by P. Benner and D. Kressner                        *
*                                                                             *
*******************************************************************************
*                          RELEASE: 1.1 (03-Sep-2005)                         *
*******************************************************************************


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

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


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

The distribution file, named "hapack.tar.gz", contains the source code
of HAPACK as well as example programs and data.
The untaring of the file "hapack.tar.gz" creates the directory "hapack" 
in the current directory.

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

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

examples:
  This directory contains test programs with sample input and output
  data.

src:
  This directory contains the source codes of HAPACK.

To continue the installation, change to the "hapack" directory:
	cd hapack

Steps to build HAPACK:
======================

1. Edit the file "make.inc" and set the macros according to your system.
   For example, on Linux the macros should be set to:
     FORTRAN    = f77                            # Fortran 77 compiler
     OPTS       = -O3                            # Fortran 77 compiler optimizing options.
     LOADER     = f77                            # Fortran-77 linker command.
     BLASLIB    = -L/usr/site-local/lib -lblas   # Location of the BLAS library
     LAPACKLIB  = -L/usr/site-local/lib -llapack # Location of the LAPACK library

2. Type "make" to build the library. This step will build the object
   files, the library, and the example programs. The library can be
   found under "hapack.a" in the main directory.
   
3. To run a test program change to the subdirectory "examples" and
   type, e.g., "thaesu < dhaesu.dat". If everything works properly the
   output should be similar to the one contained in the file
   "dhaesu.res".


List of available Fortran subroutines in HAPACK
===============================================

Driver subroutines

DHAESU
   Computes the eigenvalues and the symplectic URV/periodic Schur
   decomposition of a Hamiltonian matrix.

DHASUB
   Computes stable and unstable invariant subspaces of a Hamiltonian
   matrix from the output of {\tt DHAESU}.

DSHES
   Computes the skew-Hamiltonian Schur decomposition of a skew-
   Hamiltonian matrix.

Computational subroutines

DGESQB
   Symplectic QR decomposition of a general matrix. Blocked version.

DGESQR & 
   Symplectic QR decomposition of a general matrix. Unblocked version.

DGESUB
   Symplectic URV decomposition of a general matrix. Blocked version.

DGESUV
   Symplectic URV decomposition of a general matrix. Unblocked version.

DHABAK
   Applies the inverse of a balancing transformation, computed by the
   routines DHABAL or DSHBAL.

DHABAL
   Symplectic balancing of a Hamiltonian matrix.

DHAORD
   Reorders the (skew-)Hamiltonian Schur decomposition of a (skew-)
   Hamiltonian matrix.

DHAPVB
   PVL decomposition of a Hamiltonian matrix. Blocked version.

DHAPVL
   PVL decomposition of a Hamiltonian matrix. Unblocked version.

DHGPQR
   Periodic Schur decomposition of a product of two matrices.

DOSGPV
   Generates the orthogonal symplectic matrix U from a PVL
   decomposition determined by DHAPVL or DSHPVL.
   
DOSGSB
   Generates all or part of the orthogonal symplectic matrix Q from
   a symplectic QR decomposition determined by DGESQB or DGESQR.
   Blocked version.
   
DOSGSQ
   Generates all or part of the orthogonal symplectic matrix Q from
   a symplectic QR decomposition determined by DGEQRB or DGEQRS.
   Unblocked version.
   
DOSGSU
   Generates the orthogonal symplectic matrices U and V from a
   symplectic URV decomposition determined by DGESUB or DGESUV.

DOSMPV
   Applies the orthogonal symplectic matrix $U$ from a PVL decomposition
   determined by DHAPVL or DSHPVL to a general matrix.

DOSMSB
   Applies all or part of the orthogonal symplectic matrix Q from a
   symplectic QR decomposition determined by DGESQB or DGESQR to a
   general matrix. Blocked version.

DOSMSQ
   Applies all or part of the orthogonal symplectic matrix Q from a
   symplectic QR decomposition determined by DGESQB or DGESQR to a
   general matrix. Unblocked version.

DSHBAL
   Symplectic balancing of a skew-Hamiltonian matrix.

DSHPVB
   PVL reduction of a skew-Hamiltonian matrix. Blocked version.

DSHPVL
   PVL reduction of a skew-Hamiltonian matrix. Unblocked version.

DSHSNA
   Computes reciprocal condition numbers for the eigenvalues and some
   eigenvectors of a skew-Hamiltonian matrix in skew-Hamiltonian Schur
   form.

Auxiliary subroutines

DCROOT
   Computes the square root of a complex number in real arithmetic.

DHAEX2
   Swaps adjacent diagonal blocks in a (skew-)Hamiltonian Schur
   decomposition.

DLABMX
   Auxiliary subroutine for DHASUB.

DLAESB
   Applies the WY representation for a product of elementary
   orthogonal symplectic transformation.

DLAEST
   Constructs the WY representation for a product of elementary
   orthogonal symplectic transformation.

DLANHA
   Norm of a (skew-)Hamiltonian matrix.

DLAPQR
   Periodic Schur decomposition of a product of two small matrices.

DLAPV2
   Periodic Schur decomposition of a product of two 2-by-2 matrices.

DLAPVB
   Panel reduction for PVL decomposition.

DLASUB
   Panel reduction for symplectic URV decomposition.

DSKMV
   Skew-symmetric matrix-vector product.

DSKR2
   Skew-symmetric rank-2 update.

DSKR2K
   Skew-symmetric rank-2k update.

DSKRKB
   Computes alpha C + beta A B A^T for skew-symmetric matrices B and C.

DSKUPD
   Computes Z A Z^T for a skew-symmetric matrix A.

DTGPX2
   Swaps adjacent diagonal blocks in a periodic Schur decomposition.

DTGPY2
   Solution of a small periodic Sylvester equation.

DTRQML
   Computes matrix-matrix products involving a quasi-triangular matrix.

ILAHAP
   Problem-dependent parameters for the local environment.


Acknowledgments
===============

We thank Tim R. Hopkins and Vasile Sima for testing the functionality of HAPACK
and suggesting various improvements.


In case of problems:
====================

Send an e-mail to:
	benner@mathematik.tu-chemnitz.de
	kressner@cs.umu.se
