Actual source code: petscoptions.h
1: /*
2: Routines to determine options set in the options database.
3: */
4: #pragma once
6: #include <petscsys.h>
7: #include <petscviewertypes.h>
9: /* SUBMANSEC = Sys */
11: typedef enum {
12: PETSC_OPT_CODE,
13: PETSC_OPT_COMMAND_LINE,
14: PETSC_OPT_FILE,
15: PETSC_OPT_ENVIRONMENT,
16: NUM_PETSC_OPT_SOURCE
17: } PetscOptionSource;
19: #define PETSC_MAX_OPTION_NAME 512
20: typedef struct _n_PetscOptions *PetscOptions;
21: PETSC_EXTERN PetscErrorCode PetscOptionsCreate(PetscOptions *);
22: PETSC_EXTERN PetscErrorCode PetscOptionsPush(PetscOptions);
23: PETSC_EXTERN PetscErrorCode PetscOptionsPop(void);
24: PETSC_EXTERN PetscErrorCode PetscOptionsDestroy(PetscOptions *);
25: PETSC_EXTERN PetscErrorCode PetscOptionsCreateDefault(void);
26: PETSC_EXTERN PetscErrorCode PetscOptionsDestroyDefault(void);
28: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
29: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
30: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
31: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
32: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
33: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
34: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
35: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
36: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
37: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
39: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
40: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
41: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
42: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
43: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
44: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
46: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
47: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
48: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
49: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
50: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
52: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
53: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
54: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
55: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
56: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
57: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
58: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
60: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
61: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
62: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
63: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
64: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
65: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
66: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, char **);
67: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
68: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
69: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
71: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
72: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
73: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
74: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
75: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
77: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscErrorCode (*)(void **));
78: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
80: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
81: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
83: PETSC_EXTERN PetscBool PetscOptionsPublish;
85: /*
86: See manual page for PetscOptionsBegin()
88: PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
89: options being handled with a PetscOptionsBegin/End()
91: */
92: typedef enum {
93: OPTION_INT,
94: OPTION_BOOL,
95: OPTION_REAL,
96: OPTION_FLIST,
97: OPTION_STRING,
98: OPTION_REAL_ARRAY,
99: OPTION_SCALAR_ARRAY,
100: OPTION_HEAD,
101: OPTION_INT_ARRAY,
102: OPTION_ELIST,
103: OPTION_BOOL_ARRAY,
104: OPTION_STRING_ARRAY
105: } PetscOptionType;
107: typedef struct _n_PetscOptionItem *PetscOptionItem;
108: struct _n_PetscOptionItem {
109: char *option;
110: char *text;
111: void *data; /* used to hold the default value and then any value it is changed to by GUI */
112: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
113: const char *const *list; /* used for available values for PetscOptionsEList() */
114: char nlist; /* number of entries in list */
115: char *man;
116: PetscInt arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
117: PetscBool set; /* the user has changed this value in the GUI */
118: PetscOptionType type;
119: PetscOptionItem next;
120: char *pman;
121: void *edata;
122: };
124: typedef struct _p_PetscOptionItems {
125: PetscInt count;
126: PetscOptionItem next;
127: char *prefix, *pprefix;
128: char *title;
129: MPI_Comm comm;
130: PetscBool printhelp, changedmethod, alreadyprinted;
131: PetscObject object;
132: PetscOptions options;
133: } PetscOptionItems;
135: #if defined(PETSC_CLANG_STATIC_ANALYZER)
136: extern PetscOptionItems *PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
137: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
138: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
139: PetscErrorCode PetscOptionsEnd(void);
140: #else
141: /*MC
142: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
143: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
144: use `PetscObjectOptionsBegin()` rather than this call.
146: Synopsis:
147: #include <petscoptions.h>
148: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
150: Collective
152: Input Parameters:
153: + comm - communicator that shares GUI
154: . prefix - options prefix for all options displayed on window (optional)
155: . title - short descriptive text, for example "Krylov Solver Options"
156: - mansec - section of manual pages for options, for example `KSP` (optional)
158: Level: intermediate
160: Notes:
161: This is a macro that handles its own error checking, it does not return an error code.
163: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
165: One can add subheadings with `PetscOptionsHeadBegin()`.
167: Developer Notes:
168: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
169: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
170: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
171: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
172: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
173: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
174: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
175: default values are printed if -help was given.
176: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
177: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
178: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
179: currently set.
181: Fortran Note:
182: Returns ierr error code per PETSc Fortran API
184: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
185: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
186: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
187: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
188: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
189: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
190: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
191: M*/
192: #define PetscOptionsBegin(comm, prefix, mess, sec) \
193: do { \
194: PetscOptionItems PetscOptionsObjectBase; \
195: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
196: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
197: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
198: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
200: /*MC
201: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
202: displayed on the same window of a GUI that allows the user to set the options interactively.
204: Synopsis:
205: #include <petscoptions.h>
206: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
208: Collective
210: Input Parameter:
211: . obj - object to set options for
213: Level: intermediate
215: Notes:
216: This is a macro that handles its own error checking, it does not return an error code.
218: Needs to be ended by a call the `PetscOptionsEnd()`
220: Can add subheadings with `PetscOptionsHeadBegin()`
222: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
223: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
224: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
225: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
226: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
227: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
228: `PetscOptionsFList()`, `PetscOptionsEList()`
229: M*/
230: #define PetscObjectOptionsBegin(obj) \
231: do { \
232: PetscOptionItems PetscOptionsObjectBase; \
233: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
234: PetscOptionsObject->options = ((PetscObject)obj)->options; \
235: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
236: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
238: /*MC
239: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
240: displayed on the same window of a GUI that allows the user to set the options interactively.
242: Synopsis:
243: #include <petscoptions.h>
244: PetscErrorCode PetscOptionsEnd(void)
246: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
248: Level: intermediate
250: Notes:
251: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
253: This is a macro that handles its own error checking, it does not return an error code.
255: Fortran Note:
256: Returns ierr error code per PETSc Fortran API
258: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
259: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
260: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
261: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
262: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
263: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
264: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
265: M*/
266: #define PetscOptionsEnd() \
267: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
268: } \
269: } \
270: while (0)
271: #endif /* PETSC_CLANG_STATIC_ANALYZER */
273: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *, MPI_Comm, const char[], const char[], const char[]);
274: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems *);
275: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *);
276: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems *, const char[]);
278: #if defined(PETSC_CLANG_STATIC_ANALYZER)
279: template <typename... T>
280: void PetscOptionsHeadBegin(T...);
281: void PetscOptionsHeadEnd(void);
282: template <typename... T>
283: PetscErrorCode PetscOptionsEnum(T...);
284: template <typename... T>
285: PetscErrorCode PetscOptionsInt(T...);
286: template <typename... T>
287: PetscErrorCode PetscOptionsBoundedInt(T...);
288: template <typename... T>
289: PetscErrorCode PetscOptionsRangeInt(T...);
290: template <typename... T>
291: PetscErrorCode PetscOptionsReal(T...);
292: template <typename... T>
293: PetscErrorCode PetscOptionsScalar(T...);
294: template <typename... T>
295: PetscErrorCode PetscOptionsName(T...);
296: template <typename... T>
297: PetscErrorCode PetscOptionsString(T...);
298: template <typename... T>
299: PetscErrorCode PetscOptionsBool(T...);
300: template <typename... T>
301: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
302: template <typename... T>
303: PetscErrorCode PetscOptionsBoolGroup(T...);
304: template <typename... T>
305: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
306: template <typename... T>
307: PetscErrorCode PetscOptionsFList(T...);
308: template <typename... T>
309: PetscErrorCode PetscOptionsEList(T...);
310: template <typename... T>
311: PetscErrorCode PetscOptionsRealArray(T...);
312: template <typename... T>
313: PetscErrorCode PetscOptionsScalarArray(T...);
314: template <typename... T>
315: PetscErrorCode PetscOptionsIntArray(T...);
316: template <typename... T>
317: PetscErrorCode PetscOptionsStringArray(T...);
318: template <typename... T>
319: PetscErrorCode PetscOptionsBoolArray(T...);
320: template <typename... T>
321: PetscErrorCode PetscOptionsEnumArray(T...);
322: template <typename... T>
323: PetscErrorCode PetscOptionsDeprecated(T...);
324: template <typename... T>
325: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
326: #else
327: /*MC
328: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
329: in `KSPSetFromOptions_GMRES()`.
331: Logically Collective on the communicator passed in `PetscOptionsBegin()`
333: Input Parameter:
334: . head - the heading text
336: Level: developer
338: Notes:
339: Handles errors directly, hence does not return an error code
341: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
343: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
345: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
346: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
347: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
348: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
349: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
350: `PetscOptionsFList()`, `PetscOptionsEList()`
351: M*/
352: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
353: do { \
354: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
355: } while (0)
357: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
359: /*MC
360: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
361: See, for example, `KSPSetFromOptions_GMRES()`.
363: Synopsis:
364: #include <petscoptions.h>
365: PetscErrorCode PetscOptionsHeadEnd(void)
367: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
369: Level: intermediate
371: Notes:
372: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
374: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
376: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
377: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
378: from the function.
380: This is only for use with the PETSc options GUI
382: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
383: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
384: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
385: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
386: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
387: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
388: M*/
389: #define PetscOptionsHeadEnd() \
390: do { \
391: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
392: } while (0)
394: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
396: /*MC
397: PetscOptionsEnum - Gets the enum value for a particular option in the database.
399: Synopsis:
400: #include <petscoptions.h>
401: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
403: Logically Collective on the communicator passed in `PetscOptionsBegin()`
405: Input Parameters:
406: + opt - option name
407: . text - short string that describes the option
408: . man - manual page with additional information on option
409: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
410: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
411: .vb
412: PetscOptionsEnum(..., obj->value,&object->value,...) or
413: value = defaultvalue
414: PetscOptionsEnum(..., value,&value,&set);
415: if (set) {
416: .ve
418: Output Parameters:
419: + value - the value to return
420: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
422: Level: beginner
424: Notes:
425: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
427: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
429: If the user does not supply the option at all `value` is NOT changed. Thus
430: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
432: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
434: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
435: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
436: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
437: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
438: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
439: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
440: `PetscOptionsFList()`, `PetscOptionsEList()`
441: M*/
442: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
444: /*MC
445: PetscOptionsInt - Gets the integer value for a particular option in the database.
447: Synopsis:
448: #include <petscoptions.h>
449: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
451: Logically Collective on the communicator passed in `PetscOptionsBegin()`
453: Input Parameters:
454: + opt - option name
455: . text - short string that describes the option
456: . man - manual page with additional information on option
457: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
458: .vb
459: PetscOptionsInt(..., obj->value, &obj->value, ...) or
460: value = defaultvalue
461: PetscOptionsInt(..., value, &value, &set);
462: if (set) {
463: .ve
465: Output Parameters:
466: + value - the integer value to return
467: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
469: Level: beginner
471: Notes:
472: If the user does not supply the option at all `value` is NOT changed. Thus
473: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
475: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
477: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
479: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
480: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
481: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
482: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
483: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
484: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
485: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
486: M*/
487: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
489: /*MC
490: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
492: Synopsis:
493: #include <petscoptions.h>
494: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
496: Logically Collective on the communicator passed in `PetscOptionsBegin()`
498: Input Parameters:
499: + opt - option name
500: . text - short string that describes the option
501: . man - manual page with additional information on option
502: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
503: .vb
504: PetscOptionsInt(..., obj->value, &obj->value, ...) or
505: value = defaultvalue
506: PetscOptionsInt(..., value, &value, &set);
507: if (set) {
508: .ve
510: Output Parameters:
511: + value - the MPI integer value to return
512: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
514: Level: beginner
516: Notes:
517: If the user does not supply the option at all `value` is NOT changed. Thus
518: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
520: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
522: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
524: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
525: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
526: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
527: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
528: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
529: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
530: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
531: M*/
532: #define PetscOptionsMPIInt(opt, text, man, currentvalue, value, set) PetscOptionsMPIInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MPI_INT_MIN, PETSC_MPI_INT_MAX)
534: /*MC
535: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
537: Synopsis:
538: #include <petscoptions.h>
539: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
541: Logically Collective on the communicator passed in `PetscOptionsBegin()`
543: Input Parameters:
544: + opt - option name
545: . text - short string that describes the option
546: . man - manual page with additional information on option
547: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
548: .vb
549: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
550: .ve
551: or
552: .vb
553: value = defaultvalue
554: PetscOptionsBoundedInt(..., value, &value, &set, ...);
555: if (set) {
556: .ve
557: - bound - the requested value should be greater than or equal to this bound or an error is generated
559: Output Parameters:
560: + value - the integer value to return
561: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
563: Level: beginner
565: Notes:
566: If the user does not supply the option at all `value` is NOT changed. Thus
567: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
569: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
571: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
573: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
574: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
575: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
576: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
577: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
578: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
579: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
580: M*/
581: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
583: /*MC
584: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
586: Synopsis:
587: #include <petscoptions.h>
588: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
590: Logically Collective on the communicator passed in `PetscOptionsBegin()`
592: Input Parameters:
593: + opt - option name
594: . text - short string that describes the option
595: . man - manual page with additional information on option
596: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
597: .vb
598: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
599: .ve
600: or
601: .vb
602: value = defaultvalue
603: PetscOptionsRangeInt(..., value, &value, &set, ...);
604: if (set) {
605: .ve
606: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
607: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
609: Output Parameters:
610: + value - the integer value to return
611: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
613: Level: beginner
615: Notes:
616: If the user does not supply the option at all `value` is NOT changed. Thus
617: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
619: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
621: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
623: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
624: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
625: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
626: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
627: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
628: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
629: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
630: M*/
631: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
633: /*MC
634: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
636: Synopsis:
637: #include <petscoptions.h>
638: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
640: Logically Collective on the communicator passed in `PetscOptionsBegin()`
642: Input Parameters:
643: + opt - option name
644: . text - short string that describes the option
645: . man - manual page with additional information on option
646: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
647: .vb
648: PetscOptionsReal(..., obj->value,&obj->value,...) or
649: value = defaultvalue
650: PetscOptionsReal(..., value,&value,&set);
651: if (set) {
652: .ve
654: Output Parameters:
655: + value - the value to return
656: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
658: Level: beginner
660: Notes:
661: If the user does not supply the option at all `value` is NOT changed. Thus
662: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
664: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
666: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
668: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
669: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
670: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
671: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
672: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
673: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
674: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
675: M*/
676: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
678: /*MC
679: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
681: Synopsis:
682: #include <petscoptions.h>
683: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
685: Logically Collective on the communicator passed in `PetscOptionsBegin()`
687: Input Parameters:
688: + opt - option name
689: . text - short string that describes the option
690: . man - manual page with additional information on option
691: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
692: .vb
693: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
694: .ve
695: or
696: .vb
697: value = defaultvalue
698: PetscOptionsBoundedReal(..., value, &value, &set, ...);
699: if (set) {
700: .ve
701: - bound - the requested value should be greater than or equal to this bound or an error is generated
703: Output Parameters:
704: + value - the real value to return
705: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
707: Level: beginner
709: Notes:
710: If the user does not supply the option at all `value` is NOT changed. Thus
711: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
713: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
715: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
717: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
718: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
719: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
720: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
721: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
722: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
723: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
724: M*/
725: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
727: /*MC
728: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
730: Synopsis:
731: #include <petscoptions.h>
732: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
734: Logically Collective on the communicator passed in `PetscOptionsBegin()`
736: Input Parameters:
737: + opt - option name
738: . text - short string that describes the option
739: . man - manual page with additional information on option
740: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
741: .vb
742: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
743: .ve
744: or
745: .vb
746: value = defaultvalue
747: PetscOptionsRangeReal(..., value, &value, &set, ...);
748: if (set) {
749: .ve
750: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
751: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
753: Output Parameters:
754: + value - the value to return
755: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
757: Level: beginner
759: Notes:
760: If the user does not supply the option at all `value` is NOT changed. Thus
761: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
763: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
765: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
767: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
768: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
769: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
770: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
771: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
772: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
773: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
774: M*/
775: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
777: /*MC
778: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
780: Synopsis:
781: #include <petscoptions.h>
782: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
784: Logically Collective on the communicator passed in `PetscOptionsBegin()`
786: Input Parameters:
787: + opt - option name
788: . text - short string that describes the option
789: . man - manual page with additional information on option
790: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
791: .vb
792: PetscOptionsScalar(..., obj->value,&obj->value,...) or
793: value = defaultvalue
794: PetscOptionsScalar(..., value,&value,&set);
795: if (set) {
796: .ve
798: Output Parameters:
799: + value - the value to return
800: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
802: Level: beginner
804: Notes:
805: If the user does not supply the option at all `value` is NOT changed. Thus
806: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
808: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
810: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
812: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
813: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
814: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
815: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
816: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
817: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
818: `PetscOptionsFList()`, `PetscOptionsEList()`
819: M*/
820: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
822: /*MC
823: PetscOptionsName - Determines if a particular option has been set in the database. This returns true whether the option is a number, string or boolean, even
824: its value is set to false.
826: Synopsis:
827: #include <petscoptions.h>
828: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
830: Logically Collective on the communicator passed in `PetscOptionsBegin()`
832: Input Parameters:
833: + opt - option name
834: . text - short string that describes the option
835: - man - manual page with additional information on option
837: Output Parameter:
838: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
840: Level: beginner
842: Note:
843: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
845: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
846: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
847: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
848: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
849: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
850: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
851: `PetscOptionsFList()`, `PetscOptionsEList()`
852: M*/
853: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
855: /*MC
856: PetscOptionsString - Gets the string value for a particular option in the database.
858: Synopsis:
859: #include <petscoptions.h>
860: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
862: Logically Collective on the communicator passed in `PetscOptionsBegin()`
864: Input Parameters:
865: + opt - option name
866: . text - short string that describes the option
867: . man - manual page with additional information on option
868: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
869: - len - length of the result string including null terminator
871: Output Parameters:
872: + value - the value to return
873: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
875: Level: beginner
877: Notes:
878: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
880: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
882: If the user does not supply the option at all `value` is NOT changed. Thus
883: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
885: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
887: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
888: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
889: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
890: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
891: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
892: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
893: `PetscOptionsFList()`, `PetscOptionsEList()`
894: M*/
895: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
897: /*MC
898: PetscOptionsBool - Determines if a particular option is in the database with a true or false
900: Synopsis:
901: #include <petscoptions.h>
902: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
904: Logically Collective on the communicator passed in `PetscOptionsBegin()`
906: Input Parameters:
907: + opt - option name
908: . text - short string that describes the option
909: . man - manual page with additional information on option
910: - currentvalue - the current value
912: Output Parameters:
913: + flg - `PETSC_TRUE` or `PETSC_FALSE`
914: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
916: Level: beginner
918: Notes:
919: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
920: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
922: If the option is given, but no value is provided, then `flg` and `set` are both given the value `PETSC_TRUE`. That is `-requested_bool`
923: is equivalent to `-requested_bool true`
925: If the user does not supply the option at all `flg` is NOT changed. Thus
926: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
928: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
930: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
931: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
932: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
933: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
934: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
935: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
936: `PetscOptionsFList()`, `PetscOptionsEList()`
937: M*/
938: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
940: /*MC
941: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
942: which at most a single value can be true.
944: Synopsis:
945: #include <petscoptions.h>
946: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
948: Logically Collective on the communicator passed in `PetscOptionsBegin()`
950: Input Parameters:
951: + opt - option name
952: . text - short string that describes the option
953: - man - manual page with additional information on option
955: Output Parameter:
956: . set - whether that option was set or not
958: Level: intermediate
960: Notes:
961: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
963: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
965: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
966: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
967: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
968: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
969: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
970: `PetscOptionsFList()`, `PetscOptionsEList()`
971: M*/
972: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
974: /*MC
975: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
976: which at most a single value can be true.
978: Synopsis:
979: #include <petscoptions.h>
980: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
982: Logically Collective on the communicator passed in `PetscOptionsBegin()`
984: Input Parameters:
985: + opt - option name
986: . text - short string that describes the option
987: - man - manual page with additional information on option
989: Output Parameter:
990: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
992: Level: intermediate
994: Notes:
995: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
997: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
999: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1000: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1001: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1002: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1003: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1004: `PetscOptionsFList()`, `PetscOptionsEList()`
1005: M*/
1006: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1008: /*MC
1009: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1010: which at most a single value can be true.
1012: Synopsis:
1013: #include <petscoptions.h>
1014: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1016: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1018: Input Parameters:
1019: + opt - option name
1020: . text - short string that describes the option
1021: - man - manual page with additional information on option
1023: Output Parameter:
1024: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1026: Level: intermediate
1028: Notes:
1029: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1031: Must follow a `PetscOptionsBoolGroupBegin()`
1033: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1034: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1035: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1036: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1037: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1038: `PetscOptionsFList()`, `PetscOptionsEList()`
1039: M*/
1040: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1042: /*MC
1043: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1045: Synopsis:
1046: #include <petscoptions.h>
1047: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1049: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1051: Input Parameters:
1052: + opt - option name
1053: . ltext - short string that describes the option
1054: . man - manual page with additional information on option
1055: . list - the possible choices
1056: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1057: .vb
1058: PetscOptionsFlist(..., obj->value,value,len,&set);
1059: if (set) {
1060: .ve
1061: - len - the length of the character array value
1063: Output Parameters:
1064: + value - the value to return
1065: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1067: Level: intermediate
1069: Notes:
1070: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1072: If the user does not supply the option at all `value` is NOT changed. Thus
1073: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1075: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1077: See `PetscOptionsEList()` for when the choices are given in a string array
1079: To get a listing of all currently specified options,
1080: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1082: Developer Note:
1083: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1085: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1086: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1087: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1088: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1089: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1090: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1091: M*/
1092: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1094: /*MC
1095: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1097: Synopsis:
1098: #include <petscoptions.h>
1099: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1101: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1103: Input Parameters:
1104: + opt - option name
1105: . ltext - short string that describes the option
1106: . man - manual page with additional information on option
1107: . list - the possible choices (one of these must be selected, anything else is invalid)
1108: . ntext - number of choices
1109: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1110: .vb
1111: PetscOptionsEList(..., obj->value,&value,&set);
1112: .ve if (set) {
1114: Output Parameters:
1115: + value - the index of the value to return
1116: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1118: Level: intermediate
1120: Notes:
1121: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1123: If the user does not supply the option at all `value` is NOT changed. Thus
1124: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1126: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1128: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1129: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1130: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1131: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1132: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1133: `PetscOptionsFList()`, `PetscOptionsEnum()`
1134: M*/
1135: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1137: /*MC
1138: PetscOptionsRealArray - Gets an array of double values for a particular
1139: option in the database. The values must be separated with commas with
1140: no intervening spaces.
1142: Synopsis:
1143: #include <petscoptions.h>
1144: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1146: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1148: Input Parameters:
1149: + opt - the option one is seeking
1150: . text - short string describing option
1151: . man - manual page for option
1152: - n - maximum number of values that value has room for
1154: Output Parameters:
1155: + value - location to copy values
1156: . n - actual number of values found
1157: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1159: Level: beginner
1161: Note:
1162: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1164: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1165: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1166: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1167: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1168: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1169: `PetscOptionsFList()`, `PetscOptionsEList()`
1170: M*/
1171: #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1173: /*MC
1174: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1175: option in the database. The values must be separated with commas with
1176: no intervening spaces.
1178: Synopsis:
1179: #include <petscoptions.h>
1180: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1182: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1184: Input Parameters:
1185: + opt - the option one is seeking
1186: . text - short string describing option
1187: . man - manual page for option
1188: - n - maximum number of values allowed in the value array
1190: Output Parameters:
1191: + value - location to copy values
1192: . n - actual number of values found
1193: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1195: Level: beginner
1197: Note:
1198: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1200: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1201: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1202: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1203: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1204: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1205: `PetscOptionsFList()`, `PetscOptionsEList()`
1206: M*/
1207: #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1209: /*MC
1210: PetscOptionsIntArray - Gets an array of integers for a particular
1211: option in the database.
1213: Synopsis:
1214: #include <petscoptions.h>
1215: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1217: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1219: Input Parameters:
1220: + opt - the option one is seeking
1221: . text - short string describing option
1222: . man - manual page for option
1223: - n - maximum number of values
1225: Output Parameters:
1226: + value - location to copy values
1227: . n - actual number of values found
1228: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1230: Level: beginner
1232: Notes:
1233: The array can be passed as
1234: + a comma separated list - 0,1,2,3,4,5,6,7
1235: . a range (start\-end+1) - 0-8
1236: . a range with given increment (start\-end+1:inc) - 0-7:2
1237: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1239: There must be no intervening spaces between the values.
1241: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1243: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1244: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1245: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1246: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1247: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1248: `PetscOptionsFList()`, `PetscOptionsEList()`
1249: M*/
1250: #define PetscOptionsIntArray(opt, text, man, currentvalue, value, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1252: /*MC
1253: PetscOptionsStringArray - Gets an array of string values for a particular
1254: option in the database. The values must be separated with commas with
1255: no intervening spaces.
1257: Synopsis:
1258: #include <petscoptions.h>
1259: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1261: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1263: Input Parameters:
1264: + opt - the option one is seeking
1265: . text - short string describing option
1266: . man - manual page for option
1267: - nmax - maximum number of strings
1269: Output Parameters:
1270: + value - location to copy strings
1271: . nmax - actual number of strings found
1272: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1274: Level: beginner
1276: Notes:
1277: The user should pass in an array of pointers to char, to hold all the
1278: strings returned by this function.
1280: The user is responsible for deallocating the strings that are
1281: returned.
1283: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1285: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1286: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1287: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1288: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1289: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1290: `PetscOptionsFList()`, `PetscOptionsEList()`
1291: M*/
1292: #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1294: /*MC
1295: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1296: option in the database. The values must be separated with commas with
1297: no intervening spaces.
1299: Synopsis:
1300: #include <petscoptions.h>
1301: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1303: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1305: Input Parameters:
1306: + opt - the option one is seeking
1307: . text - short string describing option
1308: . man - manual page for option
1309: - n - maximum number of values allowed in the value array
1311: Output Parameters:
1312: + value - location to copy values
1313: . n - actual number of values found
1314: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1316: Level: beginner
1318: Notes:
1319: The user should pass in an array of `PetscBool`
1321: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1323: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1324: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1325: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1326: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1327: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1328: `PetscOptionsFList()`, `PetscOptionsEList()`
1329: M*/
1330: #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1332: /*MC
1333: PetscOptionsEnumArray - Gets an array of enum values for a particular
1334: option in the database.
1336: Synopsis:
1337: #include <petscoptions.h>
1338: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1340: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1342: Input Parameters:
1343: + opt - the option one is seeking
1344: . text - short string describing option
1345: . man - manual page for option
1346: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1347: - n - maximum number of values allowed in the value array
1349: Output Parameters:
1350: + value - location to copy values
1351: . n - actual number of values found
1352: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1354: Level: beginner
1356: Notes:
1357: The array must be passed as a comma separated list.
1359: There must be no intervening spaces between the values.
1361: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1363: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1364: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1365: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1366: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1367: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1368: `PetscOptionsFList()`, `PetscOptionsEList()`
1369: M*/
1370: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1372: /*MC
1373: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1375: Prints a deprecation warning, unless an option is supplied to suppress.
1377: Logically Collective
1379: Input Parameters:
1380: + oldname - the old, deprecated option
1381: . newname - the new option, or `NULL` if option is purely removed
1382: . version - a string describing the version of first deprecation, e.g. "3.9"
1383: - info - additional information string, or `NULL`.
1385: Options Database Key:
1386: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1388: Level: developer
1390: Notes:
1391: If `newname` is provided then the options database will automatically check the database for `oldname`.
1393: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1394: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1395: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1397: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1398: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1399: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1400: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1401: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1403: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1404: M*/
1405: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1407: /*MC
1408: PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1410: Prints a deprecation warning, unless an option is supplied to suppress.
1412: Logically Collective
1414: Input Parameters:
1415: + oldname - the old, deprecated option
1416: . newname - the new option, or `NULL` if option is purely removed
1417: . version - a string describing the version of first deprecation, e.g. "3.9"
1418: - info - additional information string, or `NULL`.
1420: Options Database Key:
1421: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1423: Level: developer
1425: Notes:
1426: If `newname` is provided then the options database will automatically check the database for `oldname`.
1428: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1429: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1430: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1432: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1433: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1434: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1435: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1437: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1438: M*/
1439: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1440: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1442: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1443: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1444: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1445: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1446: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1447: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1448: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems *, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1449: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1450: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1451: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1452: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1453: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1454: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1455: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1456: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1457: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1458: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1459: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1460: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1461: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *, const char[], const char[], const char[], const char[]);
1463: PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void);
1465: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems *, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1466: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems *);
1467: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1469: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);