AMPI: add ampirun script (#1766) 27/3527/16
authorMatthias Diener <mdiener@illinois.edu>
Wed, 17 Jan 2018 23:09:40 +0000 (17:09 -0600)
committerMatthias Diener <mdiener@illinois.edu>
Sun, 11 Feb 2018 04:44:26 +0000 (22:44 -0600)
Also adds ampirun to the manual, and to .gitignore/make clean targets.

Change-Id: I2c08bed5fa1ec8ff81040944a10c993a9b1e4306

20 files changed:
.gitignore
doc/ampi/manual.tex
examples/ampi/Cjacobi3D/Makefile
examples/ampi/alltoall/Makefile
examples/ampi/creduce/Makefile
examples/ampi/cuda/simple/Makefile
examples/ampi/onesided/Makefile
examples/ampi/pingpong/Makefile
src/libs/ck-libs/ampi/Makefile
src/libs/ck-libs/ampi/ampiCC
src/libs/ck-libs/ampi/ampirun [new file with mode: 0755]
tests/ampi/chkpt/Makefile
tests/ampi/exit/Makefile
tests/ampi/fallreduce/Makefile
tests/ampi/intercomm_coll/Makefile
tests/ampi/jacobi3d/Makefile
tests/ampi/megampi/Makefile
tests/ampi/migration/Makefile
tests/ampi/speed/Makefile
tests/ampi/stacksize/Makefile

index 4bb75fd951a155cbfa87f145c6365bda0779cc5a..0bcd8c63019c39f1a081bba319d5c7953d33a2f7 100644 (file)
@@ -38,5 +38,6 @@ Charm++-prefix
 # Ignore cruft that would result from compiling charm example/test code
 # Note this is negated inside src/arch to permit addition of new charmrun files in there
 charmrun
+ampirun
 pgm
 *.swp
index 6ac1ddefa89bb1cc4c7c926c61d17e88e045856a..4a3e0773a153ef775a510f2dddffcc2d69e99849 100644 (file)
@@ -1026,7 +1026,7 @@ Fluids on 32 physical processors, one would specify those with multiple
 \verb|+vp| options on the command line as:
 
 \begin{alltt}
-> charmrun gen1.x +p 32 +vp 128 +vp 64
+> ./charmrun gen1.x +p 32 +vp 128 +vp 64
 \end{alltt}
 
 This will ensure that multiple modules representing different complete
@@ -1804,7 +1804,7 @@ support this capability. You can also set the environment variables \texttt{AMPI
 before running a job to override the default specified at build time.
 
 \section{Building and Running AMPI Programs}
-\subsection{Building}
+\subsection{Building AMPI Programs}
 \ampi{} provides a compiler called \emph{ampicc} in your charm/bin/ directory.
 You can use this compiler to build your AMPI program the same way as other
 compilers like cc. All the command line flags that you would use
@@ -1826,18 +1826,22 @@ or a suite of strategies in with \emph{-module \textless LB\textgreater}. For ex
 \end{alltt}
 
 
-\subsection{Running}
+\subsection{Running AMPI programs}
+
+AMPI offers two options to execute an AMPI program, \texttt{charmrun} and \texttt{ampirun}.
+
+\subsubsection{Running with charmrun}
 The \charmpp{} distribution contains a script called \texttt{charmrun} that
 makes the job of running \ampi{} programs portable and easier across all
 parallel machines supported by \charmpp{}. \texttt{charmrun} is copied to a
-directory where an \ampi{} program is built using \emph{ampicc}. It takes a command
+directory where an \ampi{} program is built using \texttt{ampicc}. It takes a command
 line parameter specifying number of processors, and the name of the program
 followed by \ampi{} options (such as number of ranks to create, and the stack size
 of every user-level thread) and the program arguments. A typical invocation of an \ampi{}
 program \texttt{pgm} with \texttt{charmrun} is:
 
 \begin{alltt}
-> charmrun +p16 ./pgm +vp64
+> ./charmrun +p16 ./pgm +vp64
 \end{alltt}
 
 Here, the \ampi{} program \texttt{pgm} is run on 16 physical processors with
@@ -1845,14 +1849,41 @@ Here, the \ampi{} program \texttt{pgm} is run on 16 physical processors with
 
 To run with load balancing, specify a load balancing strategy. If Address Space
 Layout Randomization is enabled on your target system, you may need to add the
-flag \emph{+isomalloc\_sync} when running with migration. You can also specify
-the size of user-level thread's stack using the \emph{+tcharm\_stacksize}
+flag \texttt{+isomalloc\_sync} when running with migration. You can also specify
+the size of user-level thread's stack using the \texttt{+tcharm\_stacksize}
 option, which can be used to decrease the size of the stack that must be
 migrated, as in the following example:
 
 \begin{alltt}
-> charmrun +p16 ./pgm +vp128 +tcharm_stacksize 32K +balancer RefineLB
+> ./charmrun +p16 ./pgm +vp128 +tcharm_stacksize 32K +balancer RefineLB
+\end{alltt}
+
+
+\subsubsection{Running with ampirun}
+
+For compliance with the MPI standard and simpler execution, \ampi{} ships with the 
+\texttt{ampirun} script that is similar to \texttt{mpirun} provided by other MPI 
+runtimes. As with \texttt{charmrun}, \texttt{ampirun} is copied automatically to 
+the program directory when compiling an application with \texttt{ampicc}.
+
+The basic usage of ampirun is as follows:
+\begin{alltt}
+> ./ampirun -np 16 --host h1,h2,h3,h4 ./pgm
 \end{alltt}
+This command will create 16 (non-virtualized) ranks and distribute them on the hosts h1--h4.
+
+When using the \texttt{-vr} option, AMPI will create the number of ranks specified by the \texttt{-np} parameter as virtual ranks, and will create only one process per host:
+\begin{alltt}
+> ./ampirun -np 16 --host h1,h2,h3,h4 -vr ./pgm
+\end{alltt}
+
+Other options (such as the load balancing strategy), can be specified in the same way as for charmrun:
+\begin{alltt}
+> ./ampirun -np 16 ./pgm +balancer RefineLB
+\end{alltt}
+
+
+\subsubsection{Other options}
 
 Note that for AMPI programs compiled with gfortran, users may need to set the following
 environment variable to see program output to stdout:
index 92916679cc70f68f06f342096b7a5537a6d345bc..4bdbe55d4beca0eb81c725346b8979b060ebbcfd 100644 (file)
@@ -47,5 +47,5 @@ bgtest: jacobi
        [ ! -s "jacobi.iso" ] || $(call run, +p2 ./jacobi.iso 2 2 2 10 +vp8 +balancer RotateLB +x2 +y2 +z1 )
 
 clean:
-       rm -f *.o jacobi *~ moduleinit.C charmrun conv-host jacobi-cpp jacobi.iso jacobi-get jacobi.tls
+       rm -f *.o jacobi *~ moduleinit.C charmrun conv-host jacobi-cpp jacobi.iso jacobi-get jacobi.tls ampirun
        rm -rf 40 80 120
index d9ec7e0289e5c153174f6acb36c29b0198a2693e..f68b7d6f2a474229913614adc0fb845f0719c582 100644 (file)
@@ -38,4 +38,4 @@ alltoall_VPtest_f: alltoall_VPtest.f
        $(CHARMF) -o alltoall_VPtest_f alltoall_VPtest.o -swapglobals $(OPTS) $(LIBS)
 
 clean:
-       rm -rf *~ *.o alltoall mpibench charmrun conv-host allgather
+       rm -rf *~ *.o alltoall mpibench charmrun conv-host allgather ampirun
index c042e4590ece9aa0d9554551558f9dec7df182fe..d48d5420642018341fa0083caf4f470ea66c65f2 100644 (file)
@@ -13,7 +13,7 @@ mpi: test.C
        mpiCC -o pgm test.C $(OPTS)
 
 clean:
-       rm -f *.o *.mod pgm *~ conv-host charmrun
+       rm -f *.o *.mod pgm *~ conv-host charmrun ampirun
 
 test: pgm
        $(call run, ./pgm +p1 +vp1 )
index eacb1df5769c30615996a78034da67bc7acf245f..c05884c238928e121ae0ebb4ccd4adc109688826 100644 (file)
@@ -25,4 +25,4 @@ test:
        $(call run, +p2 ./simple +vp 16)
 
 clean:
-       rm -f charmrun simple *.o
+       rm -f charmrun simple *.o ampirun
index 2f4256122f3a41727e7badf75066fbfdc45c1f1f..855e6643732c8e8ca63d533e75c1cdbf21eaa631 100644 (file)
@@ -21,5 +21,5 @@ test: all
        $(call run, +p2 ./IgetTest 100000 16 +vp2)
 
 clean:
-       rm -rf charmrun conv-host moduleinit* *.o GetPutTest IgetTest GetPutTest-mpi *~ *.sts core
+       rm -rf charmrun conv-host moduleinit* *.o GetPutTest IgetTest GetPutTest-mpi *~ *.sts core ampirun
 
index bbf097ea8ddd3a99dde648e26a7bbf0e22bc3ce7..278067fef2c5087c6890e2ef658cbb11bfa52227 100644 (file)
@@ -19,5 +19,5 @@ test: all
        $(call run, +p2 ./pgm 100000 16 +vp2)
 
 clean:
-       rm -rf charmrun conv-host moduleinit* *.o pingpong pgm pgm-mpi pgm-pipe pgm-pipe-mpi *~ *.sts core
+       rm -rf charmrun conv-host moduleinit* *.o pingpong pgm pgm-mpi pgm-pipe pgm-pipe-mpi *~ *.sts core ampirun
 
index 24f59e76d47ebb332ec56814fe15970ae6c3e669..5435036a730bff545fb78a25a917a4e4979385c9 100644 (file)
@@ -98,6 +98,7 @@ headers: $(HEADERS)
        cp ampiCC $(CDIR)/bin/ampicxx
        cp ampif77 $(CDIR)/bin/ampif77
        cp ampif90 $(CDIR)/bin/ampif90
+       cp ampirun $(CDIR)/bin/ampirun
        touch headers
 
 compat_ampius.o: compat_ampius.C
index 90df02510b1293de4a1b1d4f880a2f38bd030749..a96281077ad2235138915504c0d56d8ccea21c11 100755 (executable)
@@ -42,4 +42,7 @@ then
     rmdir $dirName
 fi
 
+# Copy ampirun, but do not overwrite it if it already exists.
+cp -n $CHARMBIN/ampirun .
+
 exit $status
diff --git a/src/libs/ck-libs/ampi/ampirun b/src/libs/ck-libs/ampi/ampirun
new file mode 100755 (executable)
index 0000000..87715cc
--- /dev/null
@@ -0,0 +1,122 @@
+#!/bin/bash
+
+set -o nounset -o posix -o pipefail
+
+progname=$(basename $0)
+
+verbose=0
+num_ranks=1
+num_hosts=0
+
+virtual_ranks=0
+
+cmd=""
+hosts=""
+
+usage() {
+  echo
+  echo "Usage: $progname [options] <program>"
+  echo
+  echo "Options:"
+  echo "    -h|--help                 Show this help"
+  echo "    -v|--verbose              Verbose output"
+  echo "    -n|-np|--np|-p <#ranks>   Number of ranks"
+  echo "    --host <host1,host2,...>  Comma-separated list of hosts"
+  echo "    -vr|--vr                  Use virtual ranks"
+  echo
+  echo "Other options will be passed unmodified to charmrun."
+}
+
+
+handle_hosts() {
+  if [[ -z $hosts ]]; then
+    num_hosts=1
+    return
+  fi
+
+  echo "group main" > ampirun-nodelist
+
+  IFS=","
+  for n in $hosts; do
+    num_hosts=$((num_hosts+1))
+    echo "  host $n" >> ampirun-nodelist
+  done
+}
+
+
+processArgs() {
+  while [[ ! $# == 0 ]]
+  do
+    arg="$1"
+    shift
+
+    case "$arg" in
+      -h|--help)
+        usage
+        exit 0
+        ;;
+      -v|--verbose)
+        verbose=1
+        ;;
+
+      -n|-np|--np|-p)
+        num_ranks=$1
+        shift
+        ;;
+
+      --host)
+        hosts=$1
+        shift
+        ;;
+
+      -vr|--vr)
+        virtual_ranks=1
+        ;;
+
+      *)
+        cmd+="$arg "
+        ;;
+    esac
+  done
+}
+
+eval processArgs "$@"
+
+if [[ -z $cmd ]]; then
+  echo "$progname error: missing command to execute"
+  usage
+  exit 2
+fi
+
+handle_hosts
+
+full_cmd="./charmrun "
+
+if [[ $verbose == 0 ]]; then
+  full_cmd+="++quiet "
+fi
+
+if [[ -z $hosts ]]; then
+  full_cmd+="++local "
+else
+  full_cmd+="++nodelist ampirun-nodelist "
+fi
+
+full_cmd+="$cmd"
+
+if [[ $virtual_ranks == 0 ]]; then
+  full_cmd+="+p$num_ranks "
+else
+  full_cmd+="+vp$num_ranks +p$num_hosts "
+fi
+
+if [[ $verbose == 1 ]]; then
+  echo "Executing '$full_cmd'"
+fi
+
+eval $full_cmd
+status=$?
+
+rm -f ampirun-nodelist
+
+exit $status
index e55a80518f2fb45e429f110437894699d449f92d..e3721b1805cd7e230631e59b6b7e74a1bbe909e0 100644 (file)
@@ -26,5 +26,5 @@ bgtest: clean ampi
        $(call run, +p2 ./hello +vp8 +restart log +x2 +y1 +z1)
 
 clean:
-       rm -f *.o *.mod moduleinit.C hello *~ conv-host charmrun
+       rm -f *.o *.mod moduleinit.C hello *~ conv-host charmrun ampirun
        rm -rf log
index e07e4add4b2ee7efc1184c5b3286454138fcfd9a..0e0ab384dbbf854764aa9d88b372fc165708b425 100644 (file)
@@ -12,4 +12,4 @@ test: clean test_exit
        @rm -f tmp.out
 
 clean:
-       rm -f *.o test_exit charmrun
+       rm -f *.o test_exit charmrun ampirun
index 71c66061d56dcd451c71312a487ba0790c363934..43015c5b9eb61a84b9ccca6c0b57b44573e93041 100644 (file)
@@ -13,7 +13,7 @@ pgm.o: pgm.f90
 # clean up .o, .mod, .exe and EMACS backup files
 #
 clean:
-       rm -f *.o *.mod pgm *~ conv-host charmrun
+       rm -f *.o *.mod pgm *~ conv-host charmrun ampirun
 
 test: pgm
        $(call run, ./pgm +p2 +vp4 )
index d1e6ad0faa772fc53eb685a63453abe0a3e63677..d32dee5a659a7b2f412ceab78bdbf022e677c386 100644 (file)
@@ -18,4 +18,4 @@ bgtest: intercomm_coll
 #      $(call run, ./intercomm_coll +p2 +vp4 +x2 +y1 +z1 )
 
 clean:
-       rm -f *.o *.mod intercomm_coll *~ conv-host charmrun intercomm_coll.o charmrun.exe intercomm_coll.exe intercomm_coll.pdb intercomm_coll.ilk
+       rm -f *.o *.mod intercomm_coll *~ conv-host charmrun intercomm_coll.o charmrun.exe intercomm_coll.exe intercomm_coll.pdb intercomm_coll.ilk ampirun
index c1a432a3d9c4e678a7d5651a15d660eb2cf0258a..05871656b8091a31d0a55c6e21f5f4c709523b5c 100644 (file)
@@ -16,5 +16,5 @@ syncfttest causalfttest: jacobi
        $(call run, ./jacobi 4 2 2 200 +vp16 +p8 +balancer DummyLB +isomalloc_sync +killFile kill_02.txt )
 
 clean:
-       rm -f *.o jacobi jacobi.o *~ moduleinit.C charmrun conv-host jacobi-cpp jacobi.iso jacobi-get jacobi.tls
+       rm -f *.o jacobi jacobi.o *~ moduleinit.C charmrun conv-host jacobi-cpp jacobi.iso jacobi-get jacobi.tls ampirun
        rm -rf 40 80 120
index f7007a875c5cb2d4569e00e636b57bcdc0ba4bcc..75fd34e7e47701887f56862c7e72853cac290b96 100644 (file)
@@ -14,7 +14,7 @@ test.o: test.C
 # clean up .o, .mod, .exe and EMACS backup files
 #
 clean:
-       rm -f *.o *.mod pgm *~ conv-host charmrun test.o pgm.exe pgm.pdb pgm.ilk
+       rm -f *.o *.mod pgm *~ conv-host charmrun test.o pgm.exe pgm.pdb pgm.ilk ampirun
 
 test: pgm
        $(call run, ./pgm +p1 +vp1 )
index 5ef51d77145da58e26df7c5833e07eb1bd73257d..641e6d61c83fb518fd2eb627cb1fab92a2361d2a 100644 (file)
@@ -14,7 +14,7 @@ test.o: test.C
 # clean up .o, .mod, .exe and EMACS backup files
 #
 clean:
-       rm -f *.o *.mod pgm *~ conv-host charmrun test.o charmrun.exe pgm.exe pgm.pdb pgm.ilk
+       rm -f *.o *.mod pgm *~ conv-host charmrun test.o charmrun.exe pgm.exe pgm.pdb pgm.ilk ampirun
 
 test: pgm
        $(call run, ./pgm +p1 +vp1 )
index 370cb405d7f83eb9749e061b163d7872f3845aea..5a452e592dab8f2050b1e80ad0895c5e45c902ac 100644 (file)
@@ -12,7 +12,7 @@ hello.decl.h: hello.ci
        $(CHARMC)  hello.ci
 
 clean:
-       rm -f *.decl.h *.def.h conv-host *.o hello charmrun *.log *.sum *.sts charmrun.exe hello.exe hello.pdb hello.ilk
+       rm -f *.decl.h *.def.h conv-host *.o hello charmrun *.log *.sum *.sts charmrun.exe hello.exe hello.pdb hello.ilk ampirun
 
 hello.o: hello.C hello.decl.h
        $(CHARMC) -c hello.C
index 5f51aa4b48aad61ba0de23f209019dd26064af16..15572005b50b20301137b547f1276f041571943f 100644 (file)
@@ -10,7 +10,7 @@ test.o: test.c
        $(CHARMC) -c test.c
 
 clean:
-       rm -f *.o *.mod pgm *~ conv-host charmrun charmrun.exe pgm.exe pgm.pdb pgm.ilk
+       rm -f *.o *.mod pgm *~ conv-host charmrun charmrun.exe pgm.exe pgm.pdb pgm.ilk ampirun
 
 test: pgm
        $(call run, ./pgm +p2 +vp4 )