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, const char *const *);
     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 *, PetscCtxDestroyFn *);
     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 _n_PetscOptionItems *PetscOptionItems;
    126: struct _n_PetscOptionItems {
    127:   PetscInt        count;
    128:   PetscOptionItem next;
    129:   char           *prefix, *pprefix;
    130:   char           *title;
    131:   MPI_Comm        comm;
    132:   PetscBool       printhelp, changedmethod, alreadyprinted;
    133:   PetscObject     object;
    134:   PetscOptions    options;
    135: };

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

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

    152:     Collective

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

    160:     Level: intermediate

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

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

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

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

    183:      Fortran Note:
    184:      Returns ierr error code as the final argument per PETSc Fortran API

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

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

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

    210:     Collective

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

    215:     Level: intermediate

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

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

    222:     Can add subheadings with `PetscOptionsHeadBegin()`

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

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

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

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

    250:     Level: intermediate

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

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

    257:     Fortran Note:
    258:     Returns ierr error code as the final argument per PETSc Fortran API

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

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

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

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

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

    338:    Level: developer

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

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

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

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

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

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

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

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

    371:      Level: intermediate

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

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

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

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

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

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

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

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

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

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

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

    424:   Level: beginner

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

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

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

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

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

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

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

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

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

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

    471:   Level: beginner

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

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

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

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

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

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

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

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

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

    516:   Level: beginner

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

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

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

    526: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    527:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
    528:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
    529:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    530:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    531:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    532:           `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
    533: M*/
    534:   #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)

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

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

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

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

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

    565:    Level: beginner

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

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

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

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

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

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

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

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

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

    615:    Level: beginner

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

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

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

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

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

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

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

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

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

    660:   Level: beginner

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

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

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

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

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

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

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

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

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

    709:    Level: beginner

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

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

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

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

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

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

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

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

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

    759:    Level: beginner

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

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

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

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

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

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

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

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

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

    804:   Level: beginner

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

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

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

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

    824: /*MC
    825:   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
    826:   its value is set to false.

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

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

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

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

    842:   Level: beginner

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

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

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

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

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

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

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

    877:   Level: beginner

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

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

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

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

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

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

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

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

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

    914:   Output Parameters:
    915: + flg - `PETSC_TRUE` or `PETSC_FALSE`
    916: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed

    918:   Level: beginner

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

    924:   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`
    925:   is equivalent to `-requested_bool true`

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

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

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

    942: /*MC
    943:   PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown

    945:   Synopsis:
    946: #include <petscoptions.h>
    947:   PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, 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
    955: - currentvalue - the current value

    957:   Output Parameters:
    958: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
    959: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    961:   Level: beginner

    963:   Notes:
    964:   TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
    965:   FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`

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

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

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

    975: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
    976:           `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    977:           `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
    978:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    979:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    980:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    981:           `PetscOptionsFList()`, `PetscOptionsEList()`
    982: M*/
    983:   #define PetscOptionsBool3(opt, text, man, currentvalue, value, set)               PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)

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

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

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

    995:   Input Parameters:
    996: + opt  - option name
    997: . text - short string that describes the option
    998: - man  - manual page with additional information on option

    1000:   Output Parameter:
    1001: . set - whether that option was set or not

    1003:   Level: intermediate

    1005:   Notes:
    1006:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

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

    1010: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1011:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1012:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1013:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1014:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1015:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1016: M*/
    1017:   #define PetscOptionsBoolGroupBegin(opt, text, man, set)                           PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)

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

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

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

    1029:   Input Parameters:
    1030: + opt  - option name
    1031: . text - short string that describes the option
    1032: - man  - manual page with additional information on option

    1034:   Output Parameter:
    1035: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1037:   Level: intermediate

    1039:   Notes:
    1040:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

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

    1044: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1045:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1046:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1047:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1048:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1049:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1050: M*/
    1051:   #define PetscOptionsBoolGroup(opt, text, man, set)                                PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)

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

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

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

    1063:   Input Parameters:
    1064: + opt  - option name
    1065: . text - short string that describes the option
    1066: - man  - manual page with additional information on option

    1068:   Output Parameter:
    1069: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1071:   Level: intermediate

    1073:   Notes:
    1074:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1076:   Must follow a `PetscOptionsBoolGroupBegin()`

    1078: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1079:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1080:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1081:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1082:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1083:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1084: M*/
    1085:   #define PetscOptionsBoolGroupEnd(opt, text, man, set)                             PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)

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

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

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

    1096:   Input Parameters:
    1097: + opt          - option name
    1098: . ltext        - short string that describes the option
    1099: . man          - manual page with additional information on option
    1100: . list         - the possible choices
    1101: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1102: .vb
    1103:                  PetscOptionsFlist(..., obj->value,value,len,&set);
    1104:                  if (set) {
    1105: .ve
    1106: - len          - the length of the character array value

    1108:   Output Parameters:
    1109: + value - the value to return
    1110: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1112:   Level: intermediate

    1114:   Notes:
    1115:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

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

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

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

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

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

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

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

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

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

    1148:   Input Parameters:
    1149: + opt          - option name
    1150: . ltext        - short string that describes the option
    1151: . man          - manual page with additional information on option
    1152: . list         - the possible choices (one of these must be selected, anything else is invalid)
    1153: . ntext        - number of choices
    1154: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
    1155: .vb
    1156:                  PetscOptionsEList(..., obj->value,&value,&set);
    1157: .ve                 if (set) {

    1159:   Output Parameters:
    1160: + value - the index of the value to return
    1161: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1163:   Level: intermediate

    1165:   Notes:
    1166:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

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

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

    1173: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1174:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1175:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1176:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1177:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1178:           `PetscOptionsFList()`, `PetscOptionsEnum()`
    1179: M*/
    1180:   #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)

    1182: /*MC
    1183:   PetscOptionsRealArray - Gets an array of double values for a particular
    1184:   option in the database. The values must be separated with commas with
    1185:   no intervening spaces.

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

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

    1193:   Input Parameters:
    1194: + opt  - the option one is seeking
    1195: . text - short string describing option
    1196: . man  - manual page for option
    1197: - n    - maximum number of values that value has room for

    1199:   Output Parameters:
    1200: + value - location to copy values
    1201: . n     - actual number of values found
    1202: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1204:   Level: beginner

    1206:   Note:
    1207:   Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`

    1209: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1210:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1211:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1212:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1213:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1214:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1215: M*/
    1216:   #define PetscOptionsRealArray(opt, text, man, value, n, set)                      PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)

    1218: /*MC
    1219:   PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
    1220:   option in the database. The values must be separated with commas with
    1221:   no intervening spaces.

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

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

    1229:   Input Parameters:
    1230: + opt  - the option one is seeking
    1231: . text - short string describing option
    1232: . man  - manual page for option
    1233: - n    - maximum number of values allowed in the value array

    1235:   Output Parameters:
    1236: + value - location to copy values
    1237: . n     - actual number of values found
    1238: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1240:   Level: beginner

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

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

    1254: /*MC
    1255:   PetscOptionsIntArray - Gets an array of integers for a particular
    1256:   option in the database.

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

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

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

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

    1275:   Level: beginner

    1277:   Notes:
    1278:   The array can be passed as
    1279: +   a comma separated list -                                  0,1,2,3,4,5,6,7
    1280: .   a range (start\-end+1) -                                  0-8
    1281: .   a range with given increment (start\-end+1:inc) -         0-7:2
    1282: -   a combination of values and ranges separated by commas -  0,1-8,8-15:2

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

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

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

    1297: /*MC
    1298:   PetscOptionsStringArray - Gets an array of string values for a particular
    1299:   option in the database. The values must be separated with commas with
    1300:   no intervening spaces.

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

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

    1308:   Input Parameters:
    1309: + opt  - the option one is seeking
    1310: . text - short string describing option
    1311: . man  - manual page for option
    1312: - n    - maximum number of strings

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

    1319:   Level: beginner

    1321:   Notes:
    1322:   The user should pass in an array of pointers to char, to hold all the
    1323:   strings returned by this function.

    1325:   The user is responsible for deallocating the strings that are
    1326:   returned.

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

    1330: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1331:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1332:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1333:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1334:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1335:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1336: M*/
    1337:   #define PetscOptionsStringArray(opt, text, man, value, n, set)                    PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)

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

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

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

    1350:   Input Parameters:
    1351: + opt  - the option one is seeking
    1352: . text - short string describing option
    1353: . man  - manual page for option
    1354: - n    - maximum number of values allowed in the value array

    1356:   Output Parameters:
    1357: + value - location to copy values
    1358: . n     - actual number of values found
    1359: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1361:   Level: beginner

    1363:   Notes:
    1364:   The user should pass in an array of `PetscBool`

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

    1368: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1369:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
    1370:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1371:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1372:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1373:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1374: M*/
    1375:   #define PetscOptionsBoolArray(opt, text, man, value, n, set)                      PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)

    1377: /*MC
    1378:   PetscOptionsEnumArray - Gets an array of enum values for a particular
    1379:   option in the database.

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

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

    1387:   Input Parameters:
    1388: + opt  - the option one is seeking
    1389: . text - short string describing option
    1390: . man  - manual page for option
    1391: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
    1392: - n    - maximum number of values allowed in the value array

    1394:   Output Parameters:
    1395: + value - location to copy values
    1396: . n     - actual number of values found
    1397: - set   - `PETSC_TRUE` if found, else `PETSC_FALSE`

    1399:   Level: beginner

    1401:   Notes:
    1402:   The array must be passed as a comma separated list.

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

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

    1408: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
    1409:           `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
    1410:           `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
    1411:           `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
    1412:           `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
    1413:           `PetscOptionsFList()`, `PetscOptionsEList()`
    1414: M*/
    1415:   #define PetscOptionsEnumArray(opt, text, man, list, value, n, set)                PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)

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

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

    1422:   Logically Collective

    1424:   Input Parameters:
    1425: + oldname - the old, deprecated option
    1426: . newname - the new option, or `NULL` if option is purely removed
    1427: . version - a string describing the version of first deprecation, e.g. "3.9"
    1428: - info    - additional information string, or `NULL`.

    1430:   Options Database Key:
    1431: . -options_suppress_deprecated_warnings - do not print deprecation warnings

    1433:   Level: developer

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

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

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

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

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

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

    1457:   Logically Collective

    1459:   Input Parameters:
    1460: + oldname - the old, deprecated option
    1461: . newname - the new option, or `NULL` if option is purely removed
    1462: . version - a string describing the version of first deprecation, e.g. "3.9"
    1463: - info    - additional information string, or `NULL`.

    1465:   Options Database Key:
    1466: . -options_suppress_deprecated_warnings - do not print deprecation warnings

    1468:   Level: developer

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

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

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

    1482: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
    1483: M*/
    1484:   #define PetscOptionsDeprecatedNoObject(opt, text, man, info)                      PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
    1485: #endif /* PETSC_CLANG_STATIC_ANALYZER */

    1487: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
    1488: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
    1489: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
    1490: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
    1491: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
    1492: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
    1493: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
    1494: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
    1495: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
    1496: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
    1497: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
    1498: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
    1499: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
    1500: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
    1501: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
    1502: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
    1503: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
    1504: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
    1505: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
    1506: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
    1507: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);

    1509: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
    1510: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
    1511: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);

    1513: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);