
\documentstyle{article}

\begin{document}
\pagestyle{plain}

\title{{\em Adlib} version 1.0, \\
       Release Notes}

\author{D.B. Carpenter}

\maketitle

\section{Overview of the release}

Version 1.0 of Adlib is implemented as a C++ class library built
on top of MPI.
Please report bugs and suggestions for improvement to \verb$dbc@npac.syr.edu$.

Section \ref{use-adpp} of this document describes how to use the
\verb$ad++$ command (information which is also provided by the \verb$ad++$
`manual page').  Section \ref{examples} describes the suite of
example programs provided with the Adlib release.

\section{\label{use-adpp}Using \tt ad++}

An Adlib program typically has the form
\begin{verbatim}
#include "ad++.h"

// ...

void main(int argc, char* argv[]) {
  AdlibInit(argc, argv) ;

  // ...

  AdlibFinalize() ;
}
\end{verbatim}
An \verb$AdlibInit$ call with precisely the interface illustrated
should be made before {\em any} other Adlib call.  In particular,
initialisation must precede any call to a constructor from an Adlib
class.  In general therefore, Adlib objects may not be declared as static
entities (of course, {\em pointers} to such objects can be declared as
static entities).

Adlib programs are compiled using a script called \verb$ad++$, which
calls the local C++ compiler with options to search the correct
directory for Adlib header files, and to link in the Adlib library
code.

The result of compilation is an executable file.  The procedure for
running this file depends on the underlying message-passing platform.

The usage of the ad++ command is
\begin{verbatim}
  ad++ [options] [files] [libraries]
\end{verbatim}
where the options are options recognised by the local C++ compiler.

\section{The example suite}
\label{examples}

The Adlib release contains a set of example codes in the 
\verb$examples$ subirectory.

In this section we assume the provision of a script \verb$prun$.
This runs an executable generated by the \verb$ad++$ command on
a specified number of processes.  An Adlib program suitable for
execution on 3 processors might be compiled and executed by
\begin{verbatim}
  ad++ test.C
  prun 3 a.out
\end{verbatim}
An example version of \verb$prun$ is provided in the Adlib \verb$bin$
directory, but you will have to tailor this script according
to your local message-passing environment.

There is presently only one subdirectory of \verb$examples$.

\subsection{{\tt tests} directory}

Simple codes designed primarily to test the Adlib library.
The codes
\begin{verbatim}
  test0.h90
  test1.h90
  test2.h90
  ...
  test6.h90
\end{verbatim}
are best executed on 4 processes, e.g.:
\begin{verbatim}
  ad++ -o test1 test1.C
  prun 4 test1
\end{verbatim}
The codes
\begin{verbatim}
  test7.C
  test8.C
  test9.C
  test10.C
  test14.C
  test17.C
  testGather.C
  testMultiShift.C
  testScatterComb.C
  testStep.C
\end{verbatim}
are best executed on 6 processes, e.g.:
\begin{verbatim}
  ad++ -o test7 test7.C
  prun 6 test7
\end{verbatim}
The codes
\begin{verbatim}
  testSArray.C
  testGprintf.C
  testGscanf.C
\end{verbatim}
do not involve distributed data, so any number of processors will do,
e.g.:
\begin{verbatim}
  ad++ -o testSArray testSArray.C
  prun 3 testSArray
\end{verbatim}

A script \verb$runtests$ will compile and execute all the programs
in the directory (except \verb$testGscanf.C$, which requires keyboard
input).

\end{document}
