ncsa

User Information Home
Compute Resources
Software
Data
Security
Allocations
Consulting
Training
Strategic Applications Program

Getting Started

1. Terms
2. Sample Programs
3. Include Files and Function Calls
   1. Include Files
   2. Function Calls
4. Running "hello"

---

The MPI library provides a rich collection of communication routines. You can, however, start writing MPI code using only a few of those routines.

Before you start writing, you should understand two basic terms that are involved in almost all MPI function calls: communicator and rank.

1.0 Terms

A communicator is the domain of communications -- a group of processors within which communications may take place. MPI function calls take this as an argument to define which processors will be involved in an operation.

A rank is a unique integer that identifes the processor within a given communicator domain. If a processor is defined in more then one communicator, it has a unique, different rank in each communicator.

2. Sample Programs

Below are sample "hello" MPI programs shown in both FORTRAN and C languages.

 
program hello
include "mpif.h"

integer rank, size, ierr

call MPI_INIT(ierr)
call MPI_COMM_SIZE(MPI_COMM_WORLD, size, ierr)
call MPI_COMM_RANK(MPI_COMM_WORLD, rank, ierr)

print *, "Hello world! I'm ", rank+1," of ", size

call MPI_FINALIZE(ierr)

stop
end

This is the equivalent C version:

 
#include <stdio.h>
#include <mpi.h>

main(int *argc, char** argv)
{
   int size, rank;

   MPI_Init(argc, &argv);
   MPI_Comm_size(MPI_COMM_WORLD, &size);
   MPI_Comm_rank(MPI_COMM_WORLD, &rank);

   printf("Hello world! I'm  %d  of  %d\n", rank+1, size);

   MPI_Finalize();
}

3.0 Include Files and Function Calls

The different pieces and function calls in the program are important to understand.

3.1 Include Files

Both mpif.h and mpi.h are MPI include files that contain declarations and type definitions for fields used in the MPI function calls. One of these files must be included in every MPI program. Use the appropriate include file depending on your language:

FORTRAN	mpif.h
C	mpi.h

3.2 Function Calls

1. MPI_Init initializes the MPI library so your program can call MPI routines. Every MPI program must include this call at the beginning. You can not call any MPI routine before executing the call to MPI_Init.

   In FORTRAN, the call to MPI_Init takes one argument that is the return value of the call. If ierr is zero, then the call was successful; otherwise an error was encountered. In C, the MPI_Init takes no arguments, but the return value of the function is the error value.

   In general, the FORTRAN syntax of MPI function calls has an extra argument at the end that reports the error value of the function call. The C syntax does not have this field because the return value of the function will report the error value (if saved in a variable).

2. MPI_Finalize is used at the end of the program terminates and "cleans up" MPI routines. Every MPI program must have this call at the end. You can not call any MPI function after this call is executed.

3. When executed, MPI_Comm_size returns the number of processors in the communicator. The first argument to this function specifies the communicator. MPI_COMM_WORLD is the domain of all processors. This is an MPI constant defined in the include files (mpif.h or mpi.h). The second argument to the function is the number of processors in the communicator.

   This function may be called to find out how many processors are availabe under the given communicator.

4. MPI_Comm_rank is called to find the rank of the calling processor within the group of procesors. It takes a communicator name as its first argument, and returns the rank in the second argument. For example, if the number of processors is N, the rank returned by the calling processor in the MPI_COMM_WORLD group would be an integer number between 0 and N-1.

4.0 Running "hello"

If you compile and run one of the programs in Sample Programs, you get an output that looks like this:

 
 Hello world! I'm            3 of            4
 Hello world! I'm            2 of            4
 Hello world! I'm            1 of            4
 Hello world! I'm            4 of            4

Notice that the order of printing is random and can be different each time you run the program.