\documentstyle{article}

\begin{document}

\pagestyle{empty}

\title{Release Notes:\\
       Southampton {\em High Performance Fortran} Translation System,
       Beta release 0.1}

\author{D.B. Carpenter and J.H. Merlin}

\maketitle

\pagestyle{plain}

%\sloppy

\section{Overview of the release}

The Southampton HPF translation system is realised as a translator from
HPF \cite{hpf} to standard Fortran.  The generated Fortran contains
calls to an HPF run-time system, which in turn makes calls to an
underlying message-passing library.

Concurrency and data parallel execution are obtained from the use
of array syntax, e.g. array assignments, array external and intrinsic
functions and the \verb$WHERE$ statement and construct.
\verb$DO$-loops are not parallelised.  The HPF \verb$FORALL$ statement
is supported but is sequentialised, so the user is encouraged to use
array assignments rather than \verb$FORALL$ for this version.  We intend
to provide data-parallel execution of \verb$FORALL$ in a later release
of the system.

Programs compiled with the beta release are slow.  Our development
efforts so far have been directed towards initial implementation of
Subset HPF, rather than optimisation.  For example, some of the code
generated by the translator is obviously inefficient and could be
easily optimised, but we have not had time to look at these refinements
yet.  The run-time library supplied is implemented quite
naively---common operations can probably be speeded by an order of
magnitude.

These obvious optimisations will be incorporated in the next release of
the system.  The current release is made available simply as an HPF
development and testing environment.

Please report bugs to \verb$bug-hpf@par.soton.ac.uk$, or use the
automatic bug reporting form at
\verb$http://hpcc.soton.ac.uk/RandD/hpf/bug_report.html$


\section{Using the hpf script}

HPF programs are compiled by invoking a script called \verb$hpf$, which
calls the translator, then the Fortran compiler.  Finally it calls the
linker, automatically linking in the necessary run-time libraries.

{\em All} of the source code for an HPF program (including any library
procedures it uses) must be translated, even parts of the code
containing no HPF directives.  This is because the translation process
modifies procedure names and their argument lists, even in the absence
of HPF data mapping directives.

The result of compilation is an executable which is run in a manner
appropriate to the underlying message-passing platform.  An HPF program
can be run on {\em P} processors if and only if the size (the product
of extents) of every processor arrangement defined explicitly or
implicitly in the program is either {\em P} or 1.

The syntax of the \verb$hpf$ command is
\begin{verbatim}
  hpf [-help] [-dryrun] [-T|-c] [-o OUT_FILE]
      [-C=CHECK] [-stack STACK_SIZE] [-procRANK EXTENT ...]
      [-temp=TEMP_DIR] [-v] [-w]
      [-compOpts COMP_OPTS] [-linkOpts LINK_OPTS]
      FILE ... [-lLIB_NAME] ...
\end{verbatim}

\subsection*{Source files}

HPF source files have one of the suffixes \verb$.hpf$, \verb$.hpf90$ or
\verb$.h90$.  In the first case the source format is assumed to be
fixed (the old Fortran 77 style); in the latter two cases the source
format is ``free'' (the format new to Fortran 90).

\verb$hpf$ also accepts files with suffix \verb$.f$.  These are assumed
to be Fortran files which have been generated previously by translation
of HPF---for example by using \verb$hpf -T$.  They are passed straight
to the compiler and linked with the appropriate run-time libraries.

\verb$hpf$ will accept files with suffix \verb$.o$ or \verb$.a$.  These
are object files, passed straight to the linker.  Again, they would
normally have been created by an earlier invocation of \verb$hpf$.

\subsection*{Options to hpf}

\subsubsection*{-help}

Display a list of options.

\subsubsection*{-dryrun}

Show but do not execute commands constructed by the \verb$hpf$ script.

\subsubsection*{-T}

Translate only.  Output the intermediate Fortran.  Note
that unless the \verb$-o$ option is specified, existing \verb$.f$ files with
the same base name as the HPF source will be overwritten.

\subsubsection*{-c}

Translate and compile only (do not link).  This produces \verb$.o$ files.

\subsubsection*{-l {\em LIB\_NAME}}

Use the library \verb$lib${\em LIB\_NAME}\verb$.a$.  This option is passed to
the linker.

\subsubsection*{-o {\em OUT\_FILE}}

Name the final output file {\em OUT\_FILE}.  If no \verb$-o$ option is
specified, the generated executable is called \verb$a.out$.  This option
can also be used to name files created with the \verb$-c$ or \verb$-T$
options.


\subsubsection*{-C={\em CHECK}}

Compile in run-time checks specified by {\em CHECK}.  Recognised values
for {\em CHECK} are
\begin{description}
\item{\verb$stack$}
Check that temporary arrays do not exhaust the amount of memory
reserved for them.  This amount can be increased (or reduced) using the
\verb$-stack$ option.
\end{description}

\subsubsection*{-stack {\em STACK\_SIZE}}

Reserve {\em STACK\_SIZE} words of memory for temporary arrays.
The default is 250000.

\subsubsection*{-proc{\em RANK} {\em EXTENT} \ldots}

In HPF \verb$DISTRIBUTE$ directives, the \verb$ONTO$ clause specifies a
processor arrangement over which the array is to be distributed.  The
\verb$ONTO$ clause is optional.  If it is omitted the compiler selects
a default processor arrangement.  The \verb$-proc${\em RANK} options
allow the shape of the default processor arrangements to be specified.
At most one default processor arrangement shape can be specified for
each possible {\em RANK} between 1 and 7.  The \verb$-proc${\em RANK}
flag should be followed by precisely {\em RANK} numeric extent
fields, defining the shape.  For example
\begin{verbatim}
  -proc2 5 6
\end{verbatim}
specifies that default rank-2 processor array has shape (5,6).

\subsubsection*{-temp={\em TEMP\_DIR}}

Set the directory used for temporary files to {\em TEMP\_DIR}.
The default is the current working directory.

\subsubsection*{-v}

Verbose.  Print the commands constructed by the \verb$hpf$ script as
they are executed.

\subsubsection*{-w}

Suppress warning messages.

\subsubsection*{-compOpts {\em COMP\_OPTS}}

Append the string {\em COMP\_OPTS} to to the list of options passed to
the target compiler.

\subsubsection*{-linkOpts {\em LINK\_OPTS}}

Append the string {\em LINK\_OPTS} to to the list of options passed to
the linker.


\section{The example suite}

The release comes with a set of example codes in the \verb$examples$
subirectory.

In this section we assume the provision of a script \verb$hpfrun$.
This runs an executable generated by the \verb$hpf$ command on
a specified number of processes.  An HPF program suitable for
execution on 3 processors might be compiled and executed by
\begin{verbatim}
  hpf test.hpf
  hpfrun 3 a.out
\end{verbatim}

The example codes are divided into three subdirectories

\subsection{tests directory}

Simple codes designed primarily to exercise the HPF run-time library.
The codes
\begin{verbatim}
  test0.h90
  test1.h90
  test2.h90
  ...
  test6.h90
\end{verbatim}
should be executed on 4 processes, eg
\begin{verbatim}
  hpf -o test1 test1.h90
  hpfrun 4 test1
\end{verbatim}
The codes
\begin{verbatim}
  test7.h90
  test8.h90
  test9.h90
  ...
\end{verbatim}
should be executed on 6 processes, eg
\begin{verbatim}
  hpf -o test7 test7.h90
  hpfrun 6 test7
\end{verbatim}
A script \verb$runtests$ will compile and execute all the programs
in the directory.

\subsection{parkbench directory}

Kernels taken from the Parkbench benchmark suite.  These are intermediate
sized codes.  The codes
\begin{verbatim}
  fl.hpf
  tm.hpf
  aa.hpf
  sh.hpf
  ir.hpf
  as.hpf
\end{verbatim}
are suitable for execution on 4 processors, eg
\begin{verbatim}
  hpf -o fl fl.hpf
  hpfrun 4 fl
\end{verbatim}
The codes
\begin{verbatim}
  st.hpf
  rd.hpf
\end{verbatim}
are suitable for execution on 8 processors, eg
\begin{verbatim}
  hpf -o st st.hpf
  hpfrun 8 st
\end{verbatim}
A script \verb$runtests$ will compile and execute all the programs
in the directory.

\subsection{genesis directory}

Codes taken from the Genesis benchmark suite.  These are small to
medium-size application codes.  Each program is split over several
files in its own subdirectory.  The subdirectories are
\begin{verbatim}
  pde1
  pde2
  trans1
  fft1
  md1
\end{verbatim}
\verb$make$ files are provided in the subdirectories.  All codes are suitable
for execution on 4 processors, eg
\begin{verbatim}
  cd pde1
  make
  hpfrun 4 pde1
\end{verbatim}
The HPF translator doesn't yet support the Fortran 90 intrinsic
\verb$DATA_AND_TIME$.  A timer routine, \verb$ctimer$, is provided.
\verb$ctimer$ is written in C.  In principle, this makes the programs
non-portable, but the versions provided will probably work on most UNIX
platforms.  \verb$ctimer$ returns the time local to each process---it's
result is not a globally consistent HPF value.  The translator has no way
of knowing this, so careless use of the returned value (for example, in
control constructs) could cause run-time errors.

\section{Language restrictions}

The translator accepts the official `Subset HPF' language 
(as defined in Section 8 of the `HPF Language Specification')
with some restrictions.  It recognises {\em full\/} HPF (including 
full Fortran 90) and gives error messages upon encountering 
unsupported features.  This section lists those features in 
Subset HPF that are {\em not\/} supported in this version (V0.1).

Incidentally, some Fortran 90 features that are not in strict
Subset HPF, e.g.\ the {\tt SELECT CASE} construct, {\em are\/} supported.

\subsection{Fortran 77 features}

\subsubsection*{Sequence and storage association}

The \verb$EQUIVALENCE$ statement is not supported;  partitioning of
common blocks differently in different program units is not supported.

Associating an array {\em element} actual argument with an array
dummy argument is not supported; reshaping of arrays across
procedure interfaces is not supported.

\subsubsection*{DATA statements and BLOCK DATA}

Neither are supported.

\subsubsection*{I$/$O}

Implied \verb$DO$ loops in \verb$READ$, \verb$WRITE$ or \verb$PRINT$
statements are not supported.

The ``\verb$ERR =$'', ``\verb$END =$'' and ``\verb$EOR =$'' specifiers
in I$/$O statements, are not supported (if the program is executed on
more than one abstract processor.)

\subsubsection*{CHARACTER variables}

Variables, named constants and functions of \verb$CHARACTER$ type are
not supported (though character literal constants and expressions {\em
are} supported).

Specification of \verb$CHARACTER$ type in an \verb$IMPLICIT$ statement
is not supported.

\subsubsection*{Assumed size arrays}

Fortran 77 {\em assumed size} arrays are not supported.  
These are dummy arguments declared with an asterisk in their extent
field.  (Fortran 90 assumed {\em shape} arrays {\em are} supported.)

\subsubsection*{Specification expressions}

A {\em specification expression} is an expression used in a
declaration, for example, as an array extent.  The HPF implementation
does not support references to arrays or references to distributed data
in specification expressions.

\subsubsection*{Termination of a DO loops}

Termination of a \verb$DO$ loop at a statement other than \verb$ENDDO$
or \verb$CONTINUE$ is not supported.

\subsubsection*{Statement functions}

Statement functions---``in-line'' definitions of functions within
other procedures---are not supported.

\subsubsection*{ENTRY statement}

Multiple entry points into a single procedure are not supported.

\subsection{Fortran 90 features in Subset HPF}

\subsubsection*{Array constructors}

Array constructors---lists of values between the brackets \verb$(/$
\verb$/)$, used to represent one-dimensional arrays---are not
supported.

\subsubsection*{ALLOCATABLE arrays}

\verb$ALLOCATABLE$ arrays and the \verb$ALLOCATE$ and \verb$DEALLOCATE$
statements are not supported.

\subsubsection*{Initialisation of variables in type declarations}

This is not supported.

\subsection{HPF features in the Subset}

\subsubsection*{SEQUENCE directive}

The \verb$SEQUENCE$ directive is not supported.

\subsubsection*{Distribution of PARAMETERs}

Explicit distribution of \verb$PARAMETER$ values is not supported.

\subsubsection*{Inherited and transcriptive mappings}

The HPF \verb$INHERIT$ attribute or directive is not supported.

Transcriptive distribution format and transcriptive distribution
target are not supported.  These are formats and targets consisting of
a single asterisk.

\subsubsection*{FORALL statement}

In a \verb$FORALL$ statement, references to the assignment variable
or any part of it in a subscript expression, the right-hand-side
expression, or the mask expression, are not supported.


\subsection{Miscellaneous intrinsic procedures}

The following intrinsic functions and subroutines are not supported.

\subsubsection* {Fortran 77 string-handling and inquiry functions}
\verb$REPEAT$, \verb$TRIM$ and \verb$LEN$

\subsubsection*{Array inquiry functions}
\verb$ALLOCATED$, \verb$LBOUND$, \verb$SHAPE$, \verb$SIZE$ and
\verb$UBOUND$

\subsubsection*{Array construction functions}
\verb$PACK$ and \verb$UNPACK$

\subsubsection*{Intrinsic subroutines}
\verb$DATE_AND_TIME$, \verb$MVBITS$, \verb$RANDOM_NUMBER$,
\verb$RANDOM_SEED$ and \verb$SYSTEM_CLOCK$

\subsubsection*{HPF system inquiry intrinsic functions}
\verb$NUMBER_OF_PROCESSORS$ and \verb$PROCESSORS_SHAPE$

\subsubsection*{Other usage restrictions}

The following intrinsic functions can only appear as primaries
on the right-hand-side of an assignment statement (and not
in any other context):
\begin{verbatim}
MATMUL, SPREAD, RESHAPE, TRANSPOSE
\end{verbatim}

% The HPF run-time library does not support the optional \verb$MASK$
% parameter on \verb$MAXLOC$ and \verb$MINLOC$.

\section{Known bugs}

\begin{enumerate}
\item
The \verb$hpf$ script executes very slowly if the release is configured
to use GNU g++ as the linker.

\item
The code \verb$examples/fft1$ hangs under the EUI-based MPICH
implementation, running on the SP2.  This is believed to be due to a
problem with \verb$MPI_Waitany$ on that platform.  This problem is
under investigation.

\item
The code \verb$examples/fft1$ hangs intermittently under the P4-based
MPICH implementation, running on an RS6000 workstation.  This problem
is under investigation.

\end{enumerate}


\begin{thebibliography}{9}

\bibitem{hpf} {\em High Performance Fortran Language Specification.}
High Performance Fortran Forum.

\end{thebibliography}


\end{document}


