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(). 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#
- -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
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_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 ranks 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) (deprecated, use -malloc_debug)
- -malloc no
Indicates not to use error-checking malloc (deprecated, use -malloc_debug no)
- -malloc_debug
check for memory corruption at EVERY malloc or free, see PetscMallocSetDebug()
- -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, ignored in optimized build. May want to set in PETSC_OPTIONS environmental variable
- -malloc_view
show a list of all allocated memory during PetscFinalize()
- -malloc_view_threshold
only list memory allocations of size greater than t with -malloc_view
- -malloc_requested_size
malloc logging will record the requested size rather than 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 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 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]
Prints summary of flop and timing information to screen or file, see PetscLogView().
- -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_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)
- -viewfromoptions on,off
Enable or disable XXXSetFromOptions() calls, for applications with many small solves turn this off
- -check_pointer_intensity 0,1,2
if pointers are checked for validity (debug version only), using 0 will result in faster code
Only one of -log_trace, -log_view, -log_all, -log, or -log_mpe may be used at a time
Options Database Keys for SAWs#
- -saws_port
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
save a log of all SAWs communication
- -saws_https
have SAWs use HTTPS instead of HTTP
- -saws_root
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_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) 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
Notes#
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 ~/.petscrc, .petscrc and petscrc. Use PETSC_NULL_CHARACTER to not check for code specific file. Use -skip_petscrc in the code specific file (or command line) to skip ~/.petscrc, .petscrc and 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: ch_fortran 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(), PetscLogGpuTime()
Level#
beginner
Location#
Examples#
src/sys/classes/viewer/tutorials/ex1.c.html
src/sys/classes/viewer/tutorials/ex1f90.F90.html
src/sys/classes/viewer/tutorials/ex2.c.html
src/sys/classes/random/tutorials/ex1.c.html
src/sys/classes/random/tutorials/ex2.c.html
src/sys/tutorials/ex16.c.html
src/sys/tutorials/ex16f.F90.html
src/sys/tutorials/ex17.c.html
src/sys/tutorials/ex17f.F90.html
src/sys/tutorials/ex19.c.html
src/sys/tutorials/ex1.c.html
Index of all Sys routines
Table of Contents for all manual pages
Index of all manual pages