Rmpi is an R package providing an interface to MPI (Message-Passing Interface) 
API calls with interactive R slave functionalities. 

Copyright (C) 2002 Hao Yu <hyu@stats.uwo.ca>

******************************************************************************
Rmpi is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License as published by the Free
Software Foundation; either version 2, or (at your option) any later
version.

This program is distributed in the hope that it will be useful, but WITHOUT
ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.
    
You should have received a copy of the GNU General Public License along with 
this program; if not, write to the Free Software Foundation, Inc., 59 Temple 
Place, Suite 330, Boston, MA  02111-1307  USA
******************************************************************************

Rmpi requires R version 1.3.0 or higher, LAM-MPI 6.5.6, and SPRNG 2.0. Rmpi 
works only for Unix (Linux Redhat 7.2 on INTEL PIII Xeon SMP and 
Linux Redhat 7.1 on Compaq alpha SMP Beowulf clusters are tested) at 
present. A Beowulf cluster should be set up properly before attemping Rmpi.

INSTALLATION INSTRUCTIONS:

1. Install LAM-MPI 6.5.6 (http://www.lam-mpi.org). Follow the installation 
   instructions provided by LAM-MPI or simply choose a pre-compiled Linux RPM 
   such as
	http://www.lam-mpi.org/download/files/lam-6.5.6-tcp.1.i386.rpm 
   Modify the file lam-bhost.def (probably in /etc/lam) to include host names 
   and CPU numbers per host in a cluster. A remote shell program such as 
   rsh or ssh must be set properly otherwise LAM-MPI will not be functional. 
   This requires no password prompt when remotely executing a program. Check 
   LAM-MPI documents or FAQ to configure the default remote shell program.
   Notice that LAM-MPI must be installed on all hosts within a cluster.
   Make sure LAM executable programs are in the PATH.

   Once LAM-MPI has been installed and properly configured, login as a 
   non-root user and boot to LAM by
	lamboot -v
   and run LAM test suite to see if it works properly. Try to run
	lamexec C hostname
   to see all nodes response with their host names.

2. Install SPRNG 2.0 (http://sprng.cs.fsu.edu/sprng.html). Modify the file 
   make.CHOICES to enable MPI in SPRNG: uncomment out 
	MPIDEF = -DSPRNG_MPI
   Uncomment out also
	PLAT = (your_platform) #only one PLAT. must comment out others
	PMLCGDEF = -DUSE_PMLCG
	GMPLIB = -lgmp
   Modify appropriate make.(PLAT) file in SRC directory. For LAM-MPI, choose
	MPILIB = -lmpi -llam
   MPI include and lib paths must be supplied if they are in nonstandard 
   locations. For example, for Compaq alpha platform, change
	MPIDEF = -DSPRNG_MPI -I/myMPI/include 
	MPIDIR =-L/myMPI/lib

   Before compiling, find the following line in SRC/pmlcg/pmlcg.c:
    	#include "gmp.h"
   and change it to
    	#include <gmp.h>
   to use the system header file. 

   During compiling, it may fail compiling programs in EXAMPLES. This will 
   create no harm as long as the library libsprng.a is built in lib 
   directory. If there is no error compiling EXAMPLES, go to EXAMPLES, 
   run some MPI enabled programs such as sprng_mpi and run
	mpirun C sprng_mpi

3. Install Rmpi. If LAM-MPI is installed in /usr or /usr/local and SPRNG in 
   /usr/local/sprng or /usr/local/sprng2, run
	R INSTALL Rmpi_version.tar.gz.
   
   For LAM-MPI and SPRNG in different locations, use
	R INSTALL Rmpi_version.tar.gz \
	--configure-args="--with-sprng=/sprngpath --with-mpi=/mpipath"

   Notice that R and Rmpi have to be installed on all hosts in a cluster. The 
   paths (directories) to R and Rmpi must be the same on all hosts in a 
   cluster otherwise Rmpi may have difficult to spawn R slaves. Using a NFS 
   file system and putting R and Rmpi on it should work. The same issue 
   applies to user's home directory: it should be the same across a 
   cluster of computers. 

4. Test. Before running R and Rmpi, make sure LAM-MPI is running properly. Use
	lamboot -v
   to boot to LAM and use
	lamclean
   to clean up all MPI states. All LAM-MPI related tasks should be not be run 
   from root. After finishing a MPI related job, use
	lamhalt
   to shut down LAM.

   Make sure R is in the PATH for whole machines. Try
	rsh a_remote_host_machine R --slave
   run a simple command such as 3+8 to see it work. If R is not in PATH or 
   remote machines have difficult find it, one solution is to modify the 
   Rslave.sh file in inst directory and put an absolute path to R.
 
   Load Rmpi library in R (assuming successful) and spawn Rslaves by
   	>mpi.spawn.Rslaves(nslaves=1)  #spawn only one slave
	>mpi.close.Rslaves()	#close slaves
	>mpi.spawn.Rslaves() #spawn slaves to use all CPUs
   Execute some simple commands to R slaves, e.g.,
	>mpi.remote.exec(rnorm(10))
	>mpi.remote.exec(mean(rnorm(10000)))
	>mpi.remote.exec(rnorm(n)) #will not work if n does not exit on slaves
	>n <- 20
 	>mpi.remote.exec(rnorm, n) #the arg n is passed to rnorm

   There are a few demo examples from Rmpi. Use
	demo(package="Rmpi")
   to find them. Try
	demo("simplePI.R")
   and run
	simple.pi(1000000)

   Try other demos to see if Rmpi works properly:
    
   slave1PI.R, slave2PI.R and simPI.R have two functions each: master and slave 
   functions. User should use mpi.spawn.Rslaves to spawn R slaves first and 
   then run the master function with proper arguments. simPI.R has a plot 
   in it so trying it in X-windows.

   cslavePI.R and masterslave.R use mpi.comm.spawn to spawn their own slaves. 
   Close R slaves if they are alive.

*******************************************************************************
Final note: It is extremely important that users should close R slaves and Rmpi 
properly before quiting R. Basically, use mpi.close.Rslaves to close R slaves  
and use mpi.exit to exit Rmpi environment.

To safe guard at site level, administrator can add the .Last function to 
Rprofile.site as

.Last <- function(){
    if (is.loaded("mpi_initialize")){
        if (mpi.comm.size(1) > 0){
            print("It seems some slaves running or mpi.comm.free() is not used")
            if (length(system("mpitask",TRUE)) >2){
                print("Running mpi.close.Rslaves().")
                mpi.close.Rslaves()
            }
            else {
                print("Running mpi.comm.free().")
                mpi.comm.free(1)
            }
        }
        print("Exiting Rmpi. Please use mpi.exit() before quitting R")
        .Call("mpi_finalize")
    }
}
*****************************************************************************
