2.3. Writing PETSc Programs

Up: Contents Next: Simple PETSc Examples Previous: Running PETSc Programs

Most PETSc programs begin with a call to

   ierr = PetscInitialize(int *argc,char ***argv,char *file_name,char *help_message); 
which initializes PETSc and MPI. The arguments argc and argv are the command line arguments delivered in all C and C++ programs. The argument file_name optionally indicates an alternative name for the PETSc options file, .petscrc, which resides by default in the user's home directory. Section Runtime Options provides details regarding this file and the PETSc options database, which can be used for runtime customization. The final argument, help_message, is an optional character string that will be printed if the program is run with the -help option. In Fortran the initialization command has the form
   call PetscInitialize(character file_name,integer ierr) 
PetscInitialize() automatically calls MPI_Init() if MPI has not been not previously initialized. In certain circumstances in which MPI needs to be initialized directly (or is initialized by some other library), the user should first call MPI_Init() (or have the other library do it), and then call PetscInitialize(). By default, PetscInitialize() sets the PETSc ``world'' communicator, given by PETSC_COMM_WORLD, to MPI_COMM_WORLD.

For those not familar with MPI, a communicator is a way of indicating a collection of processors that will be involved together in a calculation or communication. Communicators have the variable type MPI_Comm. In most cases users can employ the communicator PETSC_COMM_WORLD to indicate all processes in a given run and PETSC_COMM_SELF to indicate a single process. MPI provides routines for generating new communicators consisting of subsets of processors, though most users rarely need to use these. The book Using MPI, by Lusk, Gropp, and Skjellum [10] provides an excellent introduction to the concepts in MPI. Note that PETSc users need not program much message passing directly with MPI, but they must be familar with the basic concepts of message passing and distributed memory computing.

Users who wish to employ PETSc routines on only a subset of processors within a larger parallel job, or who wish to use a ``master'' process to coordinate the work of ``slave'' PETSc processes, should specify an alternative communicator for PETSC_COMM_WORLD by calling

   ierr = PetscSetCommWorld(MPI_Comm comm); 
before calling PetscInitialize(), but, obviously, after calling MPI_Init(). PetscSetCommWorld() can be called at most once per process. Most users will never need to use the routine PetscSetCommWorld().

As illustrated by the PetscInitialize() statements above, PETSc 2.0 routines return an integer indicating whether an error has occurred during the call. The error code is set to be nonzero if an error has been detected; otherwise, it is zero. For the C/C++ interface, the error variable is the routine's return value, while for the Fortran version, each PETSc routine has as its final argument an integer error variable. Error tracebacks are discussed in the following section.

All PETSc programs should call PetscFinalize() as their final (or nearly final) statement, as given below in the C/C++ and Fortran formats, respectively:

   ierr = PetscFinalize(); 
   call PetscFinalize(ierr) 
This routine handles options to be called at the conclusion of the program, and calls MPI_Finalize() if PetscInitialize() began MPI. If MPI was initiated externally from PETSc (by either the user or another software package), the user is responsible for calling MPI_Finalize().


Up: Contents Next: Simple PETSc Examples Previous: Running PETSc Programs