Actual source code: petscoptions.h

      1: /*
      2:    Routines to determine options set in the options database.
      3: */
      4: #pragma once

      6: #include <petscsys.h>
      7: #include <petscviewertypes.h>

      9: /* SUBMANSEC = Sys */

     11: typedef enum {
     12:   PETSC_OPT_CODE,
     13:   PETSC_OPT_COMMAND_LINE,
     14:   PETSC_OPT_FILE,
     15:   PETSC_OPT_ENVIRONMENT,
     16:   NUM_PETSC_OPT_SOURCE
     17: } PetscOptionSource;

     19: #define PETSC_MAX_OPTION_NAME 512
     20: typedef struct _n_PetscOptions *PetscOptions;
     21: PETSC_EXTERN PetscErrorCode     PetscOptionsCreate(PetscOptions *);
     22: PETSC_EXTERN PetscErrorCode     PetscOptionsPush(PetscOptions);
     23: PETSC_EXTERN PetscErrorCode     PetscOptionsPop(void);
     24: PETSC_EXTERN PetscErrorCode     PetscOptionsDestroy(PetscOptions *);
     25: PETSC_EXTERN PetscErrorCode     PetscOptionsCreateDefault(void);
     26: PETSC_EXTERN PetscErrorCode     PetscOptionsDestroyDefault(void);

     28: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
     29: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
     30: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
     31: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool3(PetscOptions, const char[], const char[], PetscBool3 *, PetscBool *);
     32: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
     33: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
     34: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
     35: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
     36: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
     37: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
     38: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);

     40: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
     41: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
     42: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
     43: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
     44: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
     45: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);

     47: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
     48: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
     49: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
     50: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
     51: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);

     53: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
     54: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
     55: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
     56: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
     57: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
     58: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
     59: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);

     61: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
     62: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
     63: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
     64: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
     65: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
     66: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
     67: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, char **);
     68: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
     69: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
     70: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);

     72: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
     73: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
     74: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
     75: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
     76: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);

     78: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscErrorCode (*)(void **));
     79: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);

     81: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
     82: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);

     84: PETSC_EXTERN PetscBool PetscOptionsPublish;

     86: /*
     87:     See manual page for PetscOptionsBegin()

     89:     PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
     90:   options being handled with a PetscOptionsBegin/End()

     92: */
     93: typedef enum {
     94:   OPTION_INT,
     95:   OPTION_BOOL,
     96:   OPTION_REAL,
     97:   OPTION_FLIST,
     98:   OPTION_STRING,
     99:   OPTION_REAL_ARRAY,
    100:   OPTION_SCALAR_ARRAY,
    101:   OPTION_HEAD,
    102:   OPTION_INT_ARRAY,
    103:   OPTION_ELIST,
    104:   OPTION_BOOL_ARRAY,
    105:   OPTION_STRING_ARRAY
    106: } PetscOptionType;

    108: typedef struct _n_PetscOptionItem *PetscOptionItem;
    109: struct _n_PetscOptionItem {
    110:   char              *option;
    111:   char              *text;
    112:   void              *data;  /* used to hold the default value and then any value it is changed to by GUI */
    113:   PetscFunctionList  flist; /* used for available values for PetscOptionsList() */
    114:   const char *const *list;  /* used for available values for PetscOptionsEList() */
    115:   char               nlist; /* number of entries in list */
    116:   char              *man;
    117:   PetscInt           arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
    118:   PetscBool          set;         /* the user has changed this value in the GUI */
    119:   PetscOptionType    type;
    120:   PetscOptionItem    next;
    121:   char              *pman;
    122:   void              *edata;
    123: };

    125: typedef struct _p_PetscOptionItems {
    126:   PetscInt        count;
    127:   PetscOptionItem next;
    128:   char           *prefix, *pprefix;
    129:   char           *title;
    130:   MPI_Comm        comm;
    131:   PetscBool       printhelp, changedmethod, alreadyprinted;
    132:   PetscObject     object;
    133:   PetscOptions    options;
    134: } PetscOptionItems;

    136: #if defined(PETSC_CLANG_STATIC_ANALYZER)
    137: extern PetscOptionItems *PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
    138: PetscErrorCode           PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
    139: PetscErrorCode           PetscObjectOptionsBegin(PetscObject);
    140: PetscErrorCode           PetscOptionsEnd(void);
    141: #else
    142:   /*MC
    143:     PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
    144:      displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
    145:      use `PetscObjectOptionsBegin()` rather than this call.

    147:     Synopsis:
    148: #include <petscoptions.h>
    149:     PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])

    151:     Collective

    153:     Input Parameters:
    154: +   comm - communicator that shares GUI
    155: .   prefix - options prefix for all options displayed on window (optional)
    156: .   title - short descriptive text, for example "Krylov Solver Options"
    157: -   mansec - section of manual pages for options, for example `KSP` (optional)

    159:     Level: intermediate

    161:     Notes:
    162:     This is a macro that handles its own error checking, it does not return an error code.

    164:     The set of queries needs to be ended by a call to `PetscOptionsEnd()`.

    166:     One can add subheadings with `PetscOptionsHeadBegin()`.

    168:     Developer Notes:
    169:     `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
    170:     loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
    171:      Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
    172: +      \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
    173: .      0   - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
    174:               database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
    175: -      1   - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
    176:               default values are printed if -help was given.
    177:      When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
    178:      and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
    179:      options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
    180:      currently set.

    182:      Fortran Note:
    183:      Returns ierr error code per PETSc Fortran API

    185: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    186:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
    187:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    188:           `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    189:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    190:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    191:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
    192: M*/
    193:   #define PetscOptionsBegin(comm, prefix, mess, sec) \
    194:     do { \
    195:       PetscOptionItems  PetscOptionsObjectBase; \
    196:       PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
    197:       PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
    198:       for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
    199:         PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))

    201:   /*MC
    202:     PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
    203:     displayed on the same window of a GUI that allows the user to set the options interactively.

    205:     Synopsis:
    206: #include <petscoptions.h>
    207:     PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)

    209:     Collective

    211:     Input Parameter:
    212: .   obj - object to set options for

    214:     Level: intermediate

    216:     Notes:
    217:     This is a macro that handles its own error checking, it does not return an error code.

    219:     Needs to be ended by a call the `PetscOptionsEnd()`

    221:     Can add subheadings with `PetscOptionsHeadBegin()`

    223: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    224:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
    225:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    226:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    227:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    228:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    229:           `PetscOptionsFList()`, `PetscOptionsEList()`
    230: M*/
    231:   #define PetscObjectOptionsBegin(obj) \
    232:     do { \
    233:       PetscOptionItems  PetscOptionsObjectBase; \
    234:       PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
    235:       PetscOptionsObject->options          = ((PetscObject)obj)->options; \
    236:       for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
    237:         PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))

    239:   /*MC
    240:     PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
    241:      displayed on the same window of a GUI that allows the user to set the options interactively.

    243:     Synopsis:
    244: #include <petscoptions.h>
    245:      PetscErrorCode PetscOptionsEnd(void)

    247:     Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`

    249:     Level: intermediate

    251:     Notes:
    252:     Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`

    254:     This is a macro that handles its own error checking, it does not return an error code.

    256:     Fortran Note:
    257:     Returns ierr error code per PETSc Fortran API

    259: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    260:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
    261:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    262:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
    263:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    264:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    265:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
    266: M*/
    267:   #define PetscOptionsEnd() \
    268:     PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
    269:     } \
    270:     } \
    271:     while (0)
    272: #endif /* PETSC_CLANG_STATIC_ANALYZER */

    274: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *, MPI_Comm, const char[], const char[], const char[]);
    275: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems *);
    276: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *);
    277: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems *, const char[]);

    279: #if defined(PETSC_CLANG_STATIC_ANALYZER)
    280: template <typename... T>
    281: void PetscOptionsHeadBegin(T...);
    282: void PetscOptionsHeadEnd(void);
    283: template <typename... T>
    284: PetscErrorCode PetscOptionsEnum(T...);
    285: template <typename... T>
    286: PetscErrorCode PetscOptionsInt(T...);
    287: template <typename... T>
    288: PetscErrorCode PetscOptionsBoundedInt(T...);
    289: template <typename... T>
    290: PetscErrorCode PetscOptionsRangeInt(T...);
    291: template <typename... T>
    292: PetscErrorCode PetscOptionsReal(T...);
    293: template <typename... T>
    294: PetscErrorCode PetscOptionsScalar(T...);
    295: template <typename... T>
    296: PetscErrorCode PetscOptionsName(T...);
    297: template <typename... T>
    298: PetscErrorCode PetscOptionsString(T...);
    299: template <typename... T>
    300: PetscErrorCode PetscOptionsBool(T...);
    301: template <typename... T>
    302: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
    303: template <typename... T>
    304: PetscErrorCode PetscOptionsBoolGroup(T...);
    305: template <typename... T>
    306: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
    307: template <typename... T>
    308: PetscErrorCode PetscOptionsFList(T...);
    309: template <typename... T>
    310: PetscErrorCode PetscOptionsEList(T...);
    311: template <typename... T>
    312: PetscErrorCode PetscOptionsRealArray(T...);
    313: template <typename... T>
    314: PetscErrorCode PetscOptionsScalarArray(T...);
    315: template <typename... T>
    316: PetscErrorCode PetscOptionsIntArray(T...);
    317: template <typename... T>
    318: PetscErrorCode PetscOptionsStringArray(T...);
    319: template <typename... T>
    320: PetscErrorCode PetscOptionsBoolArray(T...);
    321: template <typename... T>
    322: PetscErrorCode PetscOptionsEnumArray(T...);
    323: template <typename... T>
    324: PetscErrorCode PetscOptionsDeprecated(T...);
    325: template <typename... T>
    326: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
    327: #else
    328:   /*MC
    329:    PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
    330:    in `KSPSetFromOptions_GMRES()`.

    332:    Logically Collective on the communicator passed in `PetscOptionsBegin()`

    334:    Input Parameter:
    335: .  head - the heading text

    337:    Level: developer

    339:    Notes:
    340:    Handles errors directly, hence does not return an error code

    342:    Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument

    344:    Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.

    346: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    347:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    348:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    349:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    350:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    351:           `PetscOptionsFList()`, `PetscOptionsEList()`
    352: M*/
    353:   #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
    354:     do { \
    355:       if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, "  %s\n", head)); \
    356:     } while (0)

    358:   #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)

    360:   /*MC
    361:      PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
    362:      See, for example, `KSPSetFromOptions_GMRES()`.

    364:      Synopsis:
    365: #include <petscoptions.h>
    366:      PetscErrorCode PetscOptionsHeadEnd(void)

    368:      Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`

    370:      Level: intermediate

    372:      Notes:
    373:      Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`

    375:      Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.

    377:      This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
    378:      See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
    379:      from the function.

    381:      This is only for use with the PETSc options GUI

    383: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    384:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    385:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    386:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    387:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    388:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
    389: M*/
    390:   #define PetscOptionsHeadEnd() \
    391:     do { \
    392:       if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
    393:     } while (0)

    395:   #define PetscOptionsTail(...)                                                     PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)

    397: /*MC
    398:   PetscOptionsEnum - Gets the enum value for a particular option in the database.

    400:   Synopsis:
    401: #include <petscoptions.h>
    402:   PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)

    404:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    406:   Input Parameters:
    407: + opt          - option name
    408: . text         - short string that describes the option
    409: . man          - manual page with additional information on option
    410: . list         - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    411: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    412: .vb
    413:                  PetscOptionsEnum(..., obj->value,&object->value,...) or
    414:                  value = defaultvalue
    415:                  PetscOptionsEnum(..., value,&value,&set);
    416:                  if (set) {
    417: .ve

    419:   Output Parameters:
    420: + value - the  value to return
    421: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    423:   Level: beginner

    425:   Notes:
    426:   Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    428:   `list` is usually something like `PCASMTypes` or some other predefined list of enum names

    430:   If the user does not supply the option at all `value` is NOT changed. Thus
    431:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    433:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    435: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    436:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    437:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    438:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    439:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    440:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    441:           `PetscOptionsFList()`, `PetscOptionsEList()`
    442: M*/
    443:   #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set)          PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)

    445: /*MC
    446:   PetscOptionsInt - Gets the integer value for a particular option in the database.

    448:   Synopsis:
    449: #include <petscoptions.h>
    450:   PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)

    452:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    454:   Input Parameters:
    455: + opt          - option name
    456: . text         - short string that describes the option
    457: . man          - manual page with additional information on option
    458: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    459: .vb
    460:                  PetscOptionsInt(..., obj->value, &obj->value, ...) or
    461:                  value = defaultvalue
    462:                  PetscOptionsInt(..., value, &value, &set);
    463:                  if (set) {
    464: .ve

    466:   Output Parameters:
    467: + value - the integer value to return
    468: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    470:   Level: beginner

    472:   Notes:
    473:   If the user does not supply the option at all `value` is NOT changed. Thus
    474:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    476:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    478:   Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    480: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    481:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
    482:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    483:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    484:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    485:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    486:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    487: M*/
    488:   #define PetscOptionsInt(opt, text, man, currentvalue, value, set)                 PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)

    490: /*MC
    491:   PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.

    493:   Synopsis:
    494: #include <petscoptions.h>
    495:   PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)

    497:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    499:   Input Parameters:
    500: + opt          - option name
    501: . text         - short string that describes the option
    502: . man          - manual page with additional information on option
    503: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    504: .vb
    505:                  PetscOptionsInt(..., obj->value, &obj->value, ...) or
    506:                  value = defaultvalue
    507:                  PetscOptionsInt(..., value, &value, &set);
    508:                  if (set) {
    509: .ve

    511:   Output Parameters:
    512: + value - the MPI integer value to return
    513: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    515:   Level: beginner

    517:   Notes:
    518:   If the user does not supply the option at all `value` is NOT changed. Thus
    519:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    521:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    523:   Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    525: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    526:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
    527:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    528:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    529:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    530:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    531:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    532: M*/
    533:   #define PetscOptionsMPIInt(opt, text, man, currentvalue, value, set)              PetscOptionsMPIInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MPI_INT_MIN, PETSC_MPI_INT_MAX)

    535: /*MC
    536:    PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.

    538:    Synopsis:
    539: #include <petscoptions.h>
    540:    PetscErrorCode  PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)

    542:    Logically Collective on the communicator passed in `PetscOptionsBegin()`

    544:    Input Parameters:
    545: +  opt          - option name
    546: .  text         - short string that describes the option
    547: .  man          - manual page with additional information on option
    548: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    549: .vb
    550:   PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
    551: .ve
    552: or
    553: .vb
    554:   value = defaultvalue
    555:   PetscOptionsBoundedInt(..., value, &value, &set, ...);
    556:   if (set) {
    557: .ve
    558: -  bound - the requested value should be greater than or equal to this bound or an error is generated

    560:    Output Parameters:
    561: +  value - the integer value to return
    562: -  set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    564:    Level: beginner

    566:    Notes:
    567:    If the user does not supply the option at all `value` is NOT changed. Thus
    568:    you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    570:    The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    572:    Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    574: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    575:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
    576:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    577:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    578:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    579:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    580:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    581: M*/
    582:   #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb)      PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)

    584: /*MC
    585:    PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.

    587:    Synopsis:
    588: #include <petscoptions.h>
    589:    PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)

    591:    Logically Collective on the communicator passed in `PetscOptionsBegin()`

    593:    Input Parameters:
    594: +  opt          - option name
    595: .  text         - short string that describes the option
    596: .  man          - manual page with additional information on option
    597: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    598: .vb
    599:   PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
    600: .ve
    601: or
    602: .vb
    603:   value = defaultvalue
    604:   PetscOptionsRangeInt(..., value, &value, &set, ...);
    605:   if (set) {
    606: .ve
    607: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
    608: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

    610:    Output Parameters:
    611: +  value - the integer value to return
    612: -  set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    614:    Level: beginner

    616:    Notes:
    617:    If the user does not supply the option at all `value` is NOT changed. Thus
    618:    you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    620:    The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    622:    Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    624: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    625:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
    626:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    627:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    628:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    629:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    630:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    631: M*/
    632:   #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub)    PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)

    634: /*MC
    635:   PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.

    637:   Synopsis:
    638: #include <petscoptions.h>
    639:   PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)

    641:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    643:   Input Parameters:
    644: + opt          - option name
    645: . text         - short string that describes the option
    646: . man          - manual page with additional information on option
    647: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    648: .vb
    649:                  PetscOptionsReal(..., obj->value,&obj->value,...) or
    650:                  value = defaultvalue
    651:                  PetscOptionsReal(..., value,&value,&set);
    652:                  if (set) {
    653: .ve

    655:   Output Parameters:
    656: + value - the value to return
    657: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    659:   Level: beginner

    661:   Notes:
    662:   If the user does not supply the option at all `value` is NOT changed. Thus
    663:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    665:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    667:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    669: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    670:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    671:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    672:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    673:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    674:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    675:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    676: M*/
    677:   #define PetscOptionsReal(opt, text, man, currentvalue, value, set)                PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)

    679: /*MC
    680:    PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.

    682:    Synopsis:
    683: #include <petscoptions.h>
    684:    PetscErrorCode  PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)

    686:    Logically Collective on the communicator passed in `PetscOptionsBegin()`

    688:    Input Parameters:
    689: +  opt          - option name
    690: .  text         - short string that describes the option
    691: .  man          - manual page with additional information on option
    692: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    693: .vb
    694:   PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
    695: .ve
    696: or
    697: .vb
    698:   value = defaultvalue
    699:   PetscOptionsBoundedReal(..., value, &value, &set, ...);
    700:   if (set) {
    701: .ve
    702: -  bound - the requested value should be greater than or equal to this bound or an error is generated

    704:    Output Parameters:
    705: +  value - the real value to return
    706: -  set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    708:    Level: beginner

    710:    Notes:
    711:    If the user does not supply the option at all `value` is NOT changed. Thus
    712:    you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    714:    The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    716:    Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    718: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    719:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
    720:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    721:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    722:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    723:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    724:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
    725: M*/
    726:   #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb)     PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)

    728: /*MC
    729:    PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.

    731:    Synopsis:
    732: #include <petscoptions.h>
    733:    PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)

    735:    Logically Collective on the communicator passed in `PetscOptionsBegin()`

    737:    Input Parameters:
    738: +  opt          - option name
    739: .  text         - short string that describes the option
    740: .  man          - manual page with additional information on option
    741: .  currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    742: .vb
    743:   PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
    744: .ve
    745: or
    746: .vb
    747:   value = defaultvalue
    748:   PetscOptionsRangeReal(..., value, &value, &set, ...);
    749:   if (set) {
    750: .ve
    751: .  lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
    752: -  ub - the upper bound, provided value must be less than or equal to this value or an error is generated

    754:    Output Parameters:
    755: +  value - the value to return
    756: -  set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    758:    Level: beginner

    760:    Notes:
    761:    If the user does not supply the option at all `value` is NOT changed. Thus
    762:    you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    764:    The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    766:    Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    768: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    769:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
    770:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    771:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    772:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    773:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    774:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
    775: M*/
    776:   #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub)   PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)

    778: /*MC
    779:   PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.

    781:   Synopsis:
    782: #include <petscoptions.h>
    783:   PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)

    785:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    787:   Input Parameters:
    788: + opt          - option name
    789: . text         - short string that describes the option
    790: . man          - manual page with additional information on option
    791: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
    792: .vb
    793:                  PetscOptionsScalar(..., obj->value,&obj->value,...) or
    794:                  value = defaultvalue
    795:                  PetscOptionsScalar(..., value,&value,&set);
    796:                  if (set) {
    797: .ve

    799:   Output Parameters:
    800: + value - the value to return
    801: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    803:   Level: beginner

    805:   Notes:
    806:   If the user does not supply the option at all `value` is NOT changed. Thus
    807:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    809:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    811:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    813: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    814:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    815:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    816:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    817:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    818:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    819:           `PetscOptionsFList()`, `PetscOptionsEList()`
    820: M*/
    821:   #define PetscOptionsScalar(opt, text, man, currentvalue, value, set)              PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    823: /*MC
    824:   PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
    825:   its value is set to false.

    827:   Synopsis:
    828: #include <petscoptions.h>
    829:   PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)

    831:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    833:   Input Parameters:
    834: + opt  - option name
    835: . text - short string that describes the option
    836: - man  - manual page with additional information on option

    838:   Output Parameter:
    839: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    841:   Level: beginner

    843:   Note:
    844:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    846: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    847:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    848:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    849:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    850:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    851:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    852:           `PetscOptionsFList()`, `PetscOptionsEList()`
    853: M*/
    854:   #define PetscOptionsName(opt, text, man, set)                                     PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)

    856: /*MC
    857:   PetscOptionsString - Gets the string value for a particular option in the database.

    859:   Synopsis:
    860: #include <petscoptions.h>
    861:   PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)

    863:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    865:   Input Parameters:
    866: + opt          - option name
    867: . text         - short string that describes the option
    868: . man          - manual page with additional information on option
    869: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
    870: - len          - length of the result string including null terminator

    872:   Output Parameters:
    873: + value - the value to return
    874: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    876:   Level: beginner

    878:   Notes:
    879:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    881:   If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).

    883:   If the user does not supply the option at all `value` is NOT changed. Thus
    884:   you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.

    886:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    888: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    889:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    890:           `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    891:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    892:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    893:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    894:           `PetscOptionsFList()`, `PetscOptionsEList()`
    895: M*/
    896:   #define PetscOptionsString(opt, text, man, currentvalue, value, len, set)         PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)

    898: /*MC
    899:   PetscOptionsBool - Determines if a particular option is in the database with a true or false

    901:   Synopsis:
    902: #include <petscoptions.h>
    903:   PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)

    905:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    907:   Input Parameters:
    908: + opt          - option name
    909: . text         - short string that describes the option
    910: . man          - manual page with additional information on option
    911: - currentvalue - the current value

    913:   Output Parameters:
    914: + flg - `PETSC_TRUE` or `PETSC_FALSE`
    915: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    917:   Level: beginner

    919:   Notes:
    920:   TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
    921:   FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`

    923:   If the option is given, but no value is provided, then `flg` and `set` are both given the value `PETSC_TRUE`. That is `-requested_bool`
    924:   is equivalent to `-requested_bool true`

    926:   If the user does not supply the option at all `flg` is NOT changed. Thus
    927:   you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.

    929:   Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    931: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    932:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    933:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
    934:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    935:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    936:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    937:           `PetscOptionsFList()`, `PetscOptionsEList()`
    938: M*/
    939:   #define PetscOptionsBool(opt, text, man, currentvalue, value, set)                PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    941: /*MC
    942:   PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
    943:   which at most a single value can be true.

    945:   Synopsis:
    946: #include <petscoptions.h>
    947:   PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)

    949:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    951:   Input Parameters:
    952: + opt  - option name
    953: . text - short string that describes the option
    954: - man  - manual page with additional information on option

    956:   Output Parameter:
    957: . set - whether that option was set or not

    959:   Level: intermediate

    961:   Notes:
    962:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    964:   Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`

    966: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    967:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    968:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    969:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    970:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    971:           `PetscOptionsFList()`, `PetscOptionsEList()`
    972: M*/
    973:   #define PetscOptionsBoolGroupBegin(opt, text, man, set)                           PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)

    975: /*MC
    976:   PetscOptionsBoolGroup - One in a series of logical queries on the options database for
    977:   which at most a single value can be true.

    979:   Synopsis:
    980: #include <petscoptions.h>
    981:   PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)

    983:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    985:   Input Parameters:
    986: + opt  - option name
    987: . text - short string that describes the option
    988: - man  - manual page with additional information on option

    990:   Output Parameter:
    991: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    993:   Level: intermediate

    995:   Notes:
    996:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    998:   Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`

    1000: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1001:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1002:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1003:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1004:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1005:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1006: M*/
    1007:   #define PetscOptionsBoolGroup(opt, text, man, set)                                PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)

    1009: /*MC
    1010:   PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
    1011:   which at most a single value can be true.

    1013:   Synopsis:
    1014: #include <petscoptions.h>
    1015:   PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool  *set)

    1017:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1019:   Input Parameters:
    1020: + opt  - option name
    1021: . text - short string that describes the option
    1022: - man  - manual page with additional information on option

    1024:   Output Parameter:
    1025: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1027:   Level: intermediate

    1029:   Notes:
    1030:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1032:   Must follow a `PetscOptionsBoolGroupBegin()`

    1034: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1035:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1036:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1037:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1038:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1039:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1040: M*/
    1041:   #define PetscOptionsBoolGroupEnd(opt, text, man, set)                             PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)

    1043: /*MC
    1044:   PetscOptionsFList - Puts a list of option values that a single one may be selected from

    1046:   Synopsis:
    1047: #include <petscoptions.h>
    1048:   PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)

    1050:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1052:   Input Parameters:
    1053: + opt          - option name
    1054: . ltext        - short string that describes the option
    1055: . man          - manual page with additional information on option
    1056: . list         - the possible choices
    1057: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1058: .vb
    1059:                  PetscOptionsFlist(..., obj->value,value,len,&set);
    1060:                  if (set) {
    1061: .ve
    1062: - len          - the length of the character array value

    1064:   Output Parameters:
    1065: + value - the value to return
    1066: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1068:   Level: intermediate

    1070:   Notes:
    1071:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1073:   If the user does not supply the option at all `value` is NOT changed. Thus
    1074:   you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.

    1076:   The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.

    1078:   See `PetscOptionsEList()` for when the choices are given in a string array

    1080:   To get a listing of all currently specified options,
    1081:   see `PetscOptionsView()` or `PetscOptionsGetAll()`

    1083:   Developer Note:
    1084:   This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list

    1086: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1087:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1088:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1089:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1090:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1091:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
    1092: M*/
    1093:   #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set)   PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)

    1095: /*MC
    1096:   PetscOptionsEList - Puts a list of option values that a single one may be selected from

    1098:   Synopsis:
    1099: #include <petscoptions.h>
    1100:   PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)

    1102:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1104:   Input Parameters:
    1105: + opt          - option name
    1106: . ltext        - short string that describes the option
    1107: . man          - manual page with additional information on option
    1108: . list         - the possible choices (one of these must be selected, anything else is invalid)
    1109: . ntext        - number of choices
    1110: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1111: .vb
    1112:                  PetscOptionsEList(..., obj->value,&value,&set);
    1113: .ve                 if (set) {

    1115:   Output Parameters:
    1116: + value - the index of the value to return
    1117: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1119:   Level: intermediate

    1121:   Notes:
    1122:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1124:   If the user does not supply the option at all `value` is NOT changed. Thus
    1125:   you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.

    1127:   See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`

    1129: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1130:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1131:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1132:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1133:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1134:           `PetscOptionsFList()`, `PetscOptionsEnum()`
    1135: M*/
    1136:   #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)

    1138: /*MC
    1139:   PetscOptionsRealArray - Gets an array of double values for a particular
    1140:   option in the database. The values must be separated with commas with
    1141:   no intervening spaces.

    1143:   Synopsis:
    1144: #include <petscoptions.h>
    1145:   PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)

    1147:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1149:   Input Parameters:
    1150: + opt  - the option one is seeking
    1151: . text - short string describing option
    1152: . man  - manual page for option
    1153: - n    - maximum number of values that value has room for

    1155:   Output Parameters:
    1156: + value - location to copy values
    1157: . n     - actual number of values found
    1158: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1160:   Level: beginner

    1162:   Note:
    1163:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1165: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1166:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1167:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1168:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1169:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1170:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1171: M*/
    1172:   #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set)           PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    1174: /*MC
    1175:   PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
    1176:   option in the database. The values must be separated with commas with
    1177:   no intervening spaces.

    1179:   Synopsis:
    1180: #include <petscoptions.h>
    1181:   PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)

    1183:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1185:   Input Parameters:
    1186: + opt  - the option one is seeking
    1187: . text - short string describing option
    1188: . man  - manual page for option
    1189: - n    - maximum number of values allowed in the value array

    1191:   Output Parameters:
    1192: + value - location to copy values
    1193: . n     - actual number of values found
    1194: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1196:   Level: beginner

    1198:   Note:
    1199:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1201: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1202:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1203:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1204:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1205:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1206:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1207: M*/
    1208:   #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set)         PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    1210: /*MC
    1211:   PetscOptionsIntArray - Gets an array of integers for a particular
    1212:   option in the database.

    1214:   Synopsis:
    1215: #include <petscoptions.h>
    1216:   PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)

    1218:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1220:   Input Parameters:
    1221: + opt  - the option one is seeking
    1222: . text - short string describing option
    1223: . man  - manual page for option
    1224: - n    - maximum number of values

    1226:   Output Parameters:
    1227: + value - location to copy values
    1228: . n     - actual number of values found
    1229: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1231:   Level: beginner

    1233:   Notes:
    1234:   The array can be passed as
    1235: +   a comma separated list -                                  0,1,2,3,4,5,6,7
    1236: .   a range (start\-end+1) -                                  0-8
    1237: .   a range with given increment (start\-end+1:inc) -         0-7:2
    1238: -   a combination of values and ranges separated by commas -  0,1-8,8-15:2

    1240:   There must be no intervening spaces between the values.

    1242:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1244: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1245:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1246:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1247:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1248:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1249:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1250: M*/
    1251:   #define PetscOptionsIntArray(opt, text, man, currentvalue, value, set)            PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    1253: /*MC
    1254:   PetscOptionsStringArray - Gets an array of string values for a particular
    1255:   option in the database. The values must be separated with commas with
    1256:   no intervening spaces.

    1258:   Synopsis:
    1259: #include <petscoptions.h>
    1260:   PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool  *set)

    1262:   Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support

    1264:   Input Parameters:
    1265: + opt  - the option one is seeking
    1266: . text - short string describing option
    1267: . man  - manual page for option
    1268: - nmax - maximum number of strings

    1270:   Output Parameters:
    1271: + value - location to copy strings
    1272: . nmax  - actual number of strings found
    1273: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1275:   Level: beginner

    1277:   Notes:
    1278:   The user should pass in an array of pointers to char, to hold all the
    1279:   strings returned by this function.

    1281:   The user is responsible for deallocating the strings that are
    1282:   returned.

    1284:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1286: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1287:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1288:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1289:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1290:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1291:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1292: M*/
    1293:   #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set)         PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    1295: /*MC
    1296:   PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
    1297:   option in the database. The values must be separated with commas with
    1298:   no intervening spaces.

    1300:   Synopsis:
    1301: #include <petscoptions.h>
    1302:   PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)

    1304:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1306:   Input Parameters:
    1307: + opt  - the option one is seeking
    1308: . text - short string describing option
    1309: . man  - manual page for option
    1310: - n    - maximum number of values allowed in the value array

    1312:   Output Parameters:
    1313: + value - location to copy values
    1314: . n     - actual number of values found
    1315: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1317:   Level: beginner

    1319:   Notes:
    1320:   The user should pass in an array of `PetscBool`

    1322:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1324: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1325:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1326:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1327:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1328:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1329:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1330: M*/
    1331:   #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set)           PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

    1333: /*MC
    1334:   PetscOptionsEnumArray - Gets an array of enum values for a particular
    1335:   option in the database.

    1337:   Synopsis:
    1338: #include <petscoptions.h>
    1339:   PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)

    1341:   Logically Collective on the communicator passed in `PetscOptionsBegin()`

    1343:   Input Parameters:
    1344: + opt  - the option one is seeking
    1345: . text - short string describing option
    1346: . man  - manual page for option
    1347: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    1348: - n    - maximum number of values allowed in the value array

    1350:   Output Parameters:
    1351: + value - location to copy values
    1352: . n     - actual number of values found
    1353: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1355:   Level: beginner

    1357:   Notes:
    1358:   The array must be passed as a comma separated list.

    1360:   There must be no intervening spaces between the values.

    1362:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1364: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1365:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    1366:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1367:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1368:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1369:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1370: M*/
    1371:   #define PetscOptionsEnumArray(opt, text, man, list, value, n, set)                PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)

    1373: /*MC
    1374:   PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`

    1376:   Prints a deprecation warning, unless an option is supplied to suppress.

    1378:   Logically Collective

    1380:   Input Parameters:
    1381: + oldname - the old, deprecated option
    1382: . newname - the new option, or `NULL` if option is purely removed
    1383: . version - a string describing the version of first deprecation, e.g. "3.9"
    1384: - info    - additional information string, or `NULL`.

    1386:   Options Database Key:
    1387: . -options_suppress_deprecated_warnings - do not print deprecation warnings

    1389:   Level: developer

    1391:   Notes:
    1392:   If `newname` is provided then the options database will automatically check the database for `oldname`.

    1394:   The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
    1395:   new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
    1396:   See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.

    1398:   Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
    1399:   Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
    1400:   If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
    1401:   If an option is not replaced, the info argument should be used to advise the user on how to proceed.
    1402:   There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.

    1404: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
    1405: M*/
    1406:   #define PetscOptionsDeprecated(opt, text, man, info)                              PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)

    1408: /*MC
    1409:   PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`

    1411:   Prints a deprecation warning, unless an option is supplied to suppress.

    1413:   Logically Collective

    1415:   Input Parameters:
    1416: + oldname - the old, deprecated option
    1417: . newname - the new option, or `NULL` if option is purely removed
    1418: . version - a string describing the version of first deprecation, e.g. "3.9"
    1419: - info    - additional information string, or `NULL`.

    1421:   Options Database Key:
    1422: . -options_suppress_deprecated_warnings - do not print deprecation warnings

    1424:   Level: developer

    1426:   Notes:
    1427:   If `newname` is provided then the options database will automatically check the database for `oldname`.

    1429:   The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
    1430:   new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
    1431:   See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.

    1433:   Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
    1434:   If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
    1435:   If an option is not replaced, the info argument should be used to advise the user on how to proceed.
    1436:   There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.

    1438: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
    1439: M*/
    1440:   #define PetscOptionsDeprecatedNoObject(opt, text, man, info)                      PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
    1441: #endif /* PETSC_CLANG_STATIC_ANALYZER */

    1443: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
    1444: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
    1445: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
    1446: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
    1447: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
    1448: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
    1449: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems *, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
    1450: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
    1451: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
    1452: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
    1453: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
    1454: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
    1455: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
    1456: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
    1457: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
    1458: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
    1459: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
    1460: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
    1461: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
    1462: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *, const char[], const char[], const char[], const char[]);

    1464: PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void);

    1466: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems *, void *), PetscErrorCode (*)(PetscObject, void *), void *);
    1467: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems *);
    1468: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);

    1470: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);