:orphan: # PetscOptionsBegin Begins a set of queries on the options database that are related and should be displayed on the same window of a GUI that allows the user to set the options interactively. Often one should use `PetscObjectOptionsBegin()` rather than this call. ## Synopsis ``` #include PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[]) ``` Collective ## Input Parameters - ***comm -*** communicator that shares GUI - ***prefix -*** options prefix for all options displayed on window (optional) - ***title -*** short descriptive text, for example "Krylov Solver Options" - ***mansec -*** section of manual pages for options, for example `KSP` (optional) ## Notes This is a macro that handles its own error checking, it does not return an error code. The set of queries needs to be ended by a call to `PetscOptionsEnd()`. One can add subheadings with `PetscOptionsHeadBegin()`. ## Developer Notes `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1. Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1. - ***-1 -*** `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc. - ***0 -*** The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options database updated with user changes; `PetscOptionsGetInt()` etc. are also called. - ***1 -*** `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and default values are printed if -help was given. When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1) and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never currently set. ## See Also `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()` `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`, `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()` ## Level intermediate ## Location include/petscoptions.h ## Examples src/dm/dt/dualspace/impls/lagrange/tutorials/ex1.c
src/dm/dt/dualspace/impls/lagrange/tutorials/ex2.c
src/dm/field/tutorials/ex1.c
src/dm/impls/forest/tutorials/ex1.c
src/dm/impls/plex/tutorials/ex10.c
src/dm/impls/plex/tutorials/ex11.c
src/dm/impls/plex/tutorials/ex13.c
src/dm/impls/plex/tutorials/ex5.c
src/dm/impls/plex/tutorials/ex6.c
src/dm/impls/plex/tutorials/ex8.c
src/dm/impls/plex/tutorials/ex9.c
--- [Edit on GitLab](https://gitlab.com/petsc/petsc/-/edit/release/include/petscoptions.h) [Index of all Sys routines](index.md) [Table of Contents for all manual pages](/manualpages/index.md) [Index of all manual pages](/manualpages/singleindex.md)