AppleSeed Development Page
Welcome! This page is for those who want to write their own parallel programs that run on multiple Macintoshes. With the version 1.3 or later of Pooch you can mix parallel computing inside multiprocessor Macs with parallel computing across Macs. Much of this information can also be found in the Pooch Software Development Kit.

Running in parallel on one dual processor Macintosh can also be done using a different technique: see our multiprocessing page. You may combine these techniques to run multiple dual processor Macintoshes.

What software you need to write your own Parallel Programs:

On Carbon OS 9 & OS X:
For Fortran: Absoft v7.0 Fortran 77 compiler For C: Absoft v7.0 or Metrowerks ANSI C compiler 
MacMPI_X.f  a Carbonized Fortran subset of MPI  (4/10/01) MacMPI_X.c  a Carbonized C subset of MPI  (4/10/01)
mpif.h, include file for MacMPI_X.f mpi.h, include file for MacMPI_X.c

Topics on this Page:
(Click a link to jump down the page to that section)

What is MPI?
What is MacMPI?
Using MacMPI with:
KKKKThe Absoft Pro Fortran v7.0 compiler on Mac OS 9
KKKKThe Metrowerks CodeWarrior Pro compiler for OS 9 and OS X
Troubleshooting on Mac OS 9 or later
Monitor Window
Debugging MPI Programs
Parallel Fractal Demo GPL Source

What is MPI?

MPI is an industry standard Applications Programming Interface (API), described in a number of textbooks, for sending and receiving messages between nodes of a parallel computer. If you are new to MPI, we recommend Using MPI by William Gropp, Ewing Lusk, and Anthony Skjellum [MIT Press, 1999]. There are also a number of online tutorials available for learning MPI such as at Argonne National Laboratory and Cornell University. If you're new to parallel processing, we have made available a tutorial, How to Write (Nearly) Portable Fortran Programs for Parallel Computers.

What is MacMPI?

MacMPI is a subset of MPI, which contains the collective subroutines most commonly used by university students and researchers. The main restriction of MacMPI is that messages are not buffered, which means that messages from a particular node must be received in the order sent, and probing for messages is not supported.  For regular problems, most programmers naturally send and receive messages in order.  The few times when this does not happen, it is usually unintentional and easily fixed.  Not buffering messages can also give better performance.   MacMPI_X is the Carbonized version of MacMPI; it will run on OS 9 and X.

If you don’t have an MPI program yourself, you can first try one of our sample codes:
Text Iconknock.f, a simple MPI Fortran program for beginners
Text Iconknock.c, a simple MPI C program for beginners
Text Iconpingpong.f, a Fortran test program for measuring communication speeds 
Text Iconpingpong.c, a C test program for measuring communication speeds 

Details on how to create an executable depend on the version of the compiler being used.

Using MacMPI with:

The Absoft Pro Fortran v7.0 compiler on Mac OS 9
On OS 9, this Absoft compiler creates carbon applications by default, therefore we recommend using MacMPI_X.f, which is Carbon-compliant.

To compile and run your own Fortran source code, two files are needed, a communications library, MacMPI_X.f, and the include file mpif.h. Creating an executable with the Absoft compiler is straightforward. First make sure the include file mpif.h is present, then compile the appropriate MPI library with the f77 compiler:

f77 -O -c MacMPI_X.f
If test.f is the main program, one links with MacMPI_X.f as follows depending on the language of test.f:
f77 -O test.f MacMPI_X.f.o
f90 -O test.f MacMPI_X.f.o

      The Metrowerks CodeWarrior Pro compiler for OS 9 and OS X

With CW, you have two major options, both using MacMPI_X.c: using the Standard C Console window or creating a Macintosh application.

Standard Console C

If your C source code is standard ANSI C (e.g., this code is multiplatform and uses ANSI C calls like fprintf and scanf), you should start with the Standard C console project stationery and add your source as you normally would.  Choose the Carbon stationery.  Then add the MacMPI_X library to the project. In the Target Settings Panel named "PPC Target", edit the 'SIZE' Flags to use localAndRemoteHLEvents. Also, be sure to set the Preferred Heap Size so that your code will have enough available memory. In addition, your code will need to edit certain run-time console flags. Before your main() code, add #include <SIOUX.h>, and at the top of your main() code add:

This will have the app quit when it falls out of main(), otherwise, the apps will wait for user input before quitting, locking up the remote machines forever.

In addition, if you don't already have one, you may wish to add a call to printf prior to calling MPI_Init(). It appears to be necessary for proper initialization of the app's runtime environment, without which a crash may occur.

Mac OS Toolbox C

If your C source code is a Macintosh C application (your C calls Macintosh Toolbox routines exclusively), then begin with Mac OS Toolbox project stationery as you normally would, and add your source. Choose the Carbon stationery, then add the MacMPI_X library. Since MacMPI_X relies on ANSI C routines, be sure CodeWarrior's SIOUX libraries (for PowerPC, MSL C.PPC.Lib and MSL SIOUX.PPC.Lib) are also loaded in your project. Again, in the Target Settings Panel named "PPC Target", edit the 'SIZE' Flags to use localAndRemoteHLEvents. And, when you write your code, be sure to have your remote apps quit without direct human interaction. It would also be helpful to have your app's event loop respond to Quit AppleEvents, so Pooch can kill them remotely, if necessary.

Also, you may wish to set the monitor flag to 0, which will turn off the MacMPI monitor window. If you find your event loop, your windows, and MacMPI conflicting, this may help.

Obviously, for benchmarking, you should explore the other compiler and optimization settings. But you should note that the highest level of the Global Optimization settings doesn't always produce the fastest code. Experiment.

Troubleshooting on Mac OS 9 or later

To make sure your TCP/IP network is properly set up, you should first test one of our precompiled programs using the Pooch utility. The AltiVec Fractal Carbon demo, which is compiled with MacMPI_X.c, will run on any Power Mac running OS 9 with CarbonLib.  If Pooch does not see the other nodes, it is likely that the network is not working or is unreliable.

We also recommend that you start with only two nodes, then add more later.

Pooch starts the program on each node and waits until it detects that the application is actually running. If it does not detect that the program is running, it will report an error. The program might not be running because the program on some node had a runtime error independent of MPI.  The most common cause of failure is not setting the Preferred Size in Get Info for the application causing it to run out of memory, or making it too large for those nodes which have less memory.

If MPI fails, MacMPI will write an error file called MPIErrs. You should examine these files (one on each machine), to determine the reasons for the failure. We have a separate page describing how to read these error files.  If the computers do not appear to be connecting, you can hit the escape key (or control-c or cmd-.) to abort the connection. If a connection is not made within one minute, it will abort. If a message does not arrive within five minutes, it will abort and report the status of all pending messages to the error file.

If Pooch fails to launch the parallel program, it is also possible to start it up manually. This can sometimes give further information about the reasons for failure. MacMPI requires that the master node have a file called nodelist_ip present in the same directory as the executable. If the parallel job is started manually, this file must be created by the user. (Pooch creates this file automatically.) This is a straight text file.

The first line contains a port number. If the number 5013 is used, then the slave nodes do not need to have a host file, so this is recommended for debugging. (If some other number is used, then the slave nodes need to have a nodelist_ip file which contains only the port number.) The second line contains the name self. Finally the remaining lines consist of a list of IP addresses, one address per line, in dotted decimal form:
The addresses cannot have trailing blanks. A sample nodelist_ip file looks like:
To start the parallel job manually, one has to copy the executable to each node (via AppleShare, or ftp), and start up (by double clicking) each executable. The master must be started last.

If you run into any other difficulties that should be publicized here, please email us.

Monitor Window

All current versions of MacMPI_X have a global parameter called monitor which gives various levels of diagnostic information. If monitor = 1, a small status window appears. In this window, status lights indicate whether the node whose screen is being examined is sending and/or receiving messages from any other node. Since messages normally are sent very fast, these lights blink rapidly. The status window also shows a histogram of the size of messages being sent or received.

Two additional dials are also shown in the status window. One of these shows the percent of time spent in communication. The second dials is a speedometer which shows the average and instantaneous speeds achieved during communication. These dials are only approximate. The speedometer indicating communication speed is a useful indicator of network problems if it suddenly starts to run slowly. Finally, if monitor = 2, a debug log of every message sent and received is written to the error file.

For maximum performance, monitor = 0 will shut off this window.

Debugging MPI Programs

The monitor = 2 setting in MacMPI_X is intended to help programmers find causes of MPI errors in their programs.  When this variable is set and MacMPI_X is recompiled, a log of every message sent and received by MPI is written to an error file on each node.  By comparing the error files, one can usually determine the entire state of the messaging system when a failure occurs.  A subroutine (called SET_MON in Fortran and Set_Mon in C) is available to set the monitor variable.  One can also use this subroutine to log only sections of code.  Since a lot of data is generated, we also have an additional subroutine (called LOGNAME in Fortran, Logname in C), which will embed a string into the error files to help the programmer track log entries in the program.  For example, call LOGNAME('calling fft') in Fortran will embed the string "calling fft" into the error files at that point in the log.  We have a separate page describing further details how to read and interpret these error files.

A common problem when debugging MPI programs is deadlocked code.  MacMPI_X will timeout if no data arrives for a posted receive for 5 minutes or if a posted send cannot transmit data for 5 minutes.  When MacMPI_X times out, the current status of all the messages is recorded in each of the error files, regardless of the value of the monitor variable.  The information here is very useful in figuring out the causes of deadlocks. The timeout value (in milliseconds) is set in the local variable mstime in the subroutine MPI_TEST (or MPI_Test).  When debugging, it is useful to reduce this value to about 30000 (30 seconds).

Parallel Fractal Demo GPL Source

For those who wish to work with existing parallel Macintosh application code, we have provided two versions of the source for the Parallel Fractal Demo under the GNU General Public License:

For additional technical details, see the AppleSeed Technical Report.

AppleSeed OS X Development Web Page | AppleSeed Multiprocessing Web Page | Back to AppleSeed

Last Updated: May 19, 2003