\documentclass[11pt]{report}

\usepackage{indentfirst}

\usepackage[body={6in,8.5in}]{geometry}

\usepackage{hyperref}

\usepackage{graphicx}

\DeclareGraphicsRule{.ps}{eps}{}{}

\renewcommand{\thesection}{\arabic{section}}

\setcounter{tocdepth}{3}

\setcounter{secnumdepth}{3}

\begin{document}

\begin{center}

{\Large LAPACK Working Note 81\\

Quick Installation Guide for LAPACK on Unix Systems\footnote{This work was

supported by NSF Grant No. ASC-8715728 and NSF Grant No. 0444486}}

\end{center}

\begin{center}

% Edward Anderson\footnote{Current address: Cray Research Inc.,

% 655F Lone Oak Drive, Eagan, MN 55121},

The LAPACK Authors\\

Department of Computer Science \\

University of Tennessee \\

Knoxville, Tennessee 37996-1301 \\

\end{center}

\begin{center}

REVISED: VERSION 3.1.1, February 2007 \\

REVISED: VERSION 3.2.0, November 2008

\end{center}

\begin{center}

Abstract

\end{center}

This working note describes how to install, and test version 3.2.0

of LAPACK, a linear algebra package for high-performance

computers, on a Unix System. The timing routines are not actually included in

release 3.2.0, and that part of the LAWN refers to release 3.0. Also,

version 3.2.0 contains many prototype routines needing user feedback.

Non-Unix installation instructions and

further details of the testing and timing suites are only contained in

LAPACK Working Note 41, and not in this abbreviated version.

%Separate instructions are provided for the Unix and non-Unix

%versions of the test package.

%Further details are also given on the design of the test and timing

%programs.

\newpage

\tableofcontents

\newpage

% Introduction to Implementation Guide

\section{Introduction}

LAPACK is a linear algebra library for high-performance

computers.

The library includes Fortran subroutines for

the analysis and solution of systems of simultaneous linear algebraic

equations, linear least-squares problems, and matrix eigenvalue

problems.

Our approach to achieving high efficiency is based on the use of

a standard set of Basic Linear Algebra Subprograms (the BLAS),

which can be optimized for each computing environment.

By confining most of the computational work to the BLAS,

the subroutines should be

transportable and efficient across a wide range of computers.

This working note describes how to install, test, and time this

release of LAPACK on a Unix System.

The instructions for installing, testing, and timing

\footnote{timing are only provided in LAPACK 3.0 and before}

are designed for a person whose

responsibility is the maintenance of a mathematical software library.

We assume the installer has experience in compiling and running

Fortran programs and in creating object libraries.

The installation process involves untarring the file, creating a set of

libraries, and compiling and running the test and timing programs

\footnotemark[\value{footnote}].

%This guide combines the instructions for the Unix and non-Unix

%versions of the LAPACK test package (the non-Unix version is in Appendix

%~\ref{appendixe}).

%At this time, the non-Unix version of LAPACK can only be obtained

%after first untarring the Unix tar tape and then following the instructions in

%Appendix ~\ref{appendixe}.

Section~\ref{fileformat} describes how the files are organized in the

file, and

Section~\ref{overview} gives a general overview of the parts of the test package.

Step-by-step instructions appear in Section~\ref{installation}.

%for the Unix version and in the appendix for the non-Unix version.

For users desiring additional information, please refer to LAPACK

Working Note 41.

% Sections~\ref{moretesting}

%and ~\ref{moretiming} give

%details of the test and timing programs and their input files.

%Appendices ~\ref{appendixa} and ~\ref{appendixb} briefly describe

%the LAPACK routines and auxiliary routines provided

%in this release.

%Appendix ~\ref{appendixc} lists the operation counts we have computed

%for the BLAS and for some of the LAPACK routines.

Appendix ~\ref{appendixd}, entitled ``Caveats'', is a compendium of the known

problems from our own experiences, with suggestions on how to

overcome them.

\textbf{It is strongly advised that the user read Appendix

A before proceeding with the installation process.}

%Appendix E contains the execution times of the different test

%and timing runs on two sample machines.

%Appendix ~\ref{appendixe} contains the instructions to install LAPACK on a non-Unix

%system.

\section{Revisions Since the First Public Release}

Since its first public release in February, 1992, LAPACK has had

several updates, which have encompassed the introduction of new routines

as well as extending the functionality of existing routines. The first

update,

June 30, 1992, was version 1.0a; the second update, October 31, 1992,

was version 1.0b; the third update, March 31, 1993, was version 1.1;

version 2.0 on September 30, 1994, coincided with the release of the

Second Edition of the LAPACK Users' Guide;

version 3.0 on June 30, 1999 coincided with the release of the Third Edition of

the LAPACK Users' Guide;

version 3.1 was released on November, 2006;

version 3.1.1 was released on November, 2007;

and version 3.2.0 was released on November, 2008.

All LAPACK routines reflect the current version number with the date

on the routine indicating when it was last modified.

For more information on revisions in the latest release, please refer

to the \texttt{revisions.info} file in the lapack directory on netlib.

\begin{quote}

\url{http://www.netlib.org/lapack/revisions.info}

\end{quote}

%The distribution \texttt{tar} file \texttt{lapack.tar.z} that is

%available on netlib is always the most up-to-date.

%

%On-line manpages (troff files) for LAPACK driver and computational

%routines, as well as most of the BLAS routines, are available via

%the \texttt{lapack} index on netlib.

\section{File Format}\label{fileformat}

The software for LAPACK is distributed in the form of a

gzipped tar file (via anonymous ftp or the World Wide Web),

which contains the Fortran source for LAPACK,

the Basic Linear Algebra Subprograms

(the Level 1, 2, and 3 BLAS) needed by LAPACK, the testing programs,

and the timing programs\footnotemark[\value{footnote}].

Users who wish to have a non-Unix installation should refer to LAPACK

Working Note 41,

although the overview in section~\ref{overview} applies to both the Unix and non-Unix

versions.

%Users who wish to have a non-Unix installation should go to Appendix ~\ref{appendixe},

%although the overview in section ~\ref{overview} applies to both the Unix and non-Unix

%versions.

The package may be accessed via the World Wide Web through

the URL address:

\begin{quote}

\url{http://www.netlib.org/lapack/lapack.tgz}

\end{quote}

Or, you can retrieve the file via anonymous ftp at netlib:

\begin{verbatim}

ftp ftp.netlib.org

login: anonymous

password: <your email address>

cd lapack

binary

get lapack.tgz

quit

\end{verbatim}

The software in the \texttt{tar} file

is organized in a number of essential directories as shown

in Figure 1. Please note that this figure does not reflect everything

that is contained in the \texttt{LAPACK} directory. Input and instructional

files are also located at various levels.

\begin{figure}

\vspace{11pt}

\centerline{\includegraphics[width=6.5in,height=3in]{org2.ps}}

\caption{Unix organization of LAPACK 3.0}

\vspace{11pt}

\end{figure}

Libraries are created in the LAPACK directory and

executable files are created in one of the directories BLAS, TESTING,

or TIMING\footnotemark[\value{footnote}]. Input files for the test and

timing\footnotemark[\value{footnote}] programs are also

found in these three directories so that testing may be carried out

in the directories LAPACK/BLAS, LAPACK/TESTING, and LAPACK/TIMING \footnotemark[\value{footnote}].

A top-level makefile in the LAPACK directory is provided to perform the

entire installation procedure.

\section{Overview of Tape Contents}\label{overview}

Most routines in LAPACK occur in four versions: REAL,

DOUBLE PRECISION, COMPLEX, and COMPLEX*16.

The first three versions (REAL, DOUBLE PRECISION, and COMPLEX)

are written in standard Fortran and are completely portable;

the COMPLEX*16 version is provided for

those compilers which allow this data type.

Some routines use features of Fortran 90.

For convenience, we often refer to routines by their single precision

names; the leading `S' can be replaced by a `D' for double precision,

a `C' for complex, or a `Z' for complex*16.

For LAPACK use and testing you must decide which version(s)

of the package you intend to install at your site (for example,

REAL and COMPLEX on a Cray computer or DOUBLE PRECISION and

COMPLEX*16 on an IBM computer).

\subsection{LAPACK Routines}

There are three classes of LAPACK routines:

\begin{itemize}

\item \textbf{driver} routines solve a complete problem, such as solving

a system of linear equations or computing the eigenvalues of a real

symmetric matrix. Users are encouraged to use a driver routine if there

is one that meets their requirements. The driver routines are listed

in LAPACK Working Note 41~\cite{WN41} and the LAPACK Users' Guide~\cite{LUG}.

%in Appendix ~\ref{appendixa}.

\item \textbf{computational} routines, also called simply LAPACK routines,

perform a distinct computational task, such as computing

the $LU$ decomposition of an $m$-by-$n$ matrix or finding the

eigenvalues and eigenvectors of a symmetric tridiagonal matrix using

the $QR$ algorithm.

The LAPACK routines are listed in LAPACK Working Note 41~\cite{WN41}

and the LAPACK Users' Guide~\cite{LUG}.

%The LAPACK routines are listed in Appendix ~\ref{appendixa}; see also LAPACK

%Working Note \#5 \cite{WN5}.

\item \textbf{auxiliary} routines are all the other subroutines called

by the driver routines and computational routines.

%Among them are subroutines to perform subtasks of block algorithms,

%in particular, the unblocked versions of the block algorithms;

%extensions to the BLAS, such as matrix-vector operations involving

%complex symmetric matrices;

%the special routines LSAME and XERBLA which first appeared with the

%BLAS;

%and a number of routines to perform common low-level computations,

%such as computing a matrix norm, generating an elementary Householder

%transformation, and applying a sequence of plane rotations.

%Many of the auxiliary routines may be of use to numerical analysts

%or software developers, so we have documented the Fortran source for

%these routines with the same level of detail used for the LAPACK

%routines and driver routines.

The auxiliary routines are listed in LAPACK Working Note 41~\cite{WN41}

and the LAPACK Users' Guide~\cite{LUG}.

%The auxiliary routines are listed in Appendix ~\ref{appendixb}.

\end{itemize}

\subsection{Level 1, 2, and 3 BLAS}

The BLAS are a set of Basic Linear Algebra Subprograms that perform

vector-vector, matrix-vector, and matrix-matrix operations.

LAPACK is designed around the Level 1, 2, and 3 BLAS, and nearly all

of the parallelism in the LAPACK routines is contained in the BLAS.

Therefore,

the key to getting good performance from LAPACK lies in having an

efficient version of the BLAS optimized for your particular machine.

Optimized BLAS libraries are available on a variety of architectures,

refer to the BLAS FAQ on netlib for further information.

\begin{quote}

\url{http://www.netlib.org/blas/faq.html}

\end{quote}

There are also freely available BLAS generators that automatically

tune a subset of the BLAS for a given architecture. E.g.,

\begin{quote}

\url{http://www.netlib.org/atlas/}

\end{quote}

And, if all else fails, there is the Fortran~77 reference implementation

of the Level 1, 2, and 3 BLAS available on netlib (also included in

the LAPACK distribution tar file).

\begin{quote}

\url{http://www.netlib.org/blas/blas.tgz}

\end{quote}

No matter which BLAS library is used, the BLAS test programs should

always be run.

Users should not expect too much from the Fortran~77 reference implementation

BLAS; these versions were written to define the basic operations and do not

employ the standard tricks for optimizing Fortran code.

The formal definitions of the Level 1, 2, and 3 BLAS

are in \cite{BLAS1}, \cite{BLAS2}, and \cite{BLAS3}.

The BLAS Quick Reference card is available on netlib.

\subsection{Mixed- and Extended-Precision BLAS: XBLAS}

The XBLAS extend the BLAS to work with mixed input and output

precisions as well as using extra precision internally. The XBLAS are

used in the prototype extra-precise iterative refinement codes.

The current release of the XBLAS is available through

Netlib\footnote{Development versions may be available through

\url{http://www.cs.berkeley.edu/~yozo/} or

\url{http://www.nersc.gov/~xiaoye/XBLAS/}.} at

\begin{quote}

\url{http://www.netlib.org/xblas}

\end{quote}

Their formal definition is in \cite{XBLAS}.

\subsection{LAPACK Test Routines}

This release contains two distinct test programs for LAPACK routines

in each data type. One test program tests the routines for solving

linear equations and linear least squares problems,

and the other tests routines for the matrix eigenvalue problem.

The routines for generating test matrices are used by both test

programs and are compiled into a library for use by both test programs.

\subsection{LAPACK Timing Routines (for LAPACK 3.0 and before) }

This release also contains two distinct timing programs for the

LAPACK routines in each data type.

The linear equation timing program gathers performance data in

megaflops on the factor, solve, and inverse routines for solving

linear systems, the routines to generate or apply an orthogonal matrix

given as a sequence of elementary transformations, and the reductions

to bidiagonal, tridiagonal, or Hessenberg form for eigenvalue

computations.

The operation counts used in computing the megaflop rates are computed

from a formula;

see LAPACK Working Note 41~\cite{WN41}.

% see Appendix ~\ref{appendixc}.

The eigenvalue timing program is used with the eigensystem routines

and returns the execution time, number of floating point operations, and

megaflop rate for each of the requested subroutines.

In this program, the number of operations is computed while the

code is executing using special instrumented versions of the LAPACK

subroutines.

\section{Installing LAPACK on a Unix System}\label{installation}

Installing, testing, and timing\footnotemark[\value{footnote}] the Unix version of LAPACK

involves the following steps:

\begin{enumerate}

\item Gunzip and tar the file.

\item Copy and edit the file \texttt{LAPACK/make.inc.example to LAPACK/make.inc}.

\item Edit the file \texttt{LAPACK/Makefile} and type \texttt{make}.

%\item Test and Install the Machine-Dependent Routines \\

%\emph{(WARNING: You may need to supply a correct version of second.f and

%dsecnd.f for your machine)}

%{\tt

%\begin{list}{}{}

%\item cd LAPACK

%\item make install

%\end{list} }

%

%\item Create the BLAS Library, \emph{if necessary} \\

%\emph{(NOTE: For best performance, it is recommended you use the manufacturers' BLAS)}

%{\tt

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make blaslib}

%\end{list} }

%

%\item Run the Level 1, 2, and 3 BLAS Test Programs

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make blas\_testing}

%\end{list}

%

%\item Create the LAPACK Library

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make lapacklib}

%\end{list}

%

%\item Create the Library of Test Matrix Generators

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make tmglib}

%\end{list}

%

%\item Run the LAPACK Test Programs

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make testing}

%\end{list}

%

%\item Run the LAPACK Timing Programs

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make timing}

%\end{list}

%

%\item Run the BLAS Timing Programs

%\begin{list}{}{}

%\item \texttt{cd LAPACK}

%\item \texttt{make blas\_timing}

%\end{list}

\end{enumerate}

\subsection{Untar the File}

If you received a tar file of LAPACK via the World Wide

Web or anonymous ftp, enter the following command:

\begin{list}{}

\item{\texttt{gunzip -c lapack.tgz | tar xvf -}}

\end{list}

\noindent

This will create a top-level directory called \texttt{LAPACK}, which

requires approximately 34 Mbytes of disk space.

The total space requirements including the object files and executables

is approximately 100 Mbytes for all four data types.

\subsection{Copy and edit the file \texttt{LAPACK/make.inc.example to LAPACK/make.inc}}

Before the libraries can be built, or the testing and timing\footnotemark[\value{footnote}] programs

run, you must define all machine-specific parameters for the

architecture to which you are installing LAPACK. All machine-specific

parameters are contained in the file \texttt{LAPACK/make.inc}.

An example of \texttt{LAPACK/make.inc} for a LINUX machine with GNU compilers is given

in \texttt{LAPACK/make.inc.example}, copy that file to LAPACK/make.inc by entering the following command:

\begin{list}{}

\item{\texttt{cp LAPACK/make.inc.example LAPACK/make.inc}}

\end{list}

\noindent

Now modify your \texttt{LAPACK/make.inc} by applying the following recommendations.

The first line of this \texttt{make.inc} file is:

\begin{quote}

SHELL = /bin/sh

\end{quote}

and it will need to be modified to \texttt{SHELL = /sbin/sh} if you are

installing LAPACK on an SGI architecture.

Next, you will need to modify \texttt{FC}, \texttt{FFLAGS},

\texttt{FFLAGS\_DRV}, \texttt{FFLAGS\_NOOPT}, and \texttt{LDFLAGS} to specify

the compiler, compiler options, compiler options for the testing and

timing\footnotemark[\value{footnote}] main programs, and linker options.

Next you will have to choose which function you will use to time in the

\texttt{SECOND} and \texttt{DSECND} routines.

\begin{verbatim}

# Default: SECOND and DSECND will use a call to the

# EXTERNAL FUNCTION ETIME

#TIMER = EXT_ETIME

# For RS6K: SECOND and DSECND will use a call to the

# EXTERNAL FUNCTION ETIME_

#TIMER = EXT_ETIME_

# For gfortran compiler: SECOND and DSECND will use a call to the

# INTERNAL FUNCTION ETIME

TIMER = INT_ETIME

# If your Fortran compiler does not provide etime (like Nag Fortran

# Compiler, etc...) SECOND and DSECND will use a call to the

# INTERNAL FUNCTION CPU_TIME

#TIMER = INT_CPU_TIME

# If none of these work, you can use the NONE value.

# In that case, SECOND and DSECND will always return 0.

#TIMER = NONE

\end{verbatim}

Refer to the section~\ref{second} to get more information.

Next, you will need to modify \texttt{AR}, \texttt{ARFLAGS}, and \texttt{RANLIB} to specify archiver,

archiver options, and ranlib for your machine. If your architecture

does not require \texttt{ranlib} to be run after each archive command (as

is the case with CRAY computers running UNICOS, Hewlett Packard

computers running HP-UX, or SUN SPARCstations running Solaris), set

\texttt{RANLIB = echo}. And finally, you must

modify the \texttt{BLASLIB} definition to specify the BLAS library to which

you will be linking. If an optimized version of the BLAS is available

on your machine, you are highly recommended to link to that library.

Otherwise, by default, \texttt{BLASLIB} is set to the Fortran~77 version.

If you want to enable the XBLAS, define the variable \texttt{USEXBLAS}

to some value, for example \texttt{USEXBLAS = Yes}. Then set the

variable \texttt{XBLASLIB} to point at the XBLAS library. Note that

the prototype iterative refinement routines and their testers will not

be built unless \texttt{USEXBLAS} is defined.

\textbf{NOTE:} Example \texttt{make.inc} include files are contained in the

\texttt{LAPACK/INSTALL} directory. Please refer to

Appendix~\ref{appendixd} for machine-specific installation hints, and/or

the \texttt{release\_notes} file on \texttt{netlib}.

\begin{quote}

\url{http://www.netlib.org/lapack/release\_notes}

\end{quote}

\subsection{Edit the file \texttt{LAPACK/Makefile}}\label{toplevelmakefile}

This \texttt{Makefile} can be modified to perform as much of the

installation process as the user desires. Ideally, this is the ONLY

makefile the user must modify. However, modification of lower-level

makefiles may be necessary if a specific routine needs to be compiled

with a different level of optimization.

First, edit the definitions of \texttt{blaslib}, \texttt{lapacklib},

\texttt{tmglib}, \texttt{lapack\_testing}, and \texttt{timing}\footnotemark[\value{footnote}] in the file \texttt{LAPACK/Makefile}

to specify the data types desired. For example,

if you only wish to compile the single precision real version of the

LAPACK library, you would modify the \texttt{lapacklib} definition to be:

\begin{verbatim}

lapacklib:

$(MAKE) -C SRC single

\end{verbatim}

Likewise, you could specify \texttt{double, complex, or complex16} to

build the double precision real, single precision complex, or double

precision complex libraries, respectively. By default, the presence of

no arguments following the \texttt{make} command will result in the

building of all four data types.

The make command can be run more than once to add another

data type to the library if necessary.

%If you are installing LAPACK on a Silicon Graphics machine, you must

%modify the respective definitions of \texttt{testing} and \texttt{timing} to be

%\begin{verbatim}

%testing:

% ( cd TESTING; $(MAKE) -f Makefile.sgi )

%\end{verbatim}

%and

%\begin{verbatim}

%timing:

% ( cd TIMING; $(MAKE) -f Makefile.sgi )

%\end{verbatim}

Next, if you will be using a locally available BLAS library, you will need

to remove \texttt{blaslib} from the \texttt{lib} definition. And finally,

if you do not wish to build all of the libraries individually and

likewise run all of the testing and timing separately, you can

modify the \texttt{all} definition to specify the amount of the

installation process that you want performed. By default,

the \texttt{all} definition is set to

\begin{verbatim}

all: lapack_install lib lapack_testing blas_testing

\end{verbatim}

which will perform all phases of the installation

process -- testing of machine-dependent routines, building the libraries,

BLAS testing and LAPACK testing.

The entire installation process will then be performed by typing

\texttt{make}.

Questions and/or comments can be directed to the

authors as described in Section~\ref{sendresults}. If test failures

occur, please refer to the appropriate subsection in

Section~\ref{furtherdetails}.

If disk space is limited, we suggest building each data type separately

and/or deleting all object files after building the libraries. Likewise, all

testing and timing executables can be deleted after the testing and timing

process is completed. The removal of all object files and executables

can be accomplished by the following:

\begin{list}{}{}

\item \texttt{cd LAPACK}

\item \texttt{make cleanobj}

\end{list}

\section{Further Details of the Installation Process}\label{furtherdetails}

Alternatively, you can choose to run each of the phases of the

installation process separately. The following sections give details

on how this may be achieved.

\subsection{Test and Install the Machine-Dependent Routines.}

There are six machine-dependent functions in the test and timing

package, at least three of which must be installed. They are

\begin{tabbing}

MONOMO \= DOUBLE PRECISION \= \kill

LSAME \> LOGICAL \> Test if two characters are the same regardless of case \\

SLAMCH \> REAL \> Determine machine-dependent parameters \\

DLAMCH \> DOUBLE PRECISION \> Determine machine-dependent parameters \\

SECOND \> REAL \> Return time in seconds from a fixed starting time \\

DSECND \> DOUBLE PRECISION \> Return time in seconds from a fixed starting time\\

ILAENV \> INTEGER \> Checks that NaN and infinity arithmetic are IEEE-754 compliant

\end{tabbing}

\noindent

If you are working only in single precision, you do not need to install

DLAMCH and DSECND, and if you are working only in double precision,

you do not need to install SLAMCH and SECOND.

These six subroutines are provided in \texttt{LAPACK/INSTALL},

along with six test programs.

To compile the six test programs and run the tests, go to \texttt{LAPACK} and

type \texttt{make lapack\_install}. The test programs are called

\texttt{testlsame, testslamch, testdlamch, testsecond, testdsecnd} and

\texttt{testieee}.

If you do not wish to run all tests, you will need to modify the

\texttt{lapack\_install} definition in the \texttt{LAPACK/Makefile} to only include the

tests you wish to run. Otherwise, all tests will be performed.

The expected results of each test program are described below.

\subsubsection{Installing LSAME}

LSAME is a logical function with two character parameters, A and B.

It returns .TRUE. if A and B are the same regardless of case, or .FALSE.

if they are different.

For example, the expression

\begin{list}{}{}

\item \texttt{LSAME( UPLO, 'U' )}

\end{list}

\noindent

is equivalent to

\begin{list}{}{}

\item \texttt{( UPLO.EQ.'U' ).OR.( UPLO.EQ.'u' )}

\end{list}

The test program in \texttt{lsametst.f} tests all combinations of

the same character in upper and lower case for A and B, and two

cases where A and B are different characters.

Run the test program by typing \texttt{testlsame}.

If LSAME works correctly, the only message you should see after the

execution of \texttt{testlsame} is

\begin{verbatim}

ASCII character set

Tests completed

\end{verbatim}

The file \texttt{lsame.f} is automatically copied to

\texttt{LAPACK/BLAS/SRC/} and \texttt{LAPACK/SRC/}.

The function LSAME is needed by both the BLAS and LAPACK, so it is safer

to have it in both libraries as long as this does not cause trouble

in the link phase when both libraries are used.

\subsubsection{Installing SLAMCH and DLAMCH}

SLAMCH and DLAMCH are real functions with a single character parameter

that indicates the machine parameter to be returned. The test

program in \texttt{slamchtst.f}

simply prints out the different values computed by SLAMCH,

so you need to know something about what the values should be.

For example, the output of the test program executable \texttt{testslamch}

for SLAMCH on a Sun SPARCstation is

\begin{verbatim}

Epsilon = 5.96046E-08

Safe minimum = 1.17549E-38

Base = 2.00000

Precision = 1.19209E-07

Number of digits in mantissa = 24.0000

Rounding mode = 1.00000

Minimum exponent = -125.000

Underflow threshold = 1.17549E-38

Largest exponent = 128.000

Overflow threshold = 3.40282E+38

Reciprocal of safe minimum = 8.50706E+37

\end{verbatim}

On a Cray machine, the safe minimum underflows its output

representation and the overflow threshold overflows its output

representation, so the safe minimum is printed as 0.00000 and overflow

is printed as R. This is normal.

If you would prefer to print a representable number, you can modify

the test program to print SFMIN*100. and RMAX/100. for the safe

minimum and overflow thresholds.

Likewise, the test executable \texttt{testdlamch} is run for DLAMCH.

If both tests were successful, go to Section~\ref{second}.

If SLAMCH (or DLAMCH) returns an invalid value, you will have to create

your own version of this function. The following options are used in

LAPACK and must be set:

\begin{list}{}{}

\item {`B': } Base of the machine

\item {`E': } Epsilon (relative machine precision)

\item {`O': } Overflow threshold

\item {`P': } Precision = Epsilon*Base

\item {`S': } Safe minimum (often same as underflow threshold)

\item {`U': } Underflow threshold

\end{list}

Some people may be familiar with R1MACH (D1MACH), a primitive

routine for setting machine parameters in which the user must

comment out the appropriate assignment statements for the target

machine. If a version of R1MACH is on hand, the assignments in

SLAMCH can be made to refer to R1MACH using the correspondence

\begin{list}{}{}

\item {SLAMCH( `U' )} $=$ R1MACH( 1 )

\item {SLAMCH( `O' )} $=$ R1MACH( 2 )

\item {SLAMCH( `E' )} $=$ R1MACH( 3 )

\item {SLAMCH( `B' )} $=$ R1MACH( 5 )

\end{list}

\noindent

The safe minimum returned by SLAMCH( 'S' ) is initially set to the

underflow value, but if $1/(\mathrm{overflow}) \geq (\mathrm{underflow})$

it is recomputed as $(1/(\mathrm{overflow})) * ( 1 + \varepsilon )$,

where $\varepsilon$ is the machine precision.

BE AWARE that the initial call to SLAMCH or DLAMCH is expensive.

We suggest that installers run it once, save the results, and hard-code

the constants in the version they put in their library.

\subsubsection{Installing SECOND and DSECND}\label{second}

Both the timing routines\footnotemark[\value{footnote}] and the test routines call SECOND

(DSECND), a real function with no arguments that returns the time

in seconds from some fixed starting time.

Our version of this routine

returns only ``user time'', and not ``user time $+$ system time''.

The following version of SECOND in \texttt{second\_EXT\_ETIME.f, second\_INT\_ETIME.f} calls

ETIME, a Fortran library routine available on some computer systems.

If ETIME is not available or a better local timing function exists,

you will have to provide the correct interface to SECOND and DSECND

on your machine.

Since LAPACK 3.1.1 we provide 5 different flavours of the SECOND and DSECND routines.

The version that will be used depends on the value of the TIMER variable in the make.inc

\begin{itemize}

\item If ETIME is available as an external function, set the value of the TIMER variable in your

make.inc to \texttt{EXT\_ETIME}: \texttt{second\_EXT\_ETIME.f} and \texttt{dsecnd\_EXT\_ETIME.f} will be used.

Usually on HPPA architectures,

the compiler and linker flag \texttt{+U77} should be included to access

the function \texttt{ETIME}.

\item If ETIME\_ is available as an external function, set the value of the TIMER variable in your make.inc

to \texttt{EXT\_ETIME\_}: \texttt{second\_EXT\_ETIME\_.f} and \texttt{dsecnd\_EXT\_ETIME\_.f} will be used.

It is the case on some IBM architectures such as IBM RS/6000s.

\item If ETIME is available as an internal function, set the value of the TIMER variable in your make.inc

to \texttt{INT\_ETIME}: \texttt{second\_INT\_ETIME.f} and \texttt{dsecnd\_INT\_ETIME.f} will be used.

This is the case with gfortan.

\item If CPU\_TIME is available as an internal function, set the value of the TIMER variable in your make.inc

to \texttt{INT\_CPU\_TIME}: \texttt{second\_INT\_CPU\_TIME.f} and \texttt{dsecnd\_INT\_CPU\_TIME.f} will be used.

\item If none of these function is available, set the value of the TIMER variable in your make.inc

to \texttt{NONE}: \texttt{second\_NONE.f} and \texttt{dsecnd\_NONE.f} will be used.

These routines will always return zero.

\end{itemize}

The test program in \texttt{secondtst.f}

performs a million operations using 5000 iterations of

the SAXPY operation $y := y + \alpha x$ on a vector of length 100.

The total time and megaflops for this test is reported, then

the operation is repeated including a call to SECOND on each of

the 5000 iterations to determine the overhead due to calling SECOND.

The test program executable is called \texttt{testsecond} (or \texttt{testdsecnd}).

There is no single right answer, but the times

in seconds should be positive and the megaflop ratios should be

appropriate for your machine.

\subsubsection{Testing IEEE arithmetic and ILAENV}\label{testieee}

%\textbf{If you are installing LAPACK on a non-IEEE machine, you MUST

%modify ILAENV! Otherwise, ILAENV will crash . By default, ILAENV

%assumes an IEEE machine, and does a test for IEEE-754 compliance.}

As some new routines in LAPACK rely on IEEE-754 compliance,

two settings (\texttt{ISPEC=10} and \texttt{ISPEC=11}) have been added to ILAENV

(\texttt{LAPACK/SRC/ilaenv.f}) to denote IEEE-754 compliance for NaN and

infinity arithmetic, respectively. By default, ILAENV assumes an IEEE

machine, and does a test for IEEE-754 compliance. \textbf{NOTE: If you

are installing LAPACK on a non-IEEE machine, you MUST modify ILAENV,

as this test inside ILAENV will crash!}

If \texttt{ILAENV( 10, $\ldots$ )} or \texttt{ILAENV( 11, $\ldots$ )} is

issued, then \texttt{ILAENV=1} is returned to signal IEEE-754 compliance,

and \texttt{ILAENV=0} if the architecture is non-IEEE-754 compliant.

Thus, for non-IEEE machines, the user must hard-code the setting of

(\texttt{ILAENV=0}) for (\texttt{ISPEC=10} and \texttt{ISPEC=11}) in the version

of \texttt{LAPACK/SRC/ilaenv.f} to be put in

his library. There are also specialized testing and timing\footnotemark[\value{footnote}] versions of

ILAENV that will also need to be modified.

\begin{itemize}

\item Testing/timing version of \texttt{LAPACK/TESTING/LIN/ilaenv.f}

\item Testing/timing version of \texttt{LAPACK/TESTING/EIG/ilaenv.f}

\item Testing/timing version of \texttt{LAPACK/TIMING/LIN/ilaenv.f}

\item Testing/timing version of \texttt{LAPACK/TIMING/EIG/ilaenv.f}

\end{itemize}

%Some new routines in LAPACK rely on IEEE-754 compliance, and if non-compliance

%is detected (via a call to the function ILAENV), alternative (slower)

%algorithms will be chosen.

%For further details, refer to the leading comments of routines such

%as \texttt{LAPACK/SRC/sstevr.f}.

The test program in \texttt{LAPACK/INSTALL/tstiee.f} checks an installation

architecture

to see if infinity arithmetic and NaN arithmetic are IEEE-754 compliant.

A warning message to the user is printed if non-compliance is detected.

This same test is performed inside the function ILAENV. If

\texttt{ILAENV( 10, $\ldots$ )} or \texttt{ILAENV( 11, $\ldots$ )} is

issued, then \texttt{ILAENV=1} is returned to signal IEEE-754 compliance,

and \texttt{ILAENV=0} if the architecture is non-IEEE-754 compliant.

To avoid this IEEE test being run every time you call

\texttt{ILAENV( 10, $\ldots$)} or \texttt{ILAENV( 11, $\ldots$ )}, we suggest

that the user hard-code the setting of

\texttt{ILAENV=1} or \texttt{ILAENV=0} in the version of \texttt{LAPACK/SRC/ilaenv.f} to be put in

his library. As aforementioned, there are also specialized testing and

timing\footnotemark[\value{footnote}] versions of ILAENV that will also need to be modified.

\subsection{Create the BLAS Library}

Ideally, a highly optimized version of the BLAS library already

exists on your machine.

In this case you can go directly to Section~\ref{testblas} to

make the BLAS test programs.

\begin{itemize}

\item[a)]

Go to \texttt{LAPACK} and edit the definition of \texttt{blaslib} in the

file \texttt{Makefile} to specify the data types desired, as in the example

in Section~\ref{toplevelmakefile}.

If you already have some of the BLAS, you will need to edit the file

\texttt{LAPACK/BLAS/SRC/Makefile} to comment out the lines

defining the BLAS you have.

\item[b)]

Type \texttt{make blaslib}.

The make command can be run more than once to add another

data type to the library if necessary.

\end{itemize}

\noindent

The BLAS library is created in \texttt{LAPACK/librefblas.a},

or in the user-defined location specified by \texttt{BLASLIB} in the file

\texttt{LAPACK/make.inc}.

\subsection{Run the BLAS Test Programs}\label{testblas}

Test programs for the Level 1, 2, and 3 BLAS are in the directory

\texttt{LAPACK/BLAS/TESTING}.

To compile and run the Level 1, 2, and 3 BLAS test programs,

go to \texttt{LAPACK} and type \texttt{make blas\_testing}. The executable

files are called \texttt{xblat\_s}, \texttt{xblat\_d}, \texttt{xblat\_c}, and

\texttt{xblat\_z}, where the \_ (underscore) is replaced by 1, 2, or 3,

depending upon the level of BLAS that it is testing. All executable and

output files are created in \texttt{LAPACK/BLAS/}.

For the Level 1 BLAS tests, the output file names are \texttt{sblat1.out},

\texttt{dblat1.out}, \texttt{cblat1.out}, and \texttt{zblat1.out}. For the Level

2 and 3 BLAS, the name of the output file is indicated on the first line of the

input file and is currently defined to be \texttt{sblat2.out} for

the Level 2 REAL version, and \texttt{sblat3.out} for the Level 3 REAL

version, with similar names for the other data types.

If the tests using the supplied data files were completed successfully,

consider whether the tests were sufficiently thorough.

For example, on a machine with vector registers, at least one value

of $N$ greater than the length of the vector registers should be used;

otherwise, important parts of the compiled code may not be

exercised by the tests.

If the tests were not successful, either because the program did not

finish or the test ratios did not pass the threshold, you will

probably have to find and correct the problem before continuing.

If you have been testing a system-specific

BLAS library, try using the Fortran BLAS for the routines that

did not pass the tests.

For more details on the BLAS test programs,

see \cite{BLAS2-test} and \cite{BLAS3-test}.

\subsection{Create the LAPACK Library}

\begin{itemize}

\item[a)]

Go to the directory \texttt{LAPACK} and edit the definition of

\texttt{lapacklib} in the file \texttt{Makefile} to specify the data types desired,

as in the example in Section~\ref{toplevelmakefile}.

\item[b)]

Type \texttt{make lapacklib}.

The make command can be run more than once to add another

data type to the library if necessary.

\end{itemize}

\noindent

The LAPACK library is created in \texttt{LAPACK/liblapack.a},

or in the user-defined location specified by \texttt{LAPACKLIB} in the file

\texttt{LAPACK/make.inc}.

\subsection{Create the Test Matrix Generator Library}

\begin{itemize}

\item[a)]

Go to the directory \texttt{LAPACK} and edit the definition of \texttt{tmglib}

in the file \texttt{Makefile} to specify the data types desired, as in the

example in Section~\ref{toplevelmakefile}.

\item[b)]

Type \texttt{make tmglib}.

The make command can be run more than once to add another

data type to the library if necessary.

\end{itemize}

\noindent

The test matrix generator library is created in \texttt{LAPACK/libtmglib.a},

or in the user-defined location specified by \texttt{TMGLIB} in the file

\texttt{LAPACK/make.inc}.

\subsection{Run the LAPACK Test Programs}

There are two distinct test programs for LAPACK routines

in each data type, one for the linear equation routines and

one for the eigensystem routines.

In each data type, there is one input file for testing the linear

equation routines and eighteen input files for testing the eigenvalue

routines.

The input files reside in \texttt{LAPACK/TESTING}.

For more information on the test programs and how to modify the

input files, please refer to LAPACK Working Note 41~\cite{WN41}.

% see Section~\ref{moretesting}.

If you do not wish to run each of the tests individually, you can

go to \texttt{LAPACK}, edit the definition \texttt{lapack\_testing} in the file

\texttt{Makefile} to specify the data types desired, and type \texttt{make

lapack\_testing}. This will

compile and run the tests as described in sections~\ref{testlin}

and ~\ref{testeig}.

%If you are installing LAPACK on a Silicon Graphics machine, you must

%modify the definition of \texttt{testing} to be

%\begin{verbatim}

%testing:

% ( cd TESTING; $(MAKE) -f Makefile.sgi )

%\end{verbatim}

\subsubsection{Testing the Linear Equations Routines}\label{testlin}

\begin{itemize}

\item[a)]

Go to \texttt{LAPACK/TESTING/LIN} and type \texttt{make} followed by the data types

desired. The executable files are called \texttt{xlintsts, xlintstc,

xlintstd}, or \texttt{xlintstz} and are created in \texttt{LAPACK/TESTING}.

\item[b)]

Go to \texttt{LAPACK/TESTING} and run the tests for each data type.

For the REAL version, the command is

\begin{list}{}{}

\item{} \texttt{xlintsts < stest.in > stest.out}

\end{list}

\noindent

The tests using \texttt{xlintstd}, \texttt{xlintstc}, and \texttt{xlintstz} are similar

with the leading `s' in the input and output file names replaced

by `d', `c', or `z'.

\end{itemize}

If you encountered failures in this phase of the testing process, please

refer to Section~\ref{sendresults}.

\subsubsection{Testing the Eigensystem Routines}\label{testeig}

\begin{itemize}

\item[a)]

Go to \texttt{LAPACK/TESTING/EIG} and type \texttt{make} followed by the data types

desired. The executable files are called \texttt{xeigtsts,

xeigtstc, xeigtstd}, and \texttt{xeigtstz} and are created

in \texttt{LAPACK/TESTING}.

\item[b)]

Go to \texttt{LAPACK/TESTING} and run the tests for each data type.

The tests for the eigensystem routines use eighteen separate input files

for testing the nonsymmetric eigenvalue problem,

the symmetric eigenvalue problem, the banded symmetric eigenvalue

problem, the generalized symmetric eigenvalue

problem, the generalized nonsymmetric eigenvalue problem, the

singular value decomposition, the banded singular value decomposition,

the generalized singular value

decomposition, the generalized QR and RQ factorizations, the generalized

linear regression model, and the constrained linear least squares

problem.

The tests for the REAL version are as follows:

\begin{list}{}{}

\item \texttt{xeigtsts < nep.in > snep.out}

\item \texttt{xeigtsts < sep.in > ssep.out}

\item \texttt{xeigtsts < svd.in > ssvd.out}

\item \texttt{xeigtsts < sec.in > sec.out}

\item \texttt{xeigtsts < sed.in > sed.out}

\item \texttt{xeigtsts < sgg.in > sgg.out}

\item \texttt{xeigtsts < sgd.in > sgd.out}

\item \texttt{xeigtsts < ssg.in > ssg.out}

\item \texttt{xeigtsts < ssb.in > ssb.out}

\item \texttt{xeigtsts < sbb.in > sbb.out}

\item \texttt{xeigtsts < sbal.in > sbal.out}

\item \texttt{xeigtsts < sbak.in > sbak.out}

\item \texttt{xeigtsts < sgbal.in > sgbal.out}

\item \texttt{xeigtsts < sgbak.in > sgbak.out}

\item \texttt{xeigtsts < glm.in > sglm.out}