Skip to main content
`Ctrl`+`K`

# 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 <petscoptions.h>
    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.

## Fortran Note

Returns ierr error code as the final argument per PETSc Fortran API

## See Also

`PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`

## Level

intermediate

## Location

include/petscoptions.h

## Examples

src/sys/tutorials/ex9f.F90

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