GEMM-based Level 3 BLAS: High-performance model implementations and
performance evaluation benchmark. March, 1997.
-----------------------------------------------------------------------

The software comes in four different Fortran data types (real, double,
complex, and double complex) and is designed to be easy to install and
use on different platforms.

Software directories:
---------------------
The top level directory includes this README file and the following
five subdirectories for the source code:

GBBEN:  Contains four subdirectories SBENCH, DBENCH, CBENCH, and
        ZBENCH, one subdirectory for each data type of the GEMM-based
        level 3 BLAS performance evaluation benchmark, and furthermore,
        the subdirectory TMGLIB with timing routines. The GEMM-based
        level 3 BLAS performance evaluation benchmark, is a tool for
        evaluating and comparing the performance of different
        implementations of the level 3 BLAS with the GEMM-based model
        implementations. See paper [TOMS-I].

GBL3B:  Contains four subdirectories SGBL3B, DGBL3B, CGBL3B, and
        ZGBL3B, one subdirectory corresponding to each data type of
        the GEMM-based level 3 BLAS model implementations. The model
        implementations are structured to effectively reduce data
        traffic in a memory hierarchy. See paper [TOMS-I].

INSTALL: Contains the machine-dependent functions SECOND, DSECND,
        and LSAME, and a test program for each function. These functions
        should be modified for the target system. The resolution of the
        timing functions should preferably be microseconds or smaller.

TESTING: Contains test programs for the level 3 BLAS (source code in
        subdirectory SRC). These programs test the correctness of
        Level 3 BLAS implementations. The programs are from the LAPACK
        package.

UNDERLIB: Contains underlying BLAS routines called by the GEMM-
        based level 3 BLAS. These underlying routines are "original"
        BLAS implementations from the LAPACK package and they are only
        included for completness. In order to obtain high performance
        they should be replaced by implementations optimized for the
        target machine.

Makefiles:
----------
Each directory in the hierarchy includes a Makefile. The command 'make'
in any of the directories produces all programs and libraries contained
in the current directory and subsequent subdirectories. Similarly, the
command 'make clean' remove alls object files and executables.

Specification of compiler flags, libraries etc:
-----------------------------------------------
The file 'make.inc' in the top directory specifies the Fortran compiler,
loader, archiver, flags, and libraries, and may require changes for
different target systems. Notice that compiler flags for the GEMM-based
level 3 BLAS benchmark and model implementations are specified in the
Makefiles of the subdirectories GBBEN/*BENCH and GBL3B/*GBL3B.

Correctness testing:
--------------------
Executable programs for testing the correctness of the GEMM-based
level 3 BLAS are stored in the subdirectory TESTING. We recommend that
you run the test programs.

We illustrate how the test programs can be executed in a Unix environment.
The test programs stored in the directory TESTING are executed as follows
(example in double precision):

    % xblat3d < dblat3.in

The tests are specified in the example input file 'dblat3.in' and can
be modified as desired. The result of an execution is presented in the
output file 'DBLAT3.SUMM'.

Machine-dependent parameters:
-----------------------------
Each of the GEMM-based model implementations has a few system (machine)
dependent parameters that are given values at compile time. These specify
internal block sizes, cache characteristics, and branch points for
alternative code sections, which are given as input to a program '*sgpm.f'
that facilitates the tuning of these parameters. For simplicity, we also
provide sample values for some common architectures ('*gpm.in'). The
following command given in the subdirectory GBBEN/DGBL3B (double precision):

   % dsgpm < dgpm.in

will change the system dependent parameters in the source code of each
GEMM-based routine according to the specifications in 'dgpm.in'. The
parameters can be specified as desired in 'dgpm.in'.

The benchmark programs have built-in GEMM-based level 3 BLAS routines that
are renamed and used for performance comparison with other specified
level 3 BLAS implementations. The system dependent parameters for these
built-in GEMM-based routines can similarly be changed with the program
'*sbpm.f'.

We refer to the paper [TOMS-II] for detailed information on how to specify
these parameters.

Performance timing:
-------------------
Executable programs for timing the performance of the GEMM-based level 3
BLAS are stored in the subdirectory GBBEN/*BENCH.

We illustrate how the timing programs can be executed in a Unix environment.
The benchmark programs stored in the directories GBBEN/*BENCH are executed
as follows (example in double precision):

   % dgbtim < example.in > example.out

The routines and problems to be timed are specified in the input file
'example.in' and the output result is written to the file 'example.out'.
The tests in the input file can be modified as desired. We propose two
standard test which are enclosed in the files 'dmark01.in' and
'dmark02.in'. The problems in the two tests are similar. However, some
of the matrix dimensions are larger in 'dmark02.in' than in 'dmark01.in'.
See also paper [TOMS-II].

Further information and questions:
----------------------------------
For further information see:

[TOMS-I] GEMM-based Level 3 BLAS: High-performance model
     implementations and performance evaluation benchmark
     (Bo Kagstrom, Per Ling and Charles Van Loan).

[TOMS-II] GEMM-based Level 3 BLAS: Portability and optimization
     issues (Bo Kagstrom, Per Ling and Charles Van Loan).

For questions regarding the installation and use of the software
please contact Per Ling (Per.Ling@cs.umu.se).
