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 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 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`
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: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
944: which at most a single value can be true.
946: Synopsis:
947: #include <petscoptions.h>
948: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
950: Logically Collective on the communicator passed in `PetscOptionsBegin()`
952: Input Parameters:
953: + opt - option name
954: . text - short string that describes the option
955: - man - manual page with additional information on option
957: Output Parameter:
958: . set - whether that option was set or not
960: Level: intermediate
962: Notes:
963: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
965: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
967: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
968: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
969: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
970: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
971: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
972: `PetscOptionsFList()`, `PetscOptionsEList()`
973: M*/
974: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
976: /*MC
977: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
978: which at most a single value can be true.
980: Synopsis:
981: #include <petscoptions.h>
982: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
984: Logically Collective on the communicator passed in `PetscOptionsBegin()`
986: Input Parameters:
987: + opt - option name
988: . text - short string that describes the option
989: - man - manual page with additional information on option
991: Output Parameter:
992: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
994: Level: intermediate
996: Notes:
997: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
999: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1001: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1002: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1003: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1004: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1005: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1006: `PetscOptionsFList()`, `PetscOptionsEList()`
1007: M*/
1008: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1010: /*MC
1011: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1012: which at most a single value can be true.
1014: Synopsis:
1015: #include <petscoptions.h>
1016: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1018: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1020: Input Parameters:
1021: + opt - option name
1022: . text - short string that describes the option
1023: - man - manual page with additional information on option
1025: Output Parameter:
1026: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1028: Level: intermediate
1030: Notes:
1031: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1033: Must follow a `PetscOptionsBoolGroupBegin()`
1035: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1036: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1037: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1038: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1039: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1040: `PetscOptionsFList()`, `PetscOptionsEList()`
1041: M*/
1042: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1044: /*MC
1045: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1047: Synopsis:
1048: #include <petscoptions.h>
1049: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1051: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1053: Input Parameters:
1054: + opt - option name
1055: . ltext - short string that describes the option
1056: . man - manual page with additional information on option
1057: . list - the possible choices
1058: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1059: .vb
1060: PetscOptionsFlist(..., obj->value,value,len,&set);
1061: if (set) {
1062: .ve
1063: - len - the length of the character array value
1065: Output Parameters:
1066: + value - the value to return
1067: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1069: Level: intermediate
1071: Notes:
1072: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1074: If the user does not supply the option at all `value` is NOT changed. Thus
1075: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1077: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1079: See `PetscOptionsEList()` for when the choices are given in a string array
1081: To get a listing of all currently specified options,
1082: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1084: Developer Note:
1085: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1087: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1088: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1089: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1090: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1091: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1092: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1093: M*/
1094: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1096: /*MC
1097: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1099: Synopsis:
1100: #include <petscoptions.h>
1101: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1103: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1105: Input Parameters:
1106: + opt - option name
1107: . ltext - short string that describes the option
1108: . man - manual page with additional information on option
1109: . list - the possible choices (one of these must be selected, anything else is invalid)
1110: . ntext - number of choices
1111: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1112: .vb
1113: PetscOptionsEList(..., obj->value,&value,&set);
1114: .ve if (set) {
1116: Output Parameters:
1117: + value - the index of the value to return
1118: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1120: Level: intermediate
1122: Notes:
1123: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1125: If the user does not supply the option at all `value` is NOT changed. Thus
1126: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1128: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1130: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1131: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1132: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1133: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1134: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1135: `PetscOptionsFList()`, `PetscOptionsEnum()`
1136: M*/
1137: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1139: /*MC
1140: PetscOptionsRealArray - Gets an array of double values for a particular
1141: option in the database. The values must be separated with commas with
1142: no intervening spaces.
1144: Synopsis:
1145: #include <petscoptions.h>
1146: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1148: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1150: Input Parameters:
1151: + opt - the option one is seeking
1152: . text - short string describing option
1153: . man - manual page for option
1154: - n - maximum number of values that value has room for
1156: Output Parameters:
1157: + value - location to copy values
1158: . n - actual number of values found
1159: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1161: Level: beginner
1163: Note:
1164: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1166: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1167: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1168: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1169: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1170: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1171: `PetscOptionsFList()`, `PetscOptionsEList()`
1172: M*/
1173: #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1175: /*MC
1176: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1177: option in the database. The values must be separated with commas with
1178: no intervening spaces.
1180: Synopsis:
1181: #include <petscoptions.h>
1182: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1184: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1186: Input Parameters:
1187: + opt - the option one is seeking
1188: . text - short string describing option
1189: . man - manual page for option
1190: - n - maximum number of values allowed in the value array
1192: Output Parameters:
1193: + value - location to copy values
1194: . n - actual number of values found
1195: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1197: Level: beginner
1199: Note:
1200: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1202: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1203: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1204: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1205: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1206: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1207: `PetscOptionsFList()`, `PetscOptionsEList()`
1208: M*/
1209: #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1211: /*MC
1212: PetscOptionsIntArray - Gets an array of integers for a particular
1213: option in the database.
1215: Synopsis:
1216: #include <petscoptions.h>
1217: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1219: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1221: Input Parameters:
1222: + opt - the option one is seeking
1223: . text - short string describing option
1224: . man - manual page for option
1225: - n - maximum number of values
1227: Output Parameters:
1228: + value - location to copy values
1229: . n - actual number of values found
1230: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1232: Level: beginner
1234: Notes:
1235: The array can be passed as
1236: + a comma separated list - 0,1,2,3,4,5,6,7
1237: . a range (start\-end+1) - 0-8
1238: . a range with given increment (start\-end+1:inc) - 0-7:2
1239: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1241: There must be no intervening spaces between the values.
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 PetscOptionsIntArray(opt, text, man, currentvalue, value, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1254: /*MC
1255: PetscOptionsStringArray - Gets an array of string values for a particular
1256: option in the database. The values must be separated with commas with
1257: no intervening spaces.
1259: Synopsis:
1260: #include <petscoptions.h>
1261: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1263: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1265: Input Parameters:
1266: + opt - the option one is seeking
1267: . text - short string describing option
1268: . man - manual page for option
1269: - nmax - maximum number of strings
1271: Output Parameters:
1272: + value - location to copy strings
1273: . nmax - actual number of strings found
1274: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1276: Level: beginner
1278: Notes:
1279: The user should pass in an array of pointers to char, to hold all the
1280: strings returned by this function.
1282: The user is responsible for deallocating the strings that are
1283: returned.
1285: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1287: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1288: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1289: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1290: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1291: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1292: `PetscOptionsFList()`, `PetscOptionsEList()`
1293: M*/
1294: #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1296: /*MC
1297: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1298: option in the database. The values must be separated with commas with
1299: no intervening spaces.
1301: Synopsis:
1302: #include <petscoptions.h>
1303: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1305: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1307: Input Parameters:
1308: + opt - the option one is seeking
1309: . text - short string describing option
1310: . man - manual page for option
1311: - n - maximum number of values allowed in the value array
1313: Output Parameters:
1314: + value - location to copy values
1315: . n - actual number of values found
1316: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1318: Level: beginner
1320: Notes:
1321: The user should pass in an array of `PetscBool`
1323: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1325: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1326: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1327: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1328: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1329: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1330: `PetscOptionsFList()`, `PetscOptionsEList()`
1331: M*/
1332: #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1334: /*MC
1335: PetscOptionsEnumArray - Gets an array of enum values for a particular
1336: option in the database.
1338: Synopsis:
1339: #include <petscoptions.h>
1340: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1342: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1344: Input Parameters:
1345: + opt - the option one is seeking
1346: . text - short string describing option
1347: . man - manual page for option
1348: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1349: - n - maximum number of values allowed in the value array
1351: Output Parameters:
1352: + value - location to copy values
1353: . n - actual number of values found
1354: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1356: Level: beginner
1358: Notes:
1359: The array must be passed as a comma separated list.
1361: There must be no intervening spaces between the values.
1363: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1365: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1366: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1367: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1368: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1369: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1370: `PetscOptionsFList()`, `PetscOptionsEList()`
1371: M*/
1372: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1374: /*MC
1375: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1377: Prints a deprecation warning, unless an option is supplied to suppress.
1379: Logically Collective
1381: Input Parameters:
1382: + oldname - the old, deprecated option
1383: . newname - the new option, or `NULL` if option is purely removed
1384: . version - a string describing the version of first deprecation, e.g. "3.9"
1385: - info - additional information string, or `NULL`.
1387: Options Database Key:
1388: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1390: Level: developer
1392: Notes:
1393: If `newname` is provided then the options database will automatically check the database for `oldname`.
1395: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1396: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1397: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1399: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1400: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1401: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1402: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1403: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1405: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1406: M*/
1407: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1409: /*MC
1410: PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1412: Prints a deprecation warning, unless an option is supplied to suppress.
1414: Logically Collective
1416: Input Parameters:
1417: + oldname - the old, deprecated option
1418: . newname - the new option, or `NULL` if option is purely removed
1419: . version - a string describing the version of first deprecation, e.g. "3.9"
1420: - info - additional information string, or `NULL`.
1422: Options Database Key:
1423: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1425: Level: developer
1427: Notes:
1428: If `newname` is provided then the options database will automatically check the database for `oldname`.
1430: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1431: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1432: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1434: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1435: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1436: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1437: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1439: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1440: M*/
1441: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1442: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1444: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1445: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1446: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1447: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1448: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1449: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1450: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1451: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1452: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1453: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1454: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1455: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1456: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1457: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1458: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1459: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1460: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1461: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1462: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1463: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);
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);