Actual source code: petscoptions.h
1: /*
2: Routines to determine options set in the options database.
3: */
4: #pragma once
6: #include <petscoptionstypes.h>
7: #include <petscviewertypes.h>
9: /* SUBMANSEC = Sys */
11: PETSC_EXTERN PetscErrorCode PetscOptionsCreate(PetscOptions *);
12: PETSC_EXTERN PetscErrorCode PetscOptionsPush(PetscOptions);
13: PETSC_EXTERN PetscErrorCode PetscOptionsPop(void);
14: PETSC_EXTERN PetscErrorCode PetscOptionsDestroy(PetscOptions *);
15: PETSC_EXTERN PetscErrorCode PetscOptionsCreateDefault(void);
16: PETSC_EXTERN PetscErrorCode PetscOptionsDestroyDefault(void);
18: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
19: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
20: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
21: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool3(PetscOptions, const char[], const char[], PetscBool3 *, PetscBool *);
22: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
23: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
24: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
25: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
26: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
27: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
28: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
30: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
31: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
32: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
33: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
34: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
35: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
37: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
38: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
39: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
40: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
41: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
43: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
44: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
45: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
46: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
47: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
48: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
49: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
51: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
52: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
53: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
54: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
55: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
56: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
57: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, const char *const *);
58: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
59: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
60: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
62: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
63: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
64: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
65: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
66: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
68: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscCtxDestroyFn *);
69: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
71: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
72: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
74: PETSC_EXTERN PetscBool PetscOptionsPublish;
76: struct _n_PetscOptionItem {
77: char *option;
78: char *text;
79: void *data; /* used to hold the default value and then any value it is changed to by GUI */
80: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
81: const char *const *list; /* used for available values for PetscOptionsEList() */
82: char nlist; /* number of entries in list */
83: char *man;
84: PetscInt arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
85: PetscBool set; /* the user has changed this value in the GUI */
86: PetscOptionType type;
87: PetscOptionItem next;
88: char *pman;
89: void *edata;
90: };
92: struct _n_PetscOptionItems {
93: PetscInt count;
94: PetscOptionItem next;
95: char *prefix, *pprefix;
96: char *title;
97: MPI_Comm comm;
98: PetscBool printhelp, changedmethod, alreadyprinted;
99: PetscObject object;
100: PetscOptions options;
101: };
103: #if PetscDefined(CLANG_STATIC_ANALYZER)
104: extern PetscOptionItems PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
105: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
106: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
107: PetscErrorCode PetscOptionsEnd(void);
108: #else
109: /*MC
110: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
111: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
112: use `PetscObjectOptionsBegin()` rather than this call.
114: Synopsis:
115: #include <petscoptions.h>
116: PetscErrorCode PetscOptionsBegin(MPI_Comm comm, const char prefix[], const char title[], const char mansec[])
118: Collective
120: Input Parameters:
121: + comm - communicator that shares GUI
122: . prefix - options prefix for all options displayed on window (optional)
123: . title - short descriptive text, for example "Krylov Solver Options"
124: - mansec - section of manual pages for options, for example `KSP` (optional); it also selects this
125: block for `-help mansec`, and a block with no manual section is never selected
127: Level: intermediate
129: Notes:
130: This is a macro that handles its own error checking, it does not return an error code.
132: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
134: One can add subheadings with `PetscOptionsHeadBegin()`.
136: Developer Notes:
137: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
138: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
139: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
140: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
141: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
142: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
143: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
144: default values are printed if -help was given.
145: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
146: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
147: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
148: currently set.
150: Fortran Note:
151: Returns ierr error code as the final argument per PETSc Fortran API
153: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
154: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
155: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
156: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
157: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
158: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
159: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
160: M*/
161: #define PetscOptionsBegin(comm, prefix, mess, sec) \
162: do { \
163: struct _n_PetscOptionItems PetscOptionsObjectBase; \
164: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
165: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
166: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
167: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
169: /*MC
170: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
171: displayed on the same window of a GUI that allows the user to set the options interactively.
173: Synopsis:
174: #include <petscoptions.h>
175: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
177: Collective
179: Input Parameter:
180: . obj - object to set options for
182: Level: intermediate
184: Notes:
185: This is a macro that handles its own error checking, it does not return an error code.
187: Needs to be ended by a call the `PetscOptionsEnd()`
189: Can add subheadings with `PetscOptionsHeadBegin()`
191: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
192: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
193: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
194: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
195: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
196: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
197: `PetscOptionsFList()`, `PetscOptionsEList()`
198: M*/
199: #define PetscObjectOptionsBegin(obj) \
200: do { \
201: struct _n_PetscOptionItems PetscOptionsObjectBase; \
202: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
203: PetscOptionsObject->options = ((PetscObject)(obj))->options; \
204: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
205: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
207: /*MC
208: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
209: displayed on the same window of a GUI that allows the user to set the options interactively.
211: Synopsis:
212: #include <petscoptions.h>
213: PetscErrorCode PetscOptionsEnd(void)
215: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
217: Level: intermediate
219: Notes:
220: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
222: This is a macro that handles its own error checking, it does not return an error code.
224: Fortran Note:
225: Returns ierr error code as the final argument per PETSc Fortran API
227: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
228: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
229: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
230: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
231: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
232: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
233: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
234: M*/
235: #define PetscOptionsEnd() \
236: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
237: } \
238: } \
239: while (0)
240: #endif /* PETSC_CLANG_STATIC_ANALYZER */
242: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[]);
243: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems);
244: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems);
245: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems, const char[]);
247: #if PetscDefined(CLANG_STATIC_ANALYZER)
248: template <typename... T>
249: void PetscOptionsHeadBegin(T...);
250: void PetscOptionsHeadEnd(void);
251: template <typename... T>
252: PetscErrorCode PetscOptionsEnum(T...);
253: template <typename... T>
254: PetscErrorCode PetscOptionsInt(T...);
255: template <typename... T>
256: PetscErrorCode PetscOptionsBoundedInt(T...);
257: template <typename... T>
258: PetscErrorCode PetscOptionsRangeInt(T...);
259: template <typename... T>
260: PetscErrorCode PetscOptionsReal(T...);
261: template <typename... T>
262: PetscErrorCode PetscOptionsScalar(T...);
263: template <typename... T>
264: PetscErrorCode PetscOptionsName(T...);
265: template <typename... T>
266: PetscErrorCode PetscOptionsString(T...);
267: template <typename... T>
268: PetscErrorCode PetscOptionsBool(T...);
269: template <typename... T>
270: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
271: template <typename... T>
272: PetscErrorCode PetscOptionsBoolGroup(T...);
273: template <typename... T>
274: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
275: template <typename... T>
276: PetscErrorCode PetscOptionsFList(T...);
277: template <typename... T>
278: PetscErrorCode PetscOptionsEList(T...);
279: template <typename... T>
280: PetscErrorCode PetscOptionsRealArray(T...);
281: template <typename... T>
282: PetscErrorCode PetscOptionsScalarArray(T...);
283: template <typename... T>
284: PetscErrorCode PetscOptionsIntArray(T...);
285: template <typename... T>
286: PetscErrorCode PetscOptionsStringArray(T...);
287: template <typename... T>
288: PetscErrorCode PetscOptionsBoolArray(T...);
289: template <typename... T>
290: PetscErrorCode PetscOptionsEnumArray(T...);
291: template <typename... T>
292: PetscErrorCode PetscOptionsDeprecated(T...);
293: template <typename... T>
294: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
295: #else
296: /*MC
297: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
298: in `KSPSetFromOptions_GMRES()`.
300: Synopsis:
301: #include <petscoptions.h>
302: PetscErrorCode PetscOptionsHeadBegin(PetscOptionsObject optionsobject, const char head[]) PeNS
304: Logically Collective on the communicator passed in `PetscOptionsBegin()`
306: Input Parameters:
307: + optionsobject - argument from calling function, see `KSPSetFromOptions_GMRES()`
308: - head - the heading text
310: Level: developer
312: Notes:
313: Handles errors directly, hence does not return an error code
315: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
317: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
319: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
320: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
321: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
322: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
323: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
324: `PetscOptionsFList()`, `PetscOptionsEList()`
325: M*/
326: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
327: do { \
328: if ((PetscOptionsObject)->printhelp && (PetscOptionsObject)->count == 1 && !(PetscOptionsObject)->alreadyprinted) PetscCall((*PetscHelpPrintf)((PetscOptionsObject)->comm, " %s\n", head)); \
329: } while (0)
331: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
333: /*MC
334: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
335: See, for example, `KSPSetFromOptions_GMRES()`.
337: Synopsis:
338: #include <petscoptions.h>
339: PetscErrorCode PetscOptionsHeadEnd(void)
341: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
343: Level: intermediate
345: Notes:
346: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
348: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
350: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
351: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
352: from the function.
354: This is only for use with the PETSc options GUI
356: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
357: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
358: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
359: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
360: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
361: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
362: M*/
363: #define PetscOptionsHeadEnd() \
364: do { \
365: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
366: } while (0)
368: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
370: /*MC
371: PetscOptionsEnum - Gets the enum value for a particular option in the database.
373: Synopsis:
374: #include <petscoptions.h>
375: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
377: Logically Collective on the communicator passed in `PetscOptionsBegin()`
379: Input Parameters:
380: + opt - option name
381: . text - short string that describes the option
382: . man - manual page with additional information on option
383: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by `NULL`
384: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
385: .vb
386: PetscOptionsEnum(..., obj->value,&object->value,...) or
387: value = defaultvalue
388: PetscOptionsEnum(..., value,&value,&set);
389: if (set) {
390: .ve
392: Output Parameters:
393: + value - the value to return
394: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
396: Level: beginner
398: Notes:
399: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
401: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
403: If the user does not supply the option at all `value` is NOT changed. Thus
404: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
406: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
408: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
409: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
410: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
411: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
412: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
413: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
414: `PetscOptionsFList()`, `PetscOptionsEList()`
415: M*/
416: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
418: /*MC
419: PetscOptionsInt - Gets the integer value for a particular option in the database.
421: Synopsis:
422: #include <petscoptions.h>
423: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
425: Logically Collective on the communicator passed in `PetscOptionsBegin()`
427: Input Parameters:
428: + opt - option name
429: . text - short string that describes the option
430: . man - manual page with additional information on option
431: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
432: .vb
433: PetscOptionsInt(..., obj->value, &obj->value, ...) or
434: value = defaultvalue
435: PetscOptionsInt(..., value, &value, &set);
436: if (set) {
437: .ve
439: Output Parameters:
440: + value - the integer value to return
441: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
443: Level: beginner
445: Notes:
446: If the user does not supply the option at all `value` is NOT changed. Thus
447: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
449: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
451: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
453: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
454: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
455: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
456: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
457: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
458: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
459: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
460: M*/
461: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
463: /*MC
464: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
466: Synopsis:
467: #include <petscoptions.h>
468: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
470: Logically Collective on the communicator passed in `PetscOptionsBegin()`
472: Input Parameters:
473: + opt - option name
474: . text - short string that describes the option
475: . man - manual page with additional information on option
476: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
477: .vb
478: PetscOptionsInt(..., obj->value, &obj->value, ...) or
479: value = defaultvalue
480: PetscOptionsInt(..., value, &value, &set);
481: if (set) {
482: .ve
484: Output Parameters:
485: + value - the MPI integer value to return
486: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
488: Level: beginner
490: Notes:
491: If the user does not supply the option at all `value` is NOT changed. Thus
492: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
494: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
496: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
498: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
499: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
500: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
501: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
502: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
503: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
504: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
505: M*/
506: #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)
508: /*MC
509: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
511: Synopsis:
512: #include <petscoptions.h>
513: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
515: Logically Collective on the communicator passed in `PetscOptionsBegin()`
517: Input Parameters:
518: + opt - option name
519: . text - short string that describes the option
520: . man - manual page with additional information on option
521: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
522: .vb
523: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
524: .ve
525: or
526: .vb
527: value = defaultvalue
528: PetscOptionsBoundedInt(..., value, &value, &set, ...);
529: if (set) {
530: .ve
531: - bound - the requested value should be greater than or equal to this bound or an error is generated
533: Output Parameters:
534: + value - the integer value to return
535: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
537: Level: beginner
539: Notes:
540: If the user does not supply the option at all `value` is NOT changed. Thus
541: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
543: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
545: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
547: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
548: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
549: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
550: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
551: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
552: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
553: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
554: M*/
555: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
557: /*MC
558: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
560: Synopsis:
561: #include <petscoptions.h>
562: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
564: Logically Collective on the communicator passed in `PetscOptionsBegin()`
566: Input Parameters:
567: + opt - option name
568: . text - short string that describes the option
569: . man - manual page with additional information on option
570: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
571: .vb
572: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
573: .ve
574: or
575: .vb
576: value = defaultvalue
577: PetscOptionsRangeInt(..., value, &value, &set, ...);
578: if (set) {
579: .ve
580: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
581: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
583: Output Parameters:
584: + value - the integer value to return
585: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
587: Level: beginner
589: Notes:
590: If the user does not supply the option at all `value` is NOT changed. Thus
591: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
593: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
595: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
597: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
598: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
599: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
600: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
601: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
602: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
603: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
604: M*/
605: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
607: /*MC
608: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
610: Synopsis:
611: #include <petscoptions.h>
612: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
614: Logically Collective on the communicator passed in `PetscOptionsBegin()`
616: Input Parameters:
617: + opt - option name
618: . text - short string that describes the option
619: . man - manual page with additional information on option
620: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
621: .vb
622: PetscOptionsReal(..., obj->value,&obj->value,...) or
623: value = defaultvalue
624: PetscOptionsReal(..., value,&value,&set);
625: if (set) {
626: .ve
628: Output Parameters:
629: + value - the value to return
630: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
632: Level: beginner
634: Notes:
635: If the user does not supply the option at all `value` is NOT changed. Thus
636: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
638: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
640: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
642: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
643: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
644: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
645: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
646: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
647: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
648: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
649: M*/
650: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
652: /*MC
653: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
655: Synopsis:
656: #include <petscoptions.h>
657: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
659: Logically Collective on the communicator passed in `PetscOptionsBegin()`
661: Input Parameters:
662: + opt - option name
663: . text - short string that describes the option
664: . man - manual page with additional information on option
665: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
666: .vb
667: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
668: .ve
669: or
670: .vb
671: value = defaultvalue
672: PetscOptionsBoundedReal(..., value, &value, &set, ...);
673: if (set) {
674: .ve
675: - bound - the requested value should be greater than or equal to this bound or an error is generated
677: Output Parameters:
678: + value - the real value to return
679: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
681: Level: beginner
683: Notes:
684: If the user does not supply the option at all `value` is NOT changed. Thus
685: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
687: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
689: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
691: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
692: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
693: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
694: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
695: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
696: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
697: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
698: M*/
699: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
701: /*MC
702: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
704: Synopsis:
705: #include <petscoptions.h>
706: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
708: Logically Collective on the communicator passed in `PetscOptionsBegin()`
710: Input Parameters:
711: + opt - option name
712: . text - short string that describes the option
713: . man - manual page with additional information on option
714: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
715: .vb
716: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
717: .ve
718: or
719: .vb
720: value = defaultvalue
721: PetscOptionsRangeReal(..., value, &value, &set, ...);
722: if (set) {
723: .ve
724: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
725: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
727: Output Parameters:
728: + value - the value to return
729: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
731: Level: beginner
733: Notes:
734: If the user does not supply the option at all `value` is NOT changed. Thus
735: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
737: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
739: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
741: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
742: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
743: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
744: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
745: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
746: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
747: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
748: M*/
749: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
751: /*MC
752: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
754: Synopsis:
755: #include <petscoptions.h>
756: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
758: Logically Collective on the communicator passed in `PetscOptionsBegin()`
760: Input Parameters:
761: + opt - option name
762: . text - short string that describes the option
763: . man - manual page with additional information on option
764: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
765: .vb
766: PetscOptionsScalar(..., obj->value,&obj->value,...) or
767: value = defaultvalue
768: PetscOptionsScalar(..., value,&value,&set);
769: if (set) {
770: .ve
772: Output Parameters:
773: + value - the value to return
774: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
776: Level: beginner
778: Notes:
779: If the user does not supply the option at all `value` is NOT changed. Thus
780: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
782: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
784: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
786: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
787: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
788: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
789: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
790: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
791: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
792: `PetscOptionsFList()`, `PetscOptionsEList()`
793: M*/
794: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
796: /*MC
797: 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
798: its value is set to false.
800: Synopsis:
801: #include <petscoptions.h>
802: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
804: Logically Collective on the communicator passed in `PetscOptionsBegin()`
806: Input Parameters:
807: + opt - option name
808: . text - short string that describes the option
809: - man - manual page with additional information on option
811: Output Parameter:
812: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
814: Level: beginner
816: Note:
817: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
819: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
820: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
821: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
822: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
823: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
824: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
825: `PetscOptionsFList()`, `PetscOptionsEList()`
826: M*/
827: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
829: /*MC
830: PetscOptionsString - Gets the string value for a particular option in the database.
832: Synopsis:
833: #include <petscoptions.h>
834: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
836: Logically Collective on the communicator passed in `PetscOptionsBegin()`
838: Input Parameters:
839: + opt - option name
840: . text - short string that describes the option
841: . man - manual page with additional information on option
842: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
843: - len - length of the result string including null terminator
845: Output Parameters:
846: + value - the value to return
847: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
849: Level: beginner
851: Notes:
852: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
854: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
856: If the user does not supply the option at all `value` is NOT changed. Thus
857: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
859: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
861: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
862: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
863: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
864: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
865: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
866: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
867: `PetscOptionsFList()`, `PetscOptionsEList()`
868: M*/
869: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
871: /*MC
872: PetscOptionsBool - Determines if a particular option is in the database with a true or false
874: Synopsis:
875: #include <petscoptions.h>
876: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
878: Logically Collective on the communicator passed in `PetscOptionsBegin()`
880: Input Parameters:
881: + opt - option name
882: . text - short string that describes the option
883: . man - manual page with additional information on option
884: - currentvalue - the current value
886: Output Parameters:
887: + flg - `PETSC_TRUE` or `PETSC_FALSE`
888: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
890: Level: beginner
892: Notes:
893: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
895: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
897: 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`
898: is equivalent to `-requested_bool true`
900: If the user does not supply the option at all `flg` is NOT changed. Thus
901: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
903: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
905: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
906: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
907: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
908: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
909: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
910: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
911: `PetscOptionsFList()`, `PetscOptionsEList()`
912: M*/
913: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
915: /*MC
916: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
918: Synopsis:
919: #include <petscoptions.h>
920: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
922: Logically Collective on the communicator passed in `PetscOptionsBegin()`
924: Input Parameters:
925: + opt - option name
926: . text - short string that describes the option
927: . man - manual page with additional information on option
928: - currentvalue - the current value
930: Output Parameters:
931: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
932: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
934: Level: beginner
936: Notes:
937: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_BOOL3_TRUE`
939: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_BOOL3_FALSE`
941: The option values UNKNOWN and AUTO (case-insensitive) all translate to `PETSC_BOOL3_UNKNOWN`
943: If the option is given, but no value is provided, then `flg` and `set` are both given the value `PETSC_BOOL3_TRUE`. That is `-requested_bool`
944: is equivalent to `-requested_bool true`
946: If the user does not supply the option at all `flg` is NOT changed. Thus
947: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
949: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
951: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
952: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
953: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
954: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
955: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
956: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
957: `PetscOptionsFList()`, `PetscOptionsEList()`
958: M*/
959: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
961: /*MC
962: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
963: which at most a single value can be true.
965: Synopsis:
966: #include <petscoptions.h>
967: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
969: Logically Collective on the communicator passed in `PetscOptionsBegin()`
971: Input Parameters:
972: + opt - option name
973: . text - short string that describes the option
974: - man - manual page with additional information on option
976: Output Parameter:
977: . set - whether that option was set or not
979: Level: intermediate
981: Notes:
982: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
984: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
986: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
987: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
988: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
989: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
990: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
991: `PetscOptionsFList()`, `PetscOptionsEList()`
992: M*/
993: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
995: /*MC
996: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
997: which at most a single value can be true.
999: Synopsis:
1000: #include <petscoptions.h>
1001: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1003: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1005: Input Parameters:
1006: + opt - option name
1007: . text - short string that describes the option
1008: - man - manual page with additional information on option
1010: Output Parameter:
1011: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1013: Level: intermediate
1015: Notes:
1016: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1018: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1020: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1021: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1022: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1023: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1024: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1025: `PetscOptionsFList()`, `PetscOptionsEList()`
1026: M*/
1027: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1029: /*MC
1030: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1031: which at most a single value can be true.
1033: Synopsis:
1034: #include <petscoptions.h>
1035: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1037: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1039: Input Parameters:
1040: + opt - option name
1041: . text - short string that describes the option
1042: - man - manual page with additional information on option
1044: Output Parameter:
1045: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1047: Level: intermediate
1049: Notes:
1050: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1052: Must follow a `PetscOptionsBoolGroupBegin()`
1054: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1055: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1056: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1057: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1058: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1059: `PetscOptionsFList()`, `PetscOptionsEList()`
1060: M*/
1061: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1063: /*MC
1064: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1066: Synopsis:
1067: #include <petscoptions.h>
1068: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1070: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1072: Input Parameters:
1073: + opt - option name
1074: . ltext - short string that describes the option
1075: . man - manual page with additional information on option
1076: . list - the possible choices
1077: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1078: .vb
1079: PetscOptionsFlist(..., obj->value,value,len,&set);
1080: if (set) {
1081: .ve
1082: - len - the length of the character array value
1084: Output Parameters:
1085: + value - the value to return
1086: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1088: Level: intermediate
1090: Notes:
1091: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1093: If the user does not supply the option at all `value` is NOT changed. Thus
1094: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1096: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1098: See `PetscOptionsEList()` for when the choices are given in a string array
1100: To get a listing of all currently specified options,
1101: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1103: Developer Note:
1104: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1106: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1107: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1108: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1109: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1110: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1111: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1112: M*/
1113: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1115: /*MC
1116: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1118: Synopsis:
1119: #include <petscoptions.h>
1120: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1122: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1124: Input Parameters:
1125: + opt - option name
1126: . ltext - short string that describes the option
1127: . man - manual page with additional information on option
1128: . list - the possible choices (one of these must be selected, anything else is invalid)
1129: . ntext - number of choices
1130: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1131: .vb
1132: PetscOptionsEList(..., obj->value,&value,&set);
1133: .ve if (set) {
1135: Output Parameters:
1136: + value - the index of the value to return
1137: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1139: Level: intermediate
1141: Notes:
1142: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1144: If the user does not supply the option at all `value` is NOT changed. Thus
1145: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1147: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1149: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1150: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1151: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1152: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1153: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1154: `PetscOptionsFList()`, `PetscOptionsEnum()`
1155: M*/
1156: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1158: /*MC
1159: PetscOptionsRealArray - Gets an array of double values for a particular
1160: option in the database. The values must be separated with commas with
1161: no intervening spaces.
1163: Synopsis:
1164: #include <petscoptions.h>
1165: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1167: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1169: Input Parameters:
1170: + opt - the option one is seeking
1171: . text - short string describing option
1172: . man - manual page for option
1173: - n - maximum number of values that value has room for
1175: Output Parameters:
1176: + value - location to copy values
1177: . n - actual number of values found
1178: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1180: Level: beginner
1182: Note:
1183: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1185: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1186: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1187: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1188: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1189: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1190: `PetscOptionsFList()`, `PetscOptionsEList()`
1191: M*/
1192: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1194: /*MC
1195: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1196: option in the database. The values must be separated with commas with
1197: no intervening spaces.
1199: Synopsis:
1200: #include <petscoptions.h>
1201: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1203: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1205: Input Parameters:
1206: + opt - the option one is seeking
1207: . text - short string describing option
1208: . man - manual page for option
1209: - n - maximum number of values allowed in the value array
1211: Output Parameters:
1212: + value - location to copy values
1213: . n - actual number of values found
1214: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1216: Level: beginner
1218: Note:
1219: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1221: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1222: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1223: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1224: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1225: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1226: `PetscOptionsFList()`, `PetscOptionsEList()`
1227: M*/
1228: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1230: /*MC
1231: PetscOptionsIntArray - Gets an array of integers for a particular
1232: option in the database.
1234: Synopsis:
1235: #include <petscoptions.h>
1236: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1238: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1240: Input Parameters:
1241: + opt - the option one is seeking
1242: . text - short string describing option
1243: . man - manual page for option
1244: - n - maximum number of values
1246: Output Parameters:
1247: + value - location to copy values
1248: . n - actual number of values found
1249: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1251: Level: beginner
1253: Notes:
1254: The array can be passed as
1255: + a comma separated list - 0,1,2,3,4,5,6,7
1256: . a range (start\-end+1) - 0-8
1257: . a range with given increment (start\-end+1:inc) - 0-7:2
1258: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1260: There must be no intervening spaces between the values.
1262: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1264: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1265: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1266: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1267: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1268: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1269: `PetscOptionsFList()`, `PetscOptionsEList()`
1270: M*/
1271: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1273: /*MC
1274: PetscOptionsStringArray - Gets an array of string values for a particular
1275: option in the database. The values must be separated with commas with
1276: no intervening spaces.
1278: Synopsis:
1279: #include <petscoptions.h>
1280: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1282: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1284: Input Parameters:
1285: + opt - the option one is seeking
1286: . text - short string describing option
1287: . man - manual page for option
1288: - n - maximum number of strings
1290: Output Parameters:
1291: + value - location to copy strings
1292: . n - actual number of strings found
1293: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1295: Level: beginner
1297: Notes:
1298: The user should pass in an array of pointers to char, to hold all the
1299: strings returned by this function.
1301: The user is responsible for deallocating the strings that are
1302: returned.
1304: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1306: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1307: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1308: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1309: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1310: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1311: `PetscOptionsFList()`, `PetscOptionsEList()`
1312: M*/
1313: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1315: /*MC
1316: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1317: option in the database. The values must be separated with commas with
1318: no intervening spaces.
1320: Synopsis:
1321: #include <petscoptions.h>
1322: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1324: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1326: Input Parameters:
1327: + opt - the option one is seeking
1328: . text - short string describing option
1329: . man - manual page for option
1330: - n - maximum number of values allowed in the value array
1332: Output Parameters:
1333: + value - location to copy values
1334: . n - actual number of values found
1335: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1337: Level: beginner
1339: Notes:
1340: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
1342: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
1344: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1346: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1347: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1348: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1349: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1350: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1351: `PetscOptionsFList()`, `PetscOptionsEList()`
1352: M*/
1353: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1355: /*MC
1356: PetscOptionsEnumArray - Gets an array of enum values for a particular
1357: option in the database.
1359: Synopsis:
1360: #include <petscoptions.h>
1361: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1363: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1365: Input Parameters:
1366: + opt - the option one is seeking
1367: . text - short string describing option
1368: . man - manual page for option
1369: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1370: - n - maximum number of values allowed in the value array
1372: Output Parameters:
1373: + value - location to copy values
1374: . n - actual number of values found
1375: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1377: Level: beginner
1379: Notes:
1380: The array must be passed as a comma separated list.
1382: There must be no intervening spaces between the values.
1384: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1386: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1387: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1388: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1389: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1390: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1391: `PetscOptionsFList()`, `PetscOptionsEList()`
1392: M*/
1393: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1395: /*MC
1396: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`.
1397: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1399: Synopsis:
1400: #include <petscoptions.h>
1401: PetscErrorCode PetscOptionsDeprecated(const char oldname[], const char newname[], const char version[], const char info[])
1403: Logically Collective
1405: Input Parameters:
1406: + oldname - the old, deprecated option
1407: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1408: . version - a string describing the version of first deprecation, e.g., `"3.9"`
1409: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1411: Options Database Key:
1412: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1414: Level: developer
1416: Notes:
1417: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1418: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1419: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1421: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecatedNoObject()` otherwise.
1423: Only the process of MPI rank zero that owns the `PetscOptionsItems` argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`) prints the deprecation warning.
1425: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1427: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1429: .seealso: `PetscOptionsDeprecatedNoObject()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1430: M*/
1431: #define PetscOptionsDeprecated(oldname, newname, version, info) PetscOptionsDeprecated_Private(PetscOptionsObject, PETSC_COMM_SELF, NULL, oldname, newname, version, info)
1433: /*MC
1434: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global `PetscOptionsObject`, optionally replacing it with `newname`.
1435: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1437: Synopsis:
1438: #include <petscoptions.h>
1439: PetscErrorCode PetscOptionsDeprecatedNoObject(MPI_Comm comm, const char prefix[], const char oldname[], const char newname[], const char version[], const char info[])
1441: Logically Collective
1443: Input Parameters:
1444: + comm - communicator on which to print deprecated message
1445: . prefix - prefix for the option, generally obtained with `((PetscObject)obj)->prefix`, may be `NULL`
1446: . oldname - the old, deprecated option
1447: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1448: . version - a string describing the version of first deprecation, e.g. `"3.9"`
1449: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1451: Options Database Key:
1452: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1454: Level: developer
1456: Notes:
1457: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecatedNoObject()` occurs before the
1458: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1459: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1461: Not to be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecated()` in that case.
1463: Only the process of MPI rank zero prints the deprecation warning.
1465: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1467: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1469: .seealso: `PetscOptionsDeprecated()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1470: M*/
1471: #define PetscOptionsDeprecatedNoObject(comm, prefix, oldname, newname, version, info) PetscOptionsDeprecated_Private(NULL, comm, prefix, oldname, newname, version, info)
1472: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1474: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1475: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1476: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1477: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1478: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1479: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1480: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1481: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1482: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1483: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1484: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1485: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1486: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1487: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1488: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1489: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1490: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1491: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1492: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1493: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1494: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[], const char[], const char[]);
1496: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1497: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1498: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1500: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);