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 PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
 32: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
 33: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
 34: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
 35: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
 36: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
 37: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);

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

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

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

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

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

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

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

 83: PETSC_EXTERN PetscBool PetscOptionsPublish;

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

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

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

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

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

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

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

150:     Collective

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

158:     Level: intermediate

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

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

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

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

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

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

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

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

208:     Collective

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

213:     Level: intermediate

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

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

220:     Can add subheadings with `PetscOptionsHeadBegin()`

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

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

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

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

248:     Level: intermediate

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

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

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

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

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

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

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

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

336:    Level: developer

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

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

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

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

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

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

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

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

369:      Level: intermediate

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

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

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

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

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

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

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

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

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

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

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

422:   Level: beginner

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

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

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

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

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

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

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

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

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

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

469:   Level: beginner

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

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

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

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

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

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

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

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

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

514:   Level: beginner

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

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

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

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

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

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

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

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

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

563:    Level: beginner

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

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

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

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

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

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

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

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

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

613:    Level: beginner

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

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

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

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

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

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

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

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

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

658:   Level: beginner

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

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

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

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

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

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

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

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

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

707:    Level: beginner

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

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

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

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

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

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

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

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

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

757:    Level: beginner

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

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

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

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

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

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

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

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

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

802:   Level: beginner

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

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

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

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

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

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

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

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

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

840:   Level: beginner

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

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

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

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

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

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

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

875:   Level: beginner

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

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

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

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

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

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

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

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

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

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

916:   Level: beginner

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

922:   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`
923:   is equivalent to `-requested_bool true`

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

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

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

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

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

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

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

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

958:   Level: intermediate

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

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

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

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

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

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

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

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

992:   Level: intermediate

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

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

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

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

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

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

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

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

1026:   Level: intermediate

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

1031:   Must follow a `PetscOptionsBoolGroupBegin()`

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

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

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

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

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

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

1067:   Level: intermediate

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

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

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

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

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

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

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

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

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

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

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

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

1118:   Level: intermediate

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

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

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

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

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

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

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

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

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

1159:   Level: beginner

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

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

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

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

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

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

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

1195:   Level: beginner

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

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

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

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

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

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

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

1230:   Level: beginner

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

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

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

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

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

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

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

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

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

1274:   Level: beginner

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

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

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

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

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

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

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

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

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

1316:   Level: beginner

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

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

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

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

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

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

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

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

1354:   Level: beginner

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

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

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

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

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

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

1377:   Logically Collective

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

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

1388:   Level: developer

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

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

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

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

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

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

1412:   Logically Collective

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

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

1423:   Level: developer

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

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

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

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

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

1463: PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void);

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

1469: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);