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);