\documentstyle[11pt]{article}
\large
\newlength{\pfspace}
\renewcommand{\baselinestretch}{1.0}   % 1.0 spacing
\setlength{\pfspace}{\baselineskip}

\title {The CL-PVM Package}
\author {Liwei Li and Paul S. Wang\thanks{Work reported herein has been supported in part by the National Science Foundation under Grant CCR-9503650
and CCR-9201800 Software Capitalization Supplement}\\
Institute for Computational Mathematics\\
Department of Mathematics and Computer Science\\
Kent State University}
\input{psfig}  %% get  /usr/local/lib/tex/inputs/psfig.tex
\begin{document}
\maketitle
\bibliographystyle{plain}

\section{Introduction}

{\em Parallel Virtual Machine} (PVM)
is a software package that integrates a heterogeneous network of computers
to form a single parallel/concurrent computing facility \cite{pvm3}.
PVM consists of two parts:  a run-time server and a set of library functions.
A user sets up a {\em hostfile} that lists the names of the hosts
constituting the {\em parallel virtual machine} ({\em pvm}).
A PVM server runs on each host to help manage the {\em pvm}.
Hosts can be added and deleted from the {\em pvm}
dynamically.   The {\em pvm} can be controlled from any constituent
host either interactively from a {\em console} program or
automatically from any {\em PVM tasks}.

A PVM task is an application program that runs on a {\em pvm}
and can use the PVM library functions to interact with other tasks:
sending and receiving messages, initiating subtasks,
detecting errors, etc.  The PVM version 3.0 library is written 
in C allowing direct calls from C programs.
There is also a Fortran 77 interface to give
F77 programs access to the PVM library.

CL-PVM provides a Common Lisp interface enabling
Lisp-based programs to partake in PVM applications.
A wide variety of useful Lisp programs exists including
symbolic computation systems, expert systems, artificial intelligence
systems, knowledge-based systems, and many more.  With CL-PVM,
the PVM library routines can be invoked interactively
from the Lisp toplevel or from Lisp programs.

The CL-PVM package contains a set of Common Lisp functions 
that interfaces Common Lisp (KCL, AKCL, or GCL) to the C-based library
of PVM \cite{pvm3}.  Generally, there is one CL interface function to each
PVM C library function.  The CL function calls its C-based counterpart
and relays data to and from the C function.
This interface is complete and allows Lisp-based programs
to run on a {\em pvm} and thus facilitates the combination of
symbolic, numeric, graphics, and other useful systems in a distributed
fashion (Fig. \ref{fig:1}).
\begin{figure}[hbt]
\begin{centering}
\centerline{\psfig{figure=tool.eps}}
\vspace*{3mm}
\end{centering}
\caption{Tool Integration via PVM}
\label{fig:1}
\end{figure}
CL-PVM also offers a set of tools to aid effective use of the package
with Lisp and MAXIMA tasks.  Documentation, on-line manual pages,
and examples are also included.

CL-PVM is available by public FTP (\verb?ftp.mcs.kent.edu?) in
the directory (\verb?/pub/wang/?).  The package is described here.
Please refer to \cite{clpvm} for more information on the
design and implementation of the Lisp interface to PVM.

\section{File Organization}

The main directory of CL-PVM is \verb?clpvm? and it contains six
directories:
\begin{itemize}
\item {\tt src/}: Lisp source code files for the interface functions to PVM.
\item {\tt lib/}: Compiled files of the \verb?.lsp? source files.
\item {\tt report/}: This article and other useful documents.
\item {\tt tools/}: Useful commands.
\item {\tt examples/}: Complete examples to demonstrate and test the
CL-PVM package.
\item {\tt man/}: On-line manual pages.
\end{itemize}

After installing CL-PVM, first compile the \verb?.o? files for the desired
architectures under \verb?lib/?.  Then perform tests by using the
interface interactively and by running the examples provided.

\section{Interactive Use}

Being interactive, Lisp provides an easy way to test CL-PVM.
Whenever a user invokes Lisp the file \verb?init.lsp?, if present in
the current directory, is loaded into Lisp. 
Thus, CL-PVM can be loaded into Lisp automatically this way.  For example,
\begin{verbatim}
;;;;;;;;;;;;;;;; init.lsp  ;;;;;;;;;;;;;;;;;;;;;
(si::faslink "/usr/local/clpvm/lib/SUN4/clpvm.o" 
             "/usr/local/lib/libpvm3.a -lc")
\end{verbatim}
loads both the \verb?libpvm3.a? library routines and their Lisp interfaces into
Lisp. The \verb?clpvm.o? file is produced by compiling \verb?clpvm.lsp? with the Common Lisp compiler (the {\bf compile} function in
CL).  Once the CL-PVM interface is loaded, Lisp commands such as
\begin{verbatim}
(pvm-spawn "hello_other" "" 0 "condor.mcs.kent.edu" 1 'pids)
\end{verbatim}
can be issued interactively.
See \cite{clpvm}, found in the \verb?report/? directory,
for an example of interactive testing and a sequence of Lisp commands to use.

\section{Lisp Processes as PVM Tasks}

Interactive use is fine, but PVM applications
usually require non-interactive tasks.
A Lisp process can be turned into a PVM task
by writing a simple shell script.  Consider
the \verb?hello.lsp? program with
a top-level call \verb?(hello ...)?.  The following
{\em csh} script can be used:
\begin{verbatim}
#!/bin/csh
set logfile = /tmp/${USER}LOG.$$
set gcl_w_pvm = /usr/local/gcl/gcl+pvm
set gcl_dir = /usr/local/gcl/
echo $0 $argv INVOKED >! $logfile

set cmd = ( hello )
foreach a ( $argv )
    set cmd = ( $cmd \"$a\" )
end

$gcl_w_pvm $gcl_dir >>&! $logfile <<EOF
(if (null (load "$HOME/pvm3/local_disk_bin/hello.o"
        :if-does-not-exist nil))
        (progn (princ "loading hello.o failed.") (bye) ))
( $cmd )
( bye )
EOF
echo FINISHED >>! $logfile
\end{verbatim}
The executable \verb?$gcl_w_pvm? is a version of GCL with CL-PVM
codes already loaded. 

The files \verb?hello.lsp? and \verb?hello_other.lsp? in the
\verb?examples/lisp/? subdirectory of this package show Lisp codes
that uses CL-PVM.  The \verb?hello.o? file in the above script refers
to the Lisp compiled code produced from \verb?hello.lsp?.

This particular script takes one command-line argument indicating the
host where to spawn the \verb?hello_other? task (see \verb?hello.lsp?).
The command-line argument processing shown works in general
for any number of arguments.
Using a shell script to invoke a Lisp process has another advantage:
the program is architecture independent.

Executable shell scripts like the one shown have a common structure and
can be automatically generated given appropriate data.  The
{\bf pvm\_cltask} tool included in the package does just that.

\section{Additional Tools}

At ICM/Kent, we follow an organizational scheme where a centrally
installed PVM root directory is shared by all users.  Each user
locates his/her PVM applications in a standard directory 
(\verb?$HOME/pvm3/? by default) and the \verb?local_disk_bin? subdirectory
therein is assumed to be stored in a file system local to a host.
Anyone adopting the standard setup can also take advantage of a set of
tools that make PVM much easier to use.  See \cite{tool} for
details on the organization and the available tools.

A subset of the tools relates to CL-PVM and is included in this package.
The tools will work without modification when you adopt
the standard organization \cite{tool}.
Minor changes can be made to customize these tools for other PVM
organizations.

Among these tools are
\begin{itemize}
\item {\bf pvmlc} --- a command to compile and distribute CL-coded files 
for PVM tasks on all specified hosts ussed in the form: 
\begin{flushleft}
{\bf pvmlc} {\tt [ -U {\sl compiler} ] [ -H {\sl hostfile} ] {\sl file}.lsp ...}
\end{flushleft}
\item {\bf pvm\_cltask} --- a command used to generate a PVM executable
task in the form of a {\it csh} script when given a list of Lisp object files. 
It is used in the form
\begin{flushleft}
{\bf pvm\_cltask} {\tt [ -L {\sl lisp} ] [ -N {\sl executable} ] {\sl file}.o ...}
\end{flushleft}
The script automatically invokes a user-specified Lisp function
and passes to it any command line arguments.
The generated script can be edited and later distributed by {\bf pvm\_distrib}.
\item {\bf pvm\_distrib} --- a command to distribute PVM executables to
specified hosts used in the form
\begin{flushleft}
{\bf pvm\_distrib} {\tt [ -T {\sl architecture} ] [ -H {\sl hostfile} ] {\sl a.out1} ...}
\end{flushleft}
\end{itemize}
These tools and their documentations are included with the CL-PVM package.

\section{Using PVM from MAXIMA}

With CL-PVM, it is rather simple to run MAXIMA as a PVM task
since the symbolic computation system is built
on top of AKCL.  You can load the CL-PVM interface into MAXIMA
and produce the {\bf maxima+pvm} command to run MAXIMA-based PVM tasks.
This can be done, for example, with
\begin{verbatim}
(si::faslink "/usr/local/lib/clpvm/lib/clpvm3.o"
                       "/usr/local/lib/libpvm3.a -lc")
(si:save-system "maxima+pvm")
\end{verbatim}
The CL-PVM package also includes
\begin{itemize}
\item {\bf pvmmc} --- a command to compile \verb?.lsp? files written
for MAXIMA to run on a {\em pvm}
\item {\bf pvm\_maximatask} --- a command to generate maxima-based PVM tasks.
\end{itemize}
Examples can be found in the \verb?examples/maxima/? subdirectory.

\section{On-line Manual Pages}

Manual pages accessible by the UNIX {\bf man} command are included
in the \verb?man/? directory.   These are written by Liwei Li who
also wrote most of the Lisp interface.  There is one man page for each
Lisp interface routine contained in the \verb?man/man3/? subdirectory.
The \verb?man1? subdirectory contains documentation for the shell-level
tools.

\section{Related Work at Kent}

The Symbolic Computation Group at ICM/Kent is working on many interesting
projects.  Three related items are worth mentioning here:
\begin{itemize}
\item A set of tools to help compile and manage PVM tasks in C, F77,
and Common Lisp in general is available \cite{tool}.
\item A set of functions that interfaces the symbolic package SACLIB
\cite{Sac93} to PVM is available.
\item For efficient transfer of mathematical data among distributed
processes in a heterogeneous environment, such as that represented
by a {\em pvm}, the MP protocol \cite{mp} has been developed.
MP 1.0 is being readied for release in Summer of 1996.
\end{itemize}

\begin{thebibliography}{99}
\bibitem{Sac93}B. Buchberger {\it et al}. {\it SACLIB 1.1 User's Guide}. 
RISC-Report No. 93-19, Linz, Austria, 1993.
\bibitem{pvm3} A. Geist, A. Beguelin, J. Dongarra, W. Jiang, R. Manchek and V. Sunderam, {\em PVM 3 User's Guide and Reference Manual},
Oak Ridge National Laboratory, 1993.
\bibitem{mp} S. Gray, N. Kajler, and P. Wang,
``MP: A Protocol for Efficient Exchange of Mathematical Expressions,''
Proceedings, ISSAC'94, Oxford UK, ACM Press, pp. 330-335, 
July, 1994.
\bibitem{clpvm} 
L. Li and P. S. Wang, ``CL-PVM: A Common Lisp Interface to PVM,'' 
Proceedings\footnote{{\tt http://www.cs.cmu.edu/Web/Groups/pvmug95.html}}, PVM User's Meeting, Pittsburgh, May 7-10, 1995. (Also ICM Technical Report
ICM-199509-01, {\tt http://www.mcs.kent.edu/cgi-bin/publish/access}).
\bibitem{C} P. Wang, {\em An Introduction to ANSI C on UNIX},
PWS Publishing Co. Boston, MA., 1991.
\bibitem{tool} P. S. Wang, ``PVM Guide,'' 
ICM/Kent Technical Report (ICM-199509-02),
Institute for Computational Mathematics, Kent State University,
{\tt http://www.mcs.kent.edu/cgi-bin/publish/access} (1995).
\bibitem{Lisp} R. Wilensky, {\em Common LISPcraft}, W. W. Norton \& Co., N.Y., 1986.
\bibitem{akcl} T. Yuasa and M. Hagiya, ``Kyoto Common Lisp Dictionary'',
        Kyoto University, KCL on-line documentation" 1986.
\end{thebibliography}
\end{document}
