petsc-master 2016-02-10
Report Typos and Errors


Initializes the PETSc database and MPI. PetscInitialize() calls MPI_Init() if that has yet to be called, so this routine should always be called near the beginning of your program -- usually the very first line!


#include "petscsys.h"   
PetscErrorCode  PetscInitialize(int *argc,char ***args,const char file[],const char help[])
Collective on MPI_COMM_WORLD or PETSC_COMM_WORLD if it has been set

Input Parameters

argc - count of number of command line arguments
args - the command line arguments
file - [optional] PETSc database file, also checks ~username/.petscrc and .petscrc use NULL to not check for code specific file. Use -skip_petscrc in the code specific file to skip the .petscrc files
help - [optional] Help message to print, use NULL for no message

If you wish PETSc code to run ONLY on a subcommunicator of MPI_COMM_WORLD, create that communicator first and assign it to PETSC_COMM_WORLD BEFORE calling PetscInitialize(). Thus if you are running a four process job and two processes will run PETSc and have PetscInitialize() and PetscFinalize() and two process will not, then do this. If ALL processes in the job are using PetscInitialize() and PetscFinalize() then you don't need to do this, even if different subcommunicators of the job are doing different things with PETSc.

Options Database Keys

-start_in_debugger [noxterm,dbx,xdb,gdb,...] - Starts program in debugger
-on_error_attach_debugger [noxterm,dbx,xdb,gdb,...] - Starts debugger when error detected
-on_error_emacs <machinename> causes emacsclient to jump to error file- . -on_error_abort calls abort() when error detected (no traceback)
-on_error_mpiabort calls MPI_abort() when error detected- . -error_output_stderr prints error messages to stderr instead of the default stdout
-error_output_none does not print the error messages (but handles errors in the same way as if this was not called)- . -debugger_nodes [node1,node2,...] - Indicates nodes to start in debugger
-debugger_pause [sleeptime] (in seconds) - Pauses debugger
-stop_for_debugger - Print message on how to attach debugger manually to process and wait (-debugger_pause) seconds for attachment
-malloc - Indicates use of PETSc error-checking malloc (on by default for debug version of libraries)
-malloc no - Indicates not to use error-checking malloc
-malloc_debug - check for memory corruption at EVERY malloc or free
-malloc_dump - prints a list of all unfreed memory at the end of the run
-malloc_test - like -malloc_dump -malloc_debug, but only active for debugging builds
-fp_trap - Stops on floating point exceptions (Note that on the IBM RS6000 this slows code by at least a factor of 10.)
-no_signal_handler - Indicates not to trap error signals
-shared_tmp - indicates /tmp directory is shared by all processors
-not_shared_tmp - each processor has own /tmp
-tmp - alternative name of /tmp directory
-get_total_flops - returns total flops done by all processors
-memory_view - Print memory usage at end of run

Options Database Keys for Profiling

See Users-Manual: Chapter 13 Profiling for details.
-info <optional filename> - Prints verbose information to the screen
-info_exclude <null,vec,mat,pc,ksp,snes,ts> - Excludes some of the verbose messages
-log_sync - Log the synchronization in scatters, inner products and norms
-log_trace [filename] - Print traces of all PETSc calls to the screen (useful to determine where a program hangs without running in the debugger). See PetscLogTraceBegin().
-log_view [:filename:format] - Prints summary of flop and timing information to screen or file, see PetscLogView().
-log_summary [filename] - (Deprecated, use -log_view) Prints summary of flop and timing information to screen. If the filename is specified the summary is written to the file. See PetscLogView().
-log_exclude: <vec,mat,pc.ksp,snes> - excludes subset of object classes from logging
-log_all [filename] - Logs extensive profiling information See PetscLogDump().
-log [filename] - Logs basic profiline information See PetscLogDump().
-log_mpe [filename] - Creates a logfile viewable by the utility Jumpshot (in MPICH distribution)

Only one of -log_trace, -log_view, -log_summary, -log_all, -log, or -log_mpe may be used at a time

Options Database Keys for SAWs

-saws_port <portnumber> - port number to publish SAWs data, default is 8080
-saws_port_auto_select - have SAWs select a new unique port number where it publishes the data, the URL is printed to the screen this is useful when you are running many jobs that utilize SAWs at the same time
-saws_log <filename> - save a log of all SAWs communication
-saws_https <certificate file> - have SAWs use HTTPS instead of HTTP
-saws_root <directory> - allow SAWs to have access to the given directory to search for requested resources and files

Environmental Variables

PETSC_TMP - alternative tmp directory
PETSC_SHARED_TMP - tmp is shared by all processes
PETSC_NOT_SHARED_TMP - each process has its own private tmp
PETSC_VIEWER_SOCKET_PORT - socket number to use for socket viewer
PETSC_VIEWER_SOCKET_MACHINE - machine to use for socket viewer to connect to


If for some reason you must call MPI_Init() separately, call it before PetscInitialize().

Fortran Version

In Fortran this routine has the format
      call PetscInitialize(file,ierr)

ierr - error return code
file - [optional] PETSc database file, also checks ~username/.petscrc and .petscrc use PETSC_NULL_CHARACTER to not check for code specific file. Use -skip_petscrc in the code specific file to skip the .petscrc files

Important Fortran Note

In Fortran, you MUST use PETSC_NULL_CHARACTER to indicate a null character string; you CANNOT just use NULL as in the C version. See Users-Manual: Chapter 12 PETSc for Fortran Users for details.

If your main program is C but you call Fortran code that also uses PETSc you need to call PetscInitializeFortran() soon after calling PetscInitialize().

See Also

PetscFinalize(), PetscInitializeFortran(), PetscGetArgs(), PetscInitializeNoArguments()

Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages