ROOMY QUICK START GUIDE

STEP 1: Install and Configure MPICH2

 Roomy uses MPICH2 for interprocess communications. You will find source and
 documentation for MPICH2 at

    http://www.mcs.anl.gov/research/projects/mpich2/

 If you are using your own machine, simply follow the MPICH2 installation guide.

 If you are using one of the Linux machines in the CCIS computer lab (e.g.
 pacman, galaga, bomberman), MPICH2 has already been installed at

    /net/course/csu685/.www/roomy/mpich2-install

 You can then follow the MPICH2 installation guide from step 8 of the quick
 start guide, where you will set your path and test various MPI commands.

STEP 2: Install Roomy

 The Roomy source can be found at

    /net/course/csu685/.www/roomy/roomy.tgz

 or through the course web site.

 1. Unpack the tar file

        tar xvf roomy.tgz

 2. If you installed your own copy of MPICH2, you will need to modify the makefile
    at roomy/src/Makefile. Modify the value of MPIDIR to point to your MPICH2
    installation directory.

 3. Compile the Roomy library

        cd roomy
        make

    You should then see the Roomy library at lib/libroomy.a

STEP 3: Running an Example Roomy Program

 Now, we will run an example program: a breadth first search for the pancake
 sorting problem. For now, we will only cover starting Roomy on a single
 machine.

 1. Go to the directory with the test program

        cd src/tests

 2. Compile the example pancake program

        make

 3. Roomy requires two files describing certain user supplied parameters.

    The first is a file listing the set of machines to run on. Modify the
    "machines" file in the tests directory to list the machine you are
    running on.

    The second is the "params.in" file. This file must be present in the
    same directory that you start the Roomy program from. Edit this file
    to suit your preferences. You must at least supply the following two
    parameters

        MACHINE_FILE   - an absolute path to the "machines" file described above.
        DISK_DATA_PATH - an absolute path to the directory where Roomy will
                         store all disk-based data.

    Note that the DISK_DATA_PATH must exist before running the Roomy program.
    If you are running on one of the CCIS Linux lab machines, it is recommended
    you use /tmp/<yourname>/.
 
 4. Start MPI

        mpdboot -n 1 -f machines
 
    Make sure it worked,

        mpdtrace

    should produce the list of machines MPI started on (in this case, just the
    local host).
 
 5. Execute program

       mpiexec -n 1 <full path to tests directory>/pancake.out 

    You should then see output similar to

        Thu Jan 15 18:38:45 2009: BEGINNING 11 PANCAKE BFS
        Thu Jan 15 18:38:45 2009: Initial RoomyBitsArray constructued
        Thu Jan 15 18:38:46 2009: Level 0 done: 1 elements
        Thu Jan 15 18:39:00 2009: Level 1 done: 10 elements
        Thu Jan 15 18:39:14 2009: Level 2 done: 90 elements