##############################################################################
#                                                                            #
#                               PDHSEQR README                               #
#                                                                            #
#   Contributers:  Robert Granat                                             #
#                  Bo Kagstrom                                               #
#                  Daniel Kressner                                           #
#                  Meiyue Shao                                               #
#                                                                            #
#   Department of Computing Science and HPC2N, Umea University               #
#   MATHICSE ANCHP, EPF Lausanne                                             #
#                                                                            #
##############################################################################


1. Introduction
===============
PDHSEQR is a parallel ScaLAPACK-style library for solving nonsymmetric
standard eigenvalue problems, using the Hessenberg QR algorithm with aggressive
early deflation on distributed memory HPC systems.

The source code can be downloaded from
    http://calgo.acm.org/
or the software homepage
    http://www8.cs.umu.se/~myshao/software/pdhseqr/

2. How to Install
=================
The library is written in Fortran 90.  To install the library, you need a
Fortran 90/95 compiler.  In addition, the following libraries are required.

    1) MPI, e.g., OpenMPI or MPICH.
    2) An optimized BLAS library, e.g., ATLAS or OpenBLAS,
       see http://www.netlib.org/blas/ for a reference implementation.
    3) LAPACK, see http://www.netlib.org/lapack/
    4) ScaLAPACK (including BLACS and PBLAS),
       see http://www.netlib.org/scalapack/

Follow the instruction below to build the library:

    1) Download and unpack the PDHSEQR archive.
    2) Modify the file "make.inc" to setup the compilers, linkers, and
       libraries.  Examples files for GNU, PathScale, and Intel are provided
       in the directory "MAKE_INC/".
    3) Type "make all" to build the library and test programs.
    4) Run the test programs in the directory "TESTING/" to check whether the
       installation is successful.

More detailed instructions regarding installation and testing can be found in
"PDHSEQR User's guide".

3. Functionalities
==================
The main functionality of the library PDHSEQR is to compute the real Schur
form of an upper Hessenberg matrix.  Notice that only double precision REAL
matrices are currently supported.  A complex version of the software is
planned for future releases.

Two simple examples calling PDHSEQR are provided in the directory "EXAMPLES/".
In each of these examples, the matrix size and blocking factor can be set by
adjusting the parameters in Line 40.  To use your own matrix, replace the call
to PDMATGEN2 or PQRRMMM by your own matrix generator.

4. Comments/Questions/Bug Reports
=================================
Please send your request to bokg@cs.umu.se, myshao@cs.umu.se.

5. Selected References
======================
The following references are helpful for understanding the implementation of
PDHSEQR.

    [1] R. Granat, B. Kagstrom, D. Kressner, and M. Shao, Algorithm xxx:
        Parallel library software for the multishift QR algorithm with
        aggressive early deflation.  ACM Trans. Math. Software, 2014
        (to appear).

    [2] R. Granat, B. Kagstrom, D. Kressner, and M. Shao, PDHSEQR User's Guide,
        Tech. Rep. UMINF-14.24, Department of Computing Science, Umea
        University, 2014.

    [3] R. Granat, B. Kagstrom, and D. Kressner, A novel parallel QR algorithm
        for hybrid distributed memory HPC systems.  SIAM J. Sci. Comput.
        32(4), 2345--2378, 2010.

    [4] B. Kagstrom, D. Kressner, and M. Shao, On aggressive early deflation
        in parallel variants of the QR algorithm.  In Applied Parallel and
        Scientific Computing (PARA 2010), K. Jonasson, Editor, LNCS-7133,
        Springer-Verlag, 1--10, 2012.

    [5] R. Granat, B. Kagstrom, and D. Kressner, Parallel eigenvalue
        reordering in real Schur forms.  Concurrency and Computat.: Pract.
        Exper. 21(9), 1225--1250, 2009.