INSTALL

### Consult README.md first for standard installs of pbdMPI
###
### Consider reading pbdMPI vignette at
### https://CRAN.R-project.org/package=pbdMPI
### The vignette was written for pbdMPI version 0.3-0 and is still relevant.
###
### Also, pbdDEMO vignette at
### https://CRAN.R-project.org/package=pbdDEMO, now archived, has many examples.
###
### This file is for installation from source on Linux and on Windows.
### See `INSTALL.win.src' below for a source installation for Windows system.
### See `INSTALL.win.bin' below for a binary installation for Windows system.

--- 'OpenMPI' Installation on Linux from downloaded source
(see also https://docs.open-mpi.org/en/main/installing-open-mpi/quickstart.html):
   Obtain 'OpenMPI' from 'http://www.open-mpi.org/'

     > tar zxvf openmpi-4.1.5.tar.gz
     > cd openmpi-4.1.5
     > ./configure
     > ./make
     > ./make install

   These install files to '/usr/local/bin', '/usr/local/lib', and
   '/usr/local/include' etc.  i.e. ${MPI_ROOT} is '/usr/local'.


--- Set environment variables:
   For 'csh' or 'tcsh', I would set

     > setenv PATH /usr/local/bin:$PATH
     > setenv LD_LIBRARY_PATH /usr/local/lib:$LD_LIBRARY_PATH

   For 'sh', 'bash', or 'ksh', I would set

     > export PATH=/usr/local/bin:$PATH
     > export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

   - 'PATH' is to make sure I can run 'mpiexec', 'mpirun', or 'orterun'.
   - 'LD_LIBRARY_PATH' is to make sure I can reach 'libmpi.so'.

   *** The other way is to modify '/etc/ld.so.conf' and to use the command
       'ldconfig' to update the system searhing path for 'libmpi.so'.


--- Test 'OpenMPI':
   In order to test if 'OpenMPI' works correctly, I simply run

     > mpiexec -np 2 hostname

   and this should show host name twice if environment variables are correct.


--- 'pbdMPI' Installation:
0. Download and extract 'pbdMPI'

     > tar zxvf pbdMPI_0.5-0.tar.gz

1. Default Installation:
   This should work with most platforms with 'OpenMPI' installed. The
   configuration detects the flags and libraries from
   'mpicc --showme:*' which is more portable.

     > R CMD INSTALL pbdMPI

2. Non-default Installation:

     > R CMD INSTALL pbdMPI \
         --configure-args="--with-mpi-type=OPENMPI \
                           --with-mpi=/usr/local"

3. Unusual Installation:
   Suppose 'PATH' and 'LD_LIBRARY_ATH' are set, but I don't use default paths
   to header files and libraries, then I can install 'pbdMPI' by

     > R CMD INSTALL pbdMPI \
         --configure-args="--with-mpi-type=OPENMPI \
                           --with-mpi-include=/usr/local/ompi/include  \
                           --with-mpi-libpath=/usr/local/ompi/lib" \

   Note that I still need 'PATH' and 'LD_LIBRARY_PATH' to be set correctly in
   this case.


--- Test 'pbdMPI':
   Suppose 'PATH' and 'LD_LIBRARY_ATH' are set correctly, I can run test
   examples by

     > cd pbdMPI/inst/examples/test_spmd/
     > ./00_test_all.sh


### `INSTALL.win.src'

--- 'Rtools' Installation:
   Download 'rtools43-5550-5548.exe' from
   'https://cran.r-project.org/bin/windows/Rtools/'
   and click it to install to

     'C:\rtools43'


--- 'MS-MPI' Installation:
   Download 'MS-MPI v10.1.3' and 'MS-MPI SDK' from
   'https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi'.
   File 'MSMPISetup.exe' is for both 32 and 64 bits system.
   Click on them and install them to the default directories
   'C:\Program Files\Microsoft MPI' for 'mpiexec.exe' and.
   'C:\Program Files (x86)\Microsoft SDKs\MPI' for header files and libraries.


--- Set environment variables:
   Suppose 'R', 'Rtools', and 'MS-MPI' are all installed by default. I have
   a batch file 'set_mpisrc.bat' as the following to set the environment
   variables. In short, 'MPI_ROOT' should be set to 'MS-MPI' root directory,
   and added '%MPI_ROOT%/bin' to 'PATH'.

@ECHO OFF
SET R_HOME=C:\Program Files\R\R-4.3.1\
SET RTOOLS=C:\Rtools\bin\
SET MINGW=C:\rtools43\x86_64-w64-mingw32.static.posix\bin
SET MPI_ROOT=C:\Program Files (x86)\Microsoft SDKs\MPI\
SET MPI_BIN=C:\Program Files\Microsoft MPI\bin\
SET PATH=%R_HOME%;%R_HOME%BIN\;%RTOOLS%;%MINGW%;%MPI_ROOT%;%MPI_BIN%;%PATH_ORG%


--- Test 'MS-MPI':
   In order to test if 'MS-MPI' works correctly, I run

     C:/> set_mpisrc
     C:/> mpiexec -np 2 hostname.exe

   and this should list two host names twice if environment variables are
   correct. User's id and password may be required to launch MS-MPI.


--- 'pbdMPI' Installation:
   Default Installation:

     C:/> set_mpisrc
     C:/> tar zxvf pbdMPI_0.5-0.tar.gz
     C:/> R CMD INSTALL --build --no-test-load pbdMPI
     C:/> R CMD INSTALL pbdMPI_0.5-0.zip


--- Test 'pbdMPI':
   Suppose all environments are set correctly, I can run test examples by

     C:/> set_mpisrc
     C:/> cd pbdMPI\examples\test_spmd\
     C:/> sh 00_test_all.win


### `INSTALL.win.bin'

--- 'MS-MPI' Installation:
   Download 'MS-MPI v10.1.3' from
   'https://learn.microsoft.com/en-us/message-passing-interface/microsoft-mpi'.
   File 'MSMPISetup.exe' is for both 32 and 64 bits system.
   Click on it and install it to the default directory
   'C:\Program Files\Microsoft MPI' for 'mpiexec.exe'.


--- Set environment variables:
   Suppose 'R', 'Rtools', and 'MS-MPI' are all installed by default. I have
   a batch file 'set_mpi.bat' as the following to set the environment
   variables. In short, 'MPI_ROOT' should be set to 'MS-MPI' root directory,
   and added '%MPI_ROOT%/bin' to 'PATH'.

@ECHO OFF
SET R_HOME=C:\Program Files\R\R-4.3.1\
SET MPI_BIN=C:\Program Files\Microsoft MPI\bin\
SET PATH=%R_HOME%;%R_HOME%BIN\;%RTOOLS%;%MINGW%;%MPI_BIN%;%PATH_ORG%


--- Test 'MS-MPI':
   In order to test if 'MS-MPI' works correctly, I run

     C:/> set_mpi
     C:/> mpiexec -np 2 hostname.exe

   and this should list two host names twice if environment variables are
   correct. User's id and password may be required to launch MS-MPI.


--- 'pbdMPI' Installation:
   Default Installation:

     C:/> set_mpi
     C:/> R CMD INSTALL pbdMPI_0.5-0.zip


--- Test 'pbdMPI':
   Suppose all environments are set correctly, I can run test examples by

     C:/> set_mpi
     C:/> mpiexec -np 2 Rscript.exe -e "library(pbdMPI);init();finalize()"