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

Copyright (C) 2008 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 2.2.0 or higher, and a MPI distribution on unix 
platform, MPICH2 or DeinoMPI for Windows on windows platform, and Mac OS X 
10.5.0 or higher. More information can be found in 
        http://www.stats.uwo.ca/faculty/yu/Rmpi


INSTALLATION INSTRUCTIONS:

1. Install LAM-MPI 7.1.4 (http://www.lam-mpi.org). Follow the installation 
   instructions provided by LAM-MPI or simply choose a pre-compiled Linux 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.
  
   On Debian system, it is sufficient to install
	lam3 lam3-dev lam-runtime

   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.

NOTE: If your site has a different MPI such as MPICH installed, Rmpi 
   could still detect it and disable MPI-2 related functions 
   automatically. Unless you remove the part of checking lam-mpi in zzz.R.in 
   file in R directory, you need to create a file lamnodes and put the line
	echo "FAKE lamnodes"
   Make sure lamnodes is executable and in the path. Try
	mpirun -np 1 R
   to start a master R and load Rmpi. 

   If your cluster does not have MPI_Comm_spawn enabled so you cannot 
   use mpi.spawn.Rslaves, there are two ways to launch multiple Rs. 
   a). Save Rprofile in inst (will be in the root directory of Rmpi 
       after installation) as .Rprofile in the working or root directory. 
       Then run, for example,
	 	mpirun -n 9 R --no-save -q
       This will create one master and 8 slaves. Those slaves will behave as 
       though mpi.spawn.Rslaves has been used.
   b). To run multiple Rs without using .Rprofile, add the following line
                R_PROFILE=${R_HOME}/library/Rmpi/Rprofile; export R_PROFILE
       in the R shell script (after "export R_HOME") and rename it, say, Rmpi.
       Then one can use
                mpiexec -n 9 Rmpi --no-save -q
       assuming that Rmpi is in the PATH.
 
2. Install Rmpi. If LAM-MPI is installed in /usr or /usr/local,  run
	R CMD INSTALL Rmpi_version.tar.gz.
   On Debian with lam3, lam3-dev lam-runtime installed, above will work 
   too.
   Rmpi will also detect if MPICH installed in /usr/lib as either 
   /usr/lib/mpi or /usr/lib/mpich. 
   For LAM-MPI or other MPI in a different location, use
	R CMD INSTALL Rmpi_version.tar.gz --configure-args=--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. 

3. 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 cluster. Try
	rsh a_remote_host_machine R --slave
   run a simple command such as 3+8 to see it works. 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(mpi.get.processor.name())
	>mpi.remote.exec(double(10))
	>mpi.remote.exec(double(n)) #will not work if n does not exit on slaves
	>n <- 10
 	>mpi.remote.exec(double, n) #the arg n is passed to double
   If package rlecuyer has been installed, try to use mpi.setup.rngstream
   initialize one (not two).

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

   Try other demos to see if Rmpi works properly:
    
   slave1PI.R and slave2PI.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. Make sure 
   n/maxjoblen is at least equal to or bigger than total number of slaves. 
   Making it twice as big as the total slaves will show load balancing 
   effect.

   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 or use 
   mpi.quit to quit Rmpi and R together.

   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("Please use mpi.close.Rslaves() to close slaves.")
            mpi.close.Rslaves(comm=1)
        }
        print("Please use mpi.quit() to quit R")
        .Call("mpi_finalize")
    }
}
