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 OS X: (for Mac OS 9) (for Mac OS 8.6 and earlier)
For Fortran: For C:
Absoft v7.0 - 8.2 Fortran 77 & 95 compiler
NAG v4.2 Fortran 95 compiler
IBM xlf v8.1 (Beta) Fortran 95 compiler
GNU g77 via Fink
Absoft v8.2
Metrowerks ANSI C compiler 
IBM xlc v6.0 (Beta) C/C++/C99 compiler
GNU cc on OS X
MacMPIcf.c and MacMPIf77.c, wrappers bridging Fortran to MacMPI (1/25/04) MacMPI_S.c  a Unix Sockets-based C subset of MPI  (3/7/06)
MacMPI_X.c  a Open Transport-based (Carbon) C subset of MPI  (3/7/06)
mpif.h, Fortran include file for MacMPIcf mpi.h, C include file for both MacMPI's

LnxMPI_S.c  a Unix Sockets-based C subset of MPI without graphics  (3/7/06)

"Universal Binary," for mixed clusters
of Intel- and PowerPC-based Macs:
MacMPI_SUB.c  a Unix Sockets-based C subset of MPI  (5/17/06)
MacMPI_XUB.c  a Open Transport-based (Carbon) C subset of MPI  (3/20/06)



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

What is MPI?
What is MacMPI?
Other MPIs
Sample Code
Using MacMPI with:
KKKKThe Absoft Pro Fortran v7.0 - 8.2 compilers
KKKKThe NAG Fortran v4.2 compiler
KKKKThe IBM xlf v8.1 Fortran compiler
KKKKThe GNU Fortran 77 compiler
KKKKThe Metrowerks CodeWarrior Pro compiler for OS 9 and OS X
KKKKThe GNU cc compiler
Troubleshooting on Mac OS X
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.

In addition, Dauger Research has a discussion on parallelization techniques introducing the issues encountered when writing parallel code and parallelizing existing code. Using actual code, the site expands on these ideas in parallel knock, a tutorial that introduces MPI, and two tutorials on parallelizing single-processor code, parallel adder and parallel Pascal's triangle.

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 currently exists in two versions on OS X. A sockets-based version, called MacMPI_S, runs only on OS X. A Carbonized TCP/IP version, called MacMPI_X, runs on both Mac OS 9 and X.

Other MPIs

Other MPI implementations are available on Mac OS X and their use is described on the Pooch - Compiling MPI page.

Sample Code

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 Iconmpiadder.f, a simple MPI Fortran program that sums numbers
Text Iconmpiadder.c, a simple MPI C program that sums numbers
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. Note that many of these compilers only recognize Unix-style line breaks, so be sure to convert your header files and source code into Unix-style text files (the BBEdit editor and Absoft's unixformat command can do this) from those that use Macintosh-style line breaks.

Using MacMPI with:

The Absoft Pro Fortran compilers v7.0 - 8.2 through the Terminal app
MacMPI_S:

To compile and run your own Fortran source code, four files are needed, a communications library, MacMPI_S.c, its associated include file mpi.h, a wrapper library MacMPIcf.c, and the include file mpif.h. Creating an executable with the Absoft compiler is straightforward. First make sure the include file mpi.h is present, then compile the MPI library and appropriate wrapper with the gcc compiler:

gcc -O -c MacMPI_S.c MacMPIcf.c -I /Developer/Headers/FlatCarbon
You will need to link OS X Carbon libraries in addition to MacMPI_S. If test.f is the main program, make sure the include file mpif.h is present, then link with MacMPI_S, the wrapper file, and Carbon as follows:
f95 -O test.f MacMPI_S.o MacMPIcf.o /System/Library/Frameworks/Carbon.framework/Carbon
The Absoft OS X compiler creates executables which use the default 512kB stack.  If your application needs more than that, you may want to compile with the -s flag or use the ulimit command.

MacMPI_X:

To use MacMPI_X, merely substitute MacMPI_X.c in place of MacMPI_S.c while following the procedure for MacMPI_S above.

In addition, the Absoft Fortran compiler can compile and link with MacMPI_X.f, a Fortran version of MacMPI_X, directly as follows.

f77 -O -c MacMPI_X.f
f95 -O test.f MacMPI_X.o /System/Library/Frameworks/Carbon.framework/Carbon
The NAG Fortran compiler v4.2
MacMPI_S:

To compile and run your own Fortran source code, four files are needed, a communications library, MacMPI_S.c, its associated include file mpi.h, a wrapper library MacMPIf77.c, and the include file mpif.h. First make sure the include file mpi.h is present, then compile the MPI library and appropriate wrapper with the gcc compiler:

gcc -O -c MacMPI_S.c MacMPIf77.c -I /Developer/Headers/FlatCarbon
You will need to link OS X Carbon libraries in addition to MacMPI_S. If test.f is the main program, make sure the include file mpif.h is present, then link with MacMPI_S, the wrapper file, and Carbon as follows:
f95 -O -framework carbon test.f MacMPI_S.o MacMPIf77.o

MacMPI_X:

To use MacMPI_X, merely substitute MacMPI_X.c in place of MacMPI_S.c while following the procedure for MacMPI_S above.

The IBM xlf v8.1 Fortran compiler
MacMPI_S:

To compile and run your own Fortran source code, four files are needed, a communications library, MacMPI_S.c, its associated include file mpi.h, a wrapper library MacMPIf77.c, and the include file mpif.h. First make sure the include file mpi.h is present, then compile the MPI library and appropriate wrapper with the gcc compiler:

gcc -O -c MacMPI_S.c MacMPIf77.c -I /Developer/Headers/FlatCarbon
You will need to link OS X Carbon libraries in addition to MacMPI_S. If test.f is the main program, make sure the include file mpif.h is present, then link with MacMPI_S, the wrapper file, and Carbon as follows:
xlf -O -qextname test.f MacMPI_S.o MacMPIf77.o /System/Library/Frameworks/Carbon.framework/Carbon

MacMPI_X:

To use MacMPI_X, merely substitute MacMPI_X.c in place of MacMPI_S.c while following the procedure for MacMPI_S above.

The GNU Fortran 77 compiler (a. k. a. g77)

MacMPI_S:

The g77 compiler is available via Fink. Fink automatically adjusts and installs many open-source programs available on other Unixes. g77 takes some time to compile and install (many minutes). Be sure to install the OS X Developer Tools, including gcc, before using Fink.

Then download MacMPI_S.c, the C version of the MPI library, the include files mpi.h and mpif.h, and a wrapper code that bridges g77 and MacMPI_S.c, MacMPIg77.c, into the same directory as your Fortran 77 code. Next, create object code versions of MacMPI_S and MacMPIg77 using gcc:

gcc -c MacMPI_S.c MacMPIg77.c -I /Developer/Headers/FlatCarbon
You can then create an executable using your Fortran 77 code and the g77 compiler.

If test.f is the main program, one links with MacMPI_S and Carbon as follows:

g77 test.f MacMPIg77.o MacMPI_S.o /System/Library/Frameworks/Carbon.framework/Carbon
This should create a Mach-O executable that should launch in parallel using Pooch.

MacMPI_X:

To use MacMPI_X, merely substitute MacMPI_X.c in place of MacMPI_S.c while following the procedure for MacMPI_S above.
 


      The Metrowerks CodeWarrior Pro compiler for OS 9 and OS X


With CW, you have six major options: Using the Standard C Console window versus creating a Macintosh application, and using MacMPI_X.c.

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 when using MacMPI_X.c.  Then add the MacMPI library to the project. In the Target Settings Panel named "PPC Target", edit the 'SIZE' Flags to use localAndRemoteHLEvents. This allows the Launch Den Mother to see the parallel application on a remote machine. 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:

SIOUXSettings.asktosaveonclose=0;
SIOUXSettings.autocloseonquit=1;
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 when using MacMPI_X.c. Then add the MacMPI library as well. Since MacMPI 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 status 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.
 

The built-in GNU cc compiler

MacMPI_S:

To compile and run your own C source code, two files are needed, a communications library, MacMPI_S.c, and the include file mpi.h. Creating an executable with the gcc compiler is straightforward. First make sure the include file mpi.h is present.

Also, you will need access to the Carbon header files and the OS X Carbon libraries. If test.c is the main program, one links with MacMPI_S.c and Carbon as follows:

gcc test.c MacMPI_S.c /System/Library/Frameworks/Carbon.framework/Carbon -I /Developer/Headers/FlatCarbon

MacMPI_X:

To use MacMPI_X, merely substitute MacMPI_X.c in place of MacMPI_S.c while following the procedure for MacMPI_S above.
 

Troubleshooting on Mac OS X

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 X or 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. 

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:

12.13.14.15
The addresses cannot have trailing blanks. A sample nodelist_ip file looks like:
5013
self
192.168.1.90
192.168.1.91
192.168.1.92
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 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.

In addition, two dials are shown at the bottom the monitor 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 is intended to help programmers find causes of MPI errors in their programs.  When this variable is set and MacMPI 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 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 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 Development Web Page | AppleSeed Multiprocessing Web Page | Back to AppleSeed

Last Updated: August 21, 2006