Skip to main content
`Ctrl`+`K`

# PetscInitialize

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!

## Synopsis

    #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, append “:yaml” to filename to specify YAML options format. Use `NULL` or empty string to not check for code specific file. Also checks `~/.petscrc`, `.petscrc` and `petscrc`. Use `-skip_petscrc` in the code specific file (or command line) to skip `~/.petscrc`, `.petscrc` and `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()`. 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

- -help [intro] - prints help method for each option; if `intro` is given the program stops after printing the introductory help message

- -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 if an error is detected

- -on_error_abort - calls `abort()` when error detected (no traceback)

- -on_error_mpiabort - calls `MPI_abort()` when error detected

- -error_output_stdout - prints PETSc error messages to `stdout` instead of the default `stderr`

- -error_output_none - does not print the error messages (but handles errors in the same way as if this was not called)

- -debugger_ranks [rank1,rank2,…] - Indicates MPI ranks to start in debugger

- -debugger_pause [sleeptime] (in seconds) - Pauses debugger, use if it takes a long time for the debugger to start up on your system

- -stop_for_debugger - Print message on how to attach debugger manually to process and wait (`-debugger_pause`) seconds for attachment

- -malloc_dump - prints a list of all unfreed memory at the end of the run

- -malloc_test - like `-malloc_dump` `-malloc_debug`, only active for debugging build, ignored in optimized build. Often set in `PETSC_OPTIONS` environmental variable

- -malloc_view - show a list of all allocated memory during `PetscFinalize()`

- -malloc_view_threshold <t> - only list memory allocations of size greater than t with `-malloc_view`

- -malloc_requested_size - malloc logging will record the requested size rather than (possibly large) size after alignment

- -fp_trap - Stops on floating point exceptions

- -no_signal_handler - Indicates not to trap error signals

- -shared_tmp - indicates `/tmp` directory is known to be shared by all processors

- -not_shared_tmp - indicates each processor has own `/tmp`

- -tmp - alternative directory to use instead of `/tmp`

- -mpiuni- allow-multiprocess-launch - allow `mpiexec` to launch multiple independent MPI-Uni jobs, otherwise a sanity check error is invoked to prevent misuse of MPI-Uni

## Options Database Keys for Option Database

- -skip_petscrc - skip the default option files `~/.petscrc`, `.petscrc`, `petscrc`

- -options_monitor - monitor all set options to standard output for the whole program run

- -options_monitor_cancel - cancel options monitoring hard-wired using `PetscOptionsMonitorSet()`

Options -options_monitor_{all,cancel} are position-independent and apply to all options set since the PETSc start. They can be used also in option files.

See `PetscOptionsMonitorSet()` to do monitoring programmatically.

## Options Database Keys for Profiling

See Users-Manual: ch_profiling for details.

- -info [filename][:[~]<list,of,classnames>[:[~]self]] - Prints verbose information. See `PetscInfo()`.

- -log_sync - Enable barrier synchronization for all events. This option is useful to debug imbalance within each event, however it slows things down and gives a distorted view of the overall runtime.

- -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][,[:filename:format]…] - Prints summary of flop and timing information to screen or file, see `PetscLogView()` (up to 4 viewers)

- -log_view_memory - Includes in the summary from -log_view the memory used in each event, see `PetscLogView()`.

- -log_view_gpu_time - Includes in the summary from -log_view the time used in each GPU kernel, see `PetscLogView().

- -log_exclude: <vec,mat,pc,ksp,snes> - excludes subset of object classes from logging

- -log [filename] - Logs profiling information in a dump file, see `PetscLogDump()`.

- -log_all [filename] - Same as `-log`.

- -log_mpe [filename] - Creates a logfile viewable by the utility Jumpshot (in MPICH distribution)

- -log_perfstubs - Starts a log handler with the perfstubs interface (which is used by TAU)

- -log_nvtx - Starts an nvtx log handler for use with Nsight

- -viewfromoptions on,off - Enable or disable `XXXSetFromOptions()` calls, for applications with many small solves turn this off

- -get_total_flops - Returns total flops done by all processors

- -memory_view - Print memory usage at end of run

- -check_pointer_intensity 0,1,2 - if pointers are checked for validity (debug version only), using 0 will result in faster code

## 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 directory to use instead of `/tmp`

- `PETSC_SHARED_TMP` - `/tmp` is shared by all processes

- `PETSC_NOT_SHARED_TMP` - each process has its own private `/tmp`

- `PETSC_OPTIONS` - a string containing additional options for petsc in the form of command line “-key value” pairs

- `PETSC_OPTIONS_YAML` - (requires configuring PETSc to use libyaml with `--download-yaml`) a string containing additional options for PETSc in the form of a YAML document

- `PETSC_VIEWER_SOCKET_PORT` - socket number to use for socket viewer

- `PETSC_VIEWER_SOCKET_MACHINE` - machine to use for socket viewer to connect to

## Note

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

## Fortran Notes

In Fortran this routine can be called with

           call PetscInitialize(ierr)
           call PetscInitialize(file,ierr) or
           call PetscInitialize(file,help,ierr)

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

## Options Database Key for Developers

- -checkfunctionlist - automatically checks that function lists associated with objects are correctly cleaned up. Produces messages of the form: “function name: MatInodeGetInodeSizes_C” if they are not cleaned up. This flag is always set for the test harness (in framework.py)

## See Also

`PetscFinalize()`, `PetscInitializeFortran()`, `PetscGetArgs()`, `PetscInitializeNoArguments()`, `PetscLogGpuTime()`

## Level

beginner

## Location

src/sys/objects/pinit.c

## Examples

src/dm/dt/dualspace/impls/lagrange/tutorials/ex2.c
src/dm/impls/plex/tutorials/ex10.c
src/dm/impls/plex/tutorials/ex14.c
src/dm/impls/plex/tutorials/ex13.c
src/dm/field/tutorials/ex1.c
src/dm/impls/plex/tutorials/ex1.c
src/dm/impls/forest/tutorials/ex1.c
src/dm/impls/plex/tutorials/ex15.c
src/dm/dt/dualspace/impls/lagrange/tutorials/ex1.c
src/dm/impls/plex/tutorials/ex11.c

## Implementations

PetscInitialize_MKL_CPARDISO() in src/mat/impls/aij/mpi/mkl_cpardiso/mkl_cpardiso.c

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