Blue Gene Emulator 
Parallel Programming Lab, UIUC

Contacts:
Gengbin Zheng  (gzheng@uiuc.edu)     (217.244.3667)
Arun Singla    (asingla@cs.uiuc.edu) (217.333.5827)
Joshua Unger   (unger1@uiuc.edu)     (217.333.5827)
Laxmikant Kale (kale@cs.uiuc.edu)    (217.244.0094)

The code in this directory is:

Sample Applications:
====================
ring.C        -> "Ring" broadcast algorithm -> sends message along to next
                 node and upon reaching node on edge of machine, advances line
                 like a typewriter until all nodes are reached.
                 command-line options:
                 ./ring +x <x> +y <y> +z <z> +cth <numCommTh> +wth <numWorkTh>
line.C        -> "Line" broadcast algorithm -> sends message along like ring,
                 but sends in three directions (x,y,z) for faster spreading 
                 message.
                 command-line options:
                 ./line <x> <y> <z> <numCommTh> <numWorkTh> <numIter>
maxReduceNV.C -> Reduction algorithm to find the maximum value over all nodes
                 and send results to node 0,0,0.  This implemenation uses
		 "node variables" (see documentation) which is the preferred
		 way to program storage of node-specific data.
                 command-line options:
                 ./maxReduceNV <x> <y> <z> <numCommTh> <numWorkTh>
maxReduce.C   -> Reduction algorithm to find the maximum value over all nodes
                 and send results to node 0,0,0.  This implemenation uses
		 static array  which is the non-preferred way to program storage
		 of node-specific data.
                 command-line options:
                 ./maxReduce +cth<numCommTh> +wth<numWorkTh>
prime.C       -> Computes number of primes in a given range
                 command-line options:
                 ./prime <x> <y> <z> <numCommTh> <numWorkTh> <range>
jacobi3D.C    -> Jacobi Relaxation in 3D
                 command-line options:
                  ./jacobi3D <BG_x> <BG_y> <BG_z> <numCommTh> <numWorkTh> 
                             <epsilon> [<x>] [<y>] [<z>]
ping.C        -> Ping-pong time benchmark for communication between nodes mapped
 	       to same processor and between nodes mapped to different processor
                 command-line options:
                 ./ping <x> <y> <z> <numCommTh> <numWorkTh>
octo.C        -> "Octo" broadcast algorithm -> divides machine into eight cubes,
                 sends message to center of cube, which is recursively divided
                 into eight cubes, etc...
                 command-line options:
                 octo <x> <y> <z> <numComm> <numWork>
littleMD/     -> little MD program.
                 command-line options:
                 ./bgMD <x> <y> <z> <numCommTh> <numWorkTh>
run           -> an example shell script to run all programs above.
Makefile      -> Makes all code


1. To build this code, Charm++ must be installed on your system.  Download 
   the latest version of Charm++ following the instructions:
     http://charm.cs.uiuc.edu/download.shtml
   Read REAME and build Charm++ using the following command:
     build <target> <version> [charmc-options ...]
   Just type build get a list of the possible value of parameters. 

2. Edit the Makefile in this directory and change the paths to point to your 
   charm version following the existing examples in the Makefile. Finally, 
   type "make" using the Makefile provided in this directory 

3. To run the programs (depending on your machine type) you will have to make
   a file called nodelist in the run directory that contains:

     group main
     host host1.domain.whatever  
     host host2.domain.whatever  
     host host3.domain.whatever  
     host host4.domain.whatever  

4. Then, you will type:
     charmrun +p<num_processors> <program> <args>
   To run the program ring on the first <num_processors> hosts in your 
   nodelist file.  

   For example, "charmrun +p2 ring 5 5 5 1 2" will run the "ring" executable 
on the first two hosts listed in your nodelist file, to simulate a Blue Gene
machine of 5x5x5 Nodes, each having 1 communiction thread and 2 worker threads.

Note: charmrun uses "rsh" by default to connect to hosts.  If your machine 
      only accepts "ssh", you must set the CONV_RSH environment variable to 
      "ssh".
        setenv CONV_RSH ssh
      Also, you must be able to do "rsh host" or "ssh host" from the command
      line without typing a password, so set your .rhosts or whatever you 
      need to do to make this possible.
    
   To test run the program without charmrun on your local machine, type command directly, programs will run in a special standalone mode:
     <program> <args>