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: /*E
12: PetscOptionSource - Records where a value in the PETSc options database came from, passed to options-database monitors
14: Values:
15: + `PETSC_OPT_CODE` - the option was set by a call from inside source code, for example `PetscOptionsSetValue()`
16: . `PETSC_OPT_COMMAND_LINE` - the option came from the command-line arguments of the program
17: . `PETSC_OPT_FILE` - the option came from an options file processed by `PetscOptionsInsertFile()` (or its YAML counterpart)
18: . `PETSC_OPT_ENVIRONMENT` - the option came from the `PETSC_OPTIONS` (or related) environment variable
19: - `NUM_PETSC_OPT_SOURCE` - sentinel; equals the number of valid option sources
21: Level: developer
23: .seealso: `PetscOptions`, `PetscOptionsMonitorSet()`, `PetscOptionsMonitorDefault()`
24: E*/
25: typedef enum {
26: PETSC_OPT_CODE,
27: PETSC_OPT_COMMAND_LINE,
28: PETSC_OPT_FILE,
29: PETSC_OPT_ENVIRONMENT,
30: NUM_PETSC_OPT_SOURCE
31: } PetscOptionSource;
33: #define PETSC_MAX_OPTION_NAME 512
34: /*S
35: PetscOptions - PETSc's runtime options database object; the holder of all PETSc command-line and configuration options for a session, looked up via `PetscOptionsGet*()`
37: Level: beginner
39: Notes:
40: Most PETSc API calls accept `NULL` for `PetscOptions`, meaning "the default global options database". Use `PetscOptionsCreate()` / `PetscOptionsPush()` to manage non-default databases (e.g. when reading options from a file).
42: Each `PetscObject` may also carry its own non-default options through `PetscObjectSetOptions()`.
44: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscOptionsPush()`, `PetscOptionsPop()`, `PetscOptionsGetBool()`,
45: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, `PetscOptionsGetString()`, `PetscOptionsSetValue()`, `PetscOptionsView()`
46: S*/
47: typedef struct _n_PetscOptions *PetscOptions;
48: PETSC_EXTERN PetscErrorCode PetscOptionsCreate(PetscOptions *);
49: PETSC_EXTERN PetscErrorCode PetscOptionsPush(PetscOptions);
50: PETSC_EXTERN PetscErrorCode PetscOptionsPop(void);
51: PETSC_EXTERN PetscErrorCode PetscOptionsDestroy(PetscOptions *);
52: PETSC_EXTERN PetscErrorCode PetscOptionsCreateDefault(void);
53: PETSC_EXTERN PetscErrorCode PetscOptionsDestroyDefault(void);
55: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
56: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
57: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
58: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool3(PetscOptions, const char[], const char[], PetscBool3 *, PetscBool *);
59: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
60: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
61: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
62: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
63: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
64: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
65: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
67: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
68: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
69: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
70: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
71: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
72: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
74: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
75: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
76: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
77: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
78: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
80: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
81: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
82: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
83: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
84: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
85: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
86: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
88: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
89: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
90: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
91: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
92: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
93: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
94: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, const char *const *);
95: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
96: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
97: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
99: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
100: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
101: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
102: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
103: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
105: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscCtxDestroyFn *);
106: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
108: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
109: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
111: PETSC_EXTERN PetscBool PetscOptionsPublish;
113: /*
114: See manual page for PetscOptionsBegin()
116: PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
117: options being handled with a PetscOptionsBegin/End()
119: */
120: /*E
121: PetscOptionType - Identifies the kind of value held by a `PetscOptionItem` inside a `PetscOptionsBegin()`/`PetscOptionsEnd()` block
123: Values:
124: + `OPTION_INT` - a single `PetscInt`
125: . `OPTION_BOOL` - a single `PetscBool`
126: . `OPTION_REAL` - a single `PetscReal`
127: . `OPTION_FLIST` - a selection from a registered `PetscFunctionList`
128: . `OPTION_STRING` - a single string
129: . `OPTION_REAL_ARRAY` - an array of `PetscReal`
130: . `OPTION_SCALAR_ARRAY` - an array of `PetscScalar`
131: . `OPTION_HEAD` - a section heading inserted with `PetscOptionsHead()`
132: . `OPTION_INT_ARRAY` - an array of `PetscInt`
133: . `OPTION_ELIST` - a selection from an enumerated list of strings
134: . `OPTION_BOOL_ARRAY` - an array of `PetscBool`
135: - `OPTION_STRING_ARRAY` - an array of strings
137: Level: developer
139: .seealso: `PetscOptions`, `PetscOptionItem`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsReal()`
140: E*/
141: typedef enum {
142: OPTION_INT,
143: OPTION_BOOL,
144: OPTION_REAL,
145: OPTION_FLIST,
146: OPTION_STRING,
147: OPTION_REAL_ARRAY,
148: OPTION_SCALAR_ARRAY,
149: OPTION_HEAD,
150: OPTION_INT_ARRAY,
151: OPTION_ELIST,
152: OPTION_BOOL_ARRAY,
153: OPTION_STRING_ARRAY
154: } PetscOptionType;
156: /*S
157: PetscOptionItem - Internal record describing a single option (such as `-ksp_type`) inside a `PetscOptionsBegin()` / `PetscOptionsEnd()` block, holding its option name, help text, default value, and selected value
159: Level: developer
161: .seealso: `PetscOptions`, `PetscOptionItems`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsBool()`
162: S*/
163: typedef struct _n_PetscOptionItem *PetscOptionItem;
164: struct _n_PetscOptionItem {
165: char *option;
166: char *text;
167: void *data; /* used to hold the default value and then any value it is changed to by GUI */
168: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
169: const char *const *list; /* used for available values for PetscOptionsEList() */
170: char nlist; /* number of entries in list */
171: char *man;
172: PetscInt arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
173: PetscBool set; /* the user has changed this value in the GUI */
174: PetscOptionType type;
175: PetscOptionItem next;
176: char *pman;
177: void *edata;
178: };
180: /*S
181: PetscOptionItems - Internal context object representing the set of options being processed inside a `PetscOptionsBegin()` / `PetscOptionsEnd()` block; holds a linked list of `PetscOptionItem`s, the option prefix and the owning `PetscObject`
183: Level: developer
185: .seealso: `PetscOptions`, `PetscOptionItem`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscObjectOptionsBegin()`
186: S*/
187: typedef struct _n_PetscOptionItems *PetscOptionItems;
188: struct _n_PetscOptionItems {
189: PetscInt count;
190: PetscOptionItem next;
191: char *prefix, *pprefix;
192: char *title;
193: MPI_Comm comm;
194: PetscBool printhelp, changedmethod, alreadyprinted;
195: PetscObject object;
196: PetscOptions options;
197: };
199: #if PetscDefined(CLANG_STATIC_ANALYZER)
200: extern PetscOptionItems PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
201: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
202: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
203: PetscErrorCode PetscOptionsEnd(void);
204: #else
205: /*MC
206: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
207: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
208: use `PetscObjectOptionsBegin()` rather than this call.
210: Synopsis:
211: #include <petscoptions.h>
212: PetscErrorCode PetscOptionsBegin(MPI_Comm comm, const char prefix[], const char title[], const char mansec[])
214: Collective
216: Input Parameters:
217: + comm - communicator that shares GUI
218: . prefix - options prefix for all options displayed on window (optional)
219: . title - short descriptive text, for example "Krylov Solver Options"
220: - mansec - section of manual pages for options, for example `KSP` (optional); it also selects this
221: block for `-help mansec`, and a block with no manual section is never selected
223: Level: intermediate
225: Notes:
226: This is a macro that handles its own error checking, it does not return an error code.
228: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
230: One can add subheadings with `PetscOptionsHeadBegin()`.
232: Developer Notes:
233: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
234: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
235: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
236: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
237: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
238: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
239: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
240: default values are printed if -help was given.
241: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
242: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
243: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
244: currently set.
246: Fortran Note:
247: Returns ierr error code as the final argument per PETSc Fortran API
249: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
250: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
251: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
252: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
253: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
254: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
255: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
256: M*/
257: #define PetscOptionsBegin(comm, prefix, mess, sec) \
258: do { \
259: struct _n_PetscOptionItems PetscOptionsObjectBase; \
260: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
261: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
262: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
263: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
265: /*MC
266: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
267: displayed on the same window of a GUI that allows the user to set the options interactively.
269: Synopsis:
270: #include <petscoptions.h>
271: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
273: Collective
275: Input Parameter:
276: . obj - object to set options for
278: Level: intermediate
280: Notes:
281: This is a macro that handles its own error checking, it does not return an error code.
283: Needs to be ended by a call the `PetscOptionsEnd()`
285: Can add subheadings with `PetscOptionsHeadBegin()`
287: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
288: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
289: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
290: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
291: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
292: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
293: `PetscOptionsFList()`, `PetscOptionsEList()`
294: M*/
295: #define PetscObjectOptionsBegin(obj) \
296: do { \
297: struct _n_PetscOptionItems PetscOptionsObjectBase; \
298: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
299: PetscOptionsObject->options = ((PetscObject)(obj))->options; \
300: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
301: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
303: /*MC
304: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
305: displayed on the same window of a GUI that allows the user to set the options interactively.
307: Synopsis:
308: #include <petscoptions.h>
309: PetscErrorCode PetscOptionsEnd(void)
311: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
313: Level: intermediate
315: Notes:
316: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
318: This is a macro that handles its own error checking, it does not return an error code.
320: Fortran Note:
321: Returns ierr error code as the final argument per PETSc Fortran API
323: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
324: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
325: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
326: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
327: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
328: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
329: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
330: M*/
331: #define PetscOptionsEnd() \
332: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
333: } \
334: } \
335: while (0)
336: #endif /* PETSC_CLANG_STATIC_ANALYZER */
338: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[]);
339: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems);
340: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems);
341: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems, const char[]);
343: #if PetscDefined(CLANG_STATIC_ANALYZER)
344: template <typename... T>
345: void PetscOptionsHeadBegin(T...);
346: void PetscOptionsHeadEnd(void);
347: template <typename... T>
348: PetscErrorCode PetscOptionsEnum(T...);
349: template <typename... T>
350: PetscErrorCode PetscOptionsInt(T...);
351: template <typename... T>
352: PetscErrorCode PetscOptionsBoundedInt(T...);
353: template <typename... T>
354: PetscErrorCode PetscOptionsRangeInt(T...);
355: template <typename... T>
356: PetscErrorCode PetscOptionsReal(T...);
357: template <typename... T>
358: PetscErrorCode PetscOptionsScalar(T...);
359: template <typename... T>
360: PetscErrorCode PetscOptionsName(T...);
361: template <typename... T>
362: PetscErrorCode PetscOptionsString(T...);
363: template <typename... T>
364: PetscErrorCode PetscOptionsBool(T...);
365: template <typename... T>
366: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
367: template <typename... T>
368: PetscErrorCode PetscOptionsBoolGroup(T...);
369: template <typename... T>
370: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
371: template <typename... T>
372: PetscErrorCode PetscOptionsFList(T...);
373: template <typename... T>
374: PetscErrorCode PetscOptionsEList(T...);
375: template <typename... T>
376: PetscErrorCode PetscOptionsRealArray(T...);
377: template <typename... T>
378: PetscErrorCode PetscOptionsScalarArray(T...);
379: template <typename... T>
380: PetscErrorCode PetscOptionsIntArray(T...);
381: template <typename... T>
382: PetscErrorCode PetscOptionsStringArray(T...);
383: template <typename... T>
384: PetscErrorCode PetscOptionsBoolArray(T...);
385: template <typename... T>
386: PetscErrorCode PetscOptionsEnumArray(T...);
387: template <typename... T>
388: PetscErrorCode PetscOptionsDeprecated(T...);
389: template <typename... T>
390: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
391: #else
392: /*MC
393: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
394: in `KSPSetFromOptions_GMRES()`.
396: Synopsis:
397: #include <petscoptions.h>
398: PetscErrorCode PetscOptionsHeadBegin(PetscOptionsObject optionsobject, const char head[]) PeNS
400: Logically Collective on the communicator passed in `PetscOptionsBegin()`
402: Input Parameters:
403: + optionsobject - argument from calling function, see `KSPSetFromOptions_GMRES()`
404: - head - the heading text
406: Level: developer
408: Notes:
409: Handles errors directly, hence does not return an error code
411: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
413: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
415: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
416: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
417: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
418: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
419: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
420: `PetscOptionsFList()`, `PetscOptionsEList()`
421: M*/
422: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
423: do { \
424: if ((PetscOptionsObject)->printhelp && (PetscOptionsObject)->count == 1 && !(PetscOptionsObject)->alreadyprinted) PetscCall((*PetscHelpPrintf)((PetscOptionsObject)->comm, " %s\n", head)); \
425: } while (0)
427: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
429: /*MC
430: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
431: See, for example, `KSPSetFromOptions_GMRES()`.
433: Synopsis:
434: #include <petscoptions.h>
435: PetscErrorCode PetscOptionsHeadEnd(void)
437: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
439: Level: intermediate
441: Notes:
442: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
444: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
446: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
447: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
448: from the function.
450: This is only for use with the PETSc options GUI
452: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
453: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
454: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
455: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
456: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
457: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
458: M*/
459: #define PetscOptionsHeadEnd() \
460: do { \
461: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
462: } while (0)
464: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
466: /*MC
467: PetscOptionsEnum - Gets the enum value for a particular option in the database.
469: Synopsis:
470: #include <petscoptions.h>
471: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
473: Logically Collective on the communicator passed in `PetscOptionsBegin()`
475: Input Parameters:
476: + opt - option name
477: . text - short string that describes the option
478: . man - manual page with additional information on option
479: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by `NULL`
480: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
481: .vb
482: PetscOptionsEnum(..., obj->value,&object->value,...) or
483: value = defaultvalue
484: PetscOptionsEnum(..., value,&value,&set);
485: if (set) {
486: .ve
488: Output Parameters:
489: + value - the value to return
490: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
492: Level: beginner
494: Notes:
495: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
497: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
499: If the user does not supply the option at all `value` is NOT changed. Thus
500: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
502: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
504: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
505: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
506: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
507: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
508: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
509: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
510: `PetscOptionsFList()`, `PetscOptionsEList()`
511: M*/
512: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
514: /*MC
515: PetscOptionsInt - Gets the integer value for a particular option in the database.
517: Synopsis:
518: #include <petscoptions.h>
519: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
521: Logically Collective on the communicator passed in `PetscOptionsBegin()`
523: Input Parameters:
524: + opt - option name
525: . text - short string that describes the option
526: . man - manual page with additional information on option
527: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
528: .vb
529: PetscOptionsInt(..., obj->value, &obj->value, ...) or
530: value = defaultvalue
531: PetscOptionsInt(..., value, &value, &set);
532: if (set) {
533: .ve
535: Output Parameters:
536: + value - the integer value to return
537: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
539: Level: beginner
541: Notes:
542: If the user does not supply the option at all `value` is NOT changed. Thus
543: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
545: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
547: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
549: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
550: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
551: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
552: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
553: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
554: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
555: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
556: M*/
557: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
559: /*MC
560: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
562: Synopsis:
563: #include <petscoptions.h>
564: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
566: Logically Collective on the communicator passed in `PetscOptionsBegin()`
568: Input Parameters:
569: + opt - option name
570: . text - short string that describes the option
571: . man - manual page with additional information on option
572: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
573: .vb
574: PetscOptionsInt(..., obj->value, &obj->value, ...) or
575: value = defaultvalue
576: PetscOptionsInt(..., value, &value, &set);
577: if (set) {
578: .ve
580: Output Parameters:
581: + value - the MPI integer value to return
582: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
584: Level: beginner
586: Notes:
587: If the user does not supply the option at all `value` is NOT changed. Thus
588: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
590: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
592: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
594: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
595: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
596: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
597: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
598: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
599: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
600: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
601: M*/
602: #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)
604: /*MC
605: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
607: Synopsis:
608: #include <petscoptions.h>
609: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
611: Logically Collective on the communicator passed in `PetscOptionsBegin()`
613: Input Parameters:
614: + opt - option name
615: . text - short string that describes the option
616: . man - manual page with additional information on option
617: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
618: .vb
619: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
620: .ve
621: or
622: .vb
623: value = defaultvalue
624: PetscOptionsBoundedInt(..., value, &value, &set, ...);
625: if (set) {
626: .ve
627: - bound - the requested value should be greater than or equal to this bound or an error is generated
629: Output Parameters:
630: + value - the integer value to return
631: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
633: Level: beginner
635: Notes:
636: If the user does not supply the option at all `value` is NOT changed. Thus
637: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
639: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
641: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
643: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
644: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
645: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
646: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
647: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
648: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
649: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
650: M*/
651: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
653: /*MC
654: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
656: Synopsis:
657: #include <petscoptions.h>
658: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
660: Logically Collective on the communicator passed in `PetscOptionsBegin()`
662: Input Parameters:
663: + opt - option name
664: . text - short string that describes the option
665: . man - manual page with additional information on option
666: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
667: .vb
668: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
669: .ve
670: or
671: .vb
672: value = defaultvalue
673: PetscOptionsRangeInt(..., value, &value, &set, ...);
674: if (set) {
675: .ve
676: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
677: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
679: Output Parameters:
680: + value - the integer value to return
681: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
683: Level: beginner
685: Notes:
686: If the user does not supply the option at all `value` is NOT changed. Thus
687: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
689: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
691: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
693: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
694: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
695: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
696: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
697: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
698: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
699: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
700: M*/
701: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
703: /*MC
704: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
706: Synopsis:
707: #include <petscoptions.h>
708: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
710: Logically Collective on the communicator passed in `PetscOptionsBegin()`
712: Input Parameters:
713: + opt - option name
714: . text - short string that describes the option
715: . man - manual page with additional information on option
716: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
717: .vb
718: PetscOptionsReal(..., obj->value,&obj->value,...) or
719: value = defaultvalue
720: PetscOptionsReal(..., value,&value,&set);
721: if (set) {
722: .ve
724: Output Parameters:
725: + value - the value to return
726: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
728: Level: beginner
730: Notes:
731: If the user does not supply the option at all `value` is NOT changed. Thus
732: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
734: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
736: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
738: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
739: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
740: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
741: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
742: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
743: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
744: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
745: M*/
746: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
748: /*MC
749: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
751: Synopsis:
752: #include <petscoptions.h>
753: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
755: Logically Collective on the communicator passed in `PetscOptionsBegin()`
757: Input Parameters:
758: + opt - option name
759: . text - short string that describes the option
760: . man - manual page with additional information on option
761: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
762: .vb
763: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
764: .ve
765: or
766: .vb
767: value = defaultvalue
768: PetscOptionsBoundedReal(..., value, &value, &set, ...);
769: if (set) {
770: .ve
771: - bound - the requested value should be greater than or equal to this bound or an error is generated
773: Output Parameters:
774: + value - the real value to return
775: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
777: Level: beginner
779: Notes:
780: If the user does not supply the option at all `value` is NOT changed. Thus
781: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
783: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
785: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
787: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
788: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
789: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
790: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
791: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
792: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
793: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
794: M*/
795: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
797: /*MC
798: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
800: Synopsis:
801: #include <petscoptions.h>
802: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
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
810: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
811: .vb
812: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
813: .ve
814: or
815: .vb
816: value = defaultvalue
817: PetscOptionsRangeReal(..., value, &value, &set, ...);
818: if (set) {
819: .ve
820: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
821: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
823: Output Parameters:
824: + value - the value to return
825: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
827: Level: beginner
829: Notes:
830: If the user does not supply the option at all `value` is NOT changed. Thus
831: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
833: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
835: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
837: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
838: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
839: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
840: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
841: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
842: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
843: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
844: M*/
845: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
847: /*MC
848: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
850: Synopsis:
851: #include <petscoptions.h>
852: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
854: Logically Collective on the communicator passed in `PetscOptionsBegin()`
856: Input Parameters:
857: + opt - option name
858: . text - short string that describes the option
859: . man - manual page with additional information on option
860: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
861: .vb
862: PetscOptionsScalar(..., obj->value,&obj->value,...) or
863: value = defaultvalue
864: PetscOptionsScalar(..., value,&value,&set);
865: if (set) {
866: .ve
868: Output Parameters:
869: + value - the value to return
870: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
872: Level: beginner
874: Notes:
875: If the user does not supply the option at all `value` is NOT changed. Thus
876: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
878: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
880: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
882: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
883: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
884: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
885: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
886: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
887: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
888: `PetscOptionsFList()`, `PetscOptionsEList()`
889: M*/
890: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
892: /*MC
893: 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
894: its value is set to false.
896: Synopsis:
897: #include <petscoptions.h>
898: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
900: Logically Collective on the communicator passed in `PetscOptionsBegin()`
902: Input Parameters:
903: + opt - option name
904: . text - short string that describes the option
905: - man - manual page with additional information on option
907: Output Parameter:
908: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
910: Level: beginner
912: Note:
913: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
915: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
916: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
917: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
918: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
919: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
920: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
921: `PetscOptionsFList()`, `PetscOptionsEList()`
922: M*/
923: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
925: /*MC
926: PetscOptionsString - Gets the string value for a particular option in the database.
928: Synopsis:
929: #include <petscoptions.h>
930: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
932: Logically Collective on the communicator passed in `PetscOptionsBegin()`
934: Input Parameters:
935: + opt - option name
936: . text - short string that describes the option
937: . man - manual page with additional information on option
938: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
939: - len - length of the result string including null terminator
941: Output Parameters:
942: + value - the value to return
943: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
945: Level: beginner
947: Notes:
948: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
950: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
952: If the user does not supply the option at all `value` is NOT changed. Thus
953: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
955: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
957: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
958: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
959: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
960: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
961: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
962: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
963: `PetscOptionsFList()`, `PetscOptionsEList()`
964: M*/
965: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
967: /*MC
968: PetscOptionsBool - Determines if a particular option is in the database with a true or false
970: Synopsis:
971: #include <petscoptions.h>
972: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
974: Logically Collective on the communicator passed in `PetscOptionsBegin()`
976: Input Parameters:
977: + opt - option name
978: . text - short string that describes the option
979: . man - manual page with additional information on option
980: - currentvalue - the current value
982: Output Parameters:
983: + flg - `PETSC_TRUE` or `PETSC_FALSE`
984: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
986: Level: beginner
988: Notes:
989: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
991: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
993: 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`
994: is equivalent to `-requested_bool true`
996: If the user does not supply the option at all `flg` is NOT changed. Thus
997: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
999: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1001: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1002: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1003: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1004: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1005: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1006: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1007: `PetscOptionsFList()`, `PetscOptionsEList()`
1008: M*/
1009: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1011: /*MC
1012: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
1014: Synopsis:
1015: #include <petscoptions.h>
1016: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
1018: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1020: Input Parameters:
1021: + opt - option name
1022: . text - short string that describes the option
1023: . man - manual page with additional information on option
1024: - currentvalue - the current value
1026: Output Parameters:
1027: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
1028: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1030: Level: beginner
1032: Notes:
1033: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_BOOL3_TRUE`
1035: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_BOOL3_FALSE`
1037: The option values UNKNOWN and AUTO (case-insensitive) all translate to `PETSC_BOOL3_UNKNOWN`
1039: 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`
1040: is equivalent to `-requested_bool true`
1042: If the user does not supply the option at all `flg` is NOT changed. Thus
1043: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1045: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1047: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1048: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1049: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1050: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1051: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1052: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1053: `PetscOptionsFList()`, `PetscOptionsEList()`
1054: M*/
1055: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1057: /*MC
1058: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1059: which at most a single value can be true.
1061: Synopsis:
1062: #include <petscoptions.h>
1063: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
1065: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1067: Input Parameters:
1068: + opt - option name
1069: . text - short string that describes the option
1070: - man - manual page with additional information on option
1072: Output Parameter:
1073: . set - whether that option was set or not
1075: Level: intermediate
1077: Notes:
1078: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1080: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1082: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1083: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1084: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1085: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1086: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1087: `PetscOptionsFList()`, `PetscOptionsEList()`
1088: M*/
1089: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1091: /*MC
1092: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1093: which at most a single value can be true.
1095: Synopsis:
1096: #include <petscoptions.h>
1097: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1099: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1101: Input Parameters:
1102: + opt - option name
1103: . text - short string that describes the option
1104: - man - manual page with additional information on option
1106: Output Parameter:
1107: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1109: Level: intermediate
1111: Notes:
1112: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1114: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1116: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1117: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1118: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1119: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1120: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1121: `PetscOptionsFList()`, `PetscOptionsEList()`
1122: M*/
1123: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1125: /*MC
1126: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1127: which at most a single value can be true.
1129: Synopsis:
1130: #include <petscoptions.h>
1131: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1133: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1135: Input Parameters:
1136: + opt - option name
1137: . text - short string that describes the option
1138: - man - manual page with additional information on option
1140: Output Parameter:
1141: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1143: Level: intermediate
1145: Notes:
1146: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1148: Must follow a `PetscOptionsBoolGroupBegin()`
1150: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1151: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1152: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1153: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1154: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1155: `PetscOptionsFList()`, `PetscOptionsEList()`
1156: M*/
1157: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1159: /*MC
1160: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1162: Synopsis:
1163: #include <petscoptions.h>
1164: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1166: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1168: Input Parameters:
1169: + opt - option name
1170: . ltext - short string that describes the option
1171: . man - manual page with additional information on option
1172: . list - the possible choices
1173: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1174: .vb
1175: PetscOptionsFlist(..., obj->value,value,len,&set);
1176: if (set) {
1177: .ve
1178: - len - the length of the character array value
1180: Output Parameters:
1181: + value - the value to return
1182: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1184: Level: intermediate
1186: Notes:
1187: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1189: If the user does not supply the option at all `value` is NOT changed. Thus
1190: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1192: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1194: See `PetscOptionsEList()` for when the choices are given in a string array
1196: To get a listing of all currently specified options,
1197: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1199: Developer Note:
1200: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1202: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1203: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1204: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1205: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1206: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1207: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1208: M*/
1209: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1211: /*MC
1212: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1214: Synopsis:
1215: #include <petscoptions.h>
1216: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1218: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1220: Input Parameters:
1221: + opt - option name
1222: . ltext - short string that describes the option
1223: . man - manual page with additional information on option
1224: . list - the possible choices (one of these must be selected, anything else is invalid)
1225: . ntext - number of choices
1226: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1227: .vb
1228: PetscOptionsEList(..., obj->value,&value,&set);
1229: .ve if (set) {
1231: Output Parameters:
1232: + value - the index of the value to return
1233: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1235: Level: intermediate
1237: Notes:
1238: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1240: If the user does not supply the option at all `value` is NOT changed. Thus
1241: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1243: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1245: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1246: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1247: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1248: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1249: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1250: `PetscOptionsFList()`, `PetscOptionsEnum()`
1251: M*/
1252: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1254: /*MC
1255: PetscOptionsRealArray - Gets an array of double values for a particular
1256: option in the database. The values must be separated with commas with
1257: no intervening spaces.
1259: Synopsis:
1260: #include <petscoptions.h>
1261: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1263: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1265: Input Parameters:
1266: + opt - the option one is seeking
1267: . text - short string describing option
1268: . man - manual page for option
1269: - n - maximum number of values that value has room for
1271: Output Parameters:
1272: + value - location to copy values
1273: . n - actual number of values found
1274: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1276: Level: beginner
1278: Note:
1279: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1281: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1282: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1283: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1284: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1285: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1286: `PetscOptionsFList()`, `PetscOptionsEList()`
1287: M*/
1288: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1290: /*MC
1291: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1292: option in the database. The values must be separated with commas with
1293: no intervening spaces.
1295: Synopsis:
1296: #include <petscoptions.h>
1297: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1299: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1301: Input Parameters:
1302: + opt - the option one is seeking
1303: . text - short string describing option
1304: . man - manual page for option
1305: - n - maximum number of values allowed in the value array
1307: Output Parameters:
1308: + value - location to copy values
1309: . n - actual number of values found
1310: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1312: Level: beginner
1314: Note:
1315: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1317: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1318: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1319: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1320: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1321: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1322: `PetscOptionsFList()`, `PetscOptionsEList()`
1323: M*/
1324: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1326: /*MC
1327: PetscOptionsIntArray - Gets an array of integers for a particular
1328: option in the database.
1330: Synopsis:
1331: #include <petscoptions.h>
1332: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1334: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1336: Input Parameters:
1337: + opt - the option one is seeking
1338: . text - short string describing option
1339: . man - manual page for option
1340: - n - maximum number of values
1342: Output Parameters:
1343: + value - location to copy values
1344: . n - actual number of values found
1345: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1347: Level: beginner
1349: Notes:
1350: The array can be passed as
1351: + a comma separated list - 0,1,2,3,4,5,6,7
1352: . a range (start\-end+1) - 0-8
1353: . a range with given increment (start\-end+1:inc) - 0-7:2
1354: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1356: There must be no intervening spaces between the values.
1358: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1360: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1361: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1362: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1363: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1364: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1365: `PetscOptionsFList()`, `PetscOptionsEList()`
1366: M*/
1367: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1369: /*MC
1370: PetscOptionsStringArray - Gets an array of string values for a particular
1371: option in the database. The values must be separated with commas with
1372: no intervening spaces.
1374: Synopsis:
1375: #include <petscoptions.h>
1376: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1378: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1380: Input Parameters:
1381: + opt - the option one is seeking
1382: . text - short string describing option
1383: . man - manual page for option
1384: - n - maximum number of strings
1386: Output Parameters:
1387: + value - location to copy strings
1388: . n - actual number of strings found
1389: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1391: Level: beginner
1393: Notes:
1394: The user should pass in an array of pointers to char, to hold all the
1395: strings returned by this function.
1397: The user is responsible for deallocating the strings that are
1398: returned.
1400: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1402: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1403: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1404: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1405: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1406: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1407: `PetscOptionsFList()`, `PetscOptionsEList()`
1408: M*/
1409: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1411: /*MC
1412: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1413: option in the database. The values must be separated with commas with
1414: no intervening spaces.
1416: Synopsis:
1417: #include <petscoptions.h>
1418: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1420: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1422: Input Parameters:
1423: + opt - the option one is seeking
1424: . text - short string describing option
1425: . man - manual page for option
1426: - n - maximum number of values allowed in the value array
1428: Output Parameters:
1429: + value - location to copy values
1430: . n - actual number of values found
1431: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1433: Level: beginner
1435: Notes:
1436: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
1438: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
1440: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1442: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1443: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1444: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1445: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1446: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1447: `PetscOptionsFList()`, `PetscOptionsEList()`
1448: M*/
1449: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1451: /*MC
1452: PetscOptionsEnumArray - Gets an array of enum values for a particular
1453: option in the database.
1455: Synopsis:
1456: #include <petscoptions.h>
1457: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1459: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1461: Input Parameters:
1462: + opt - the option one is seeking
1463: . text - short string describing option
1464: . man - manual page for option
1465: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1466: - n - maximum number of values allowed in the value array
1468: Output Parameters:
1469: + value - location to copy values
1470: . n - actual number of values found
1471: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1473: Level: beginner
1475: Notes:
1476: The array must be passed as a comma separated list.
1478: There must be no intervening spaces between the values.
1480: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1482: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1483: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1484: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1485: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1486: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1487: `PetscOptionsFList()`, `PetscOptionsEList()`
1488: M*/
1489: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1491: /*MC
1492: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`.
1493: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1495: Synopsis:
1496: #include <petscoptions.h>
1497: PetscErrorCode PetscOptionsDeprecated(const char oldname[], const char newname[], const char version[], const char info[])
1499: Logically Collective
1501: Input Parameters:
1502: + oldname - the old, deprecated option
1503: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1504: . version - a string describing the version of first deprecation, e.g., `"3.9"`
1505: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1507: Options Database Key:
1508: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1510: Level: developer
1512: Notes:
1513: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1514: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1515: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1517: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecatedNoObject()` otherwise.
1519: Only the process of MPI rank zero that owns the `PetscOptionsItems` argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`) prints the deprecation warning.
1521: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1523: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1525: .seealso: `PetscOptionsDeprecatedNoObject()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1526: M*/
1527: #define PetscOptionsDeprecated(oldname, newname, version, info) PetscOptionsDeprecated_Private(PetscOptionsObject, PETSC_COMM_SELF, NULL, oldname, newname, version, info)
1529: /*MC
1530: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global `PetscOptionsObject`, optionally replacing it with `newname`.
1531: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1533: Synopsis:
1534: #include <petscoptions.h>
1535: PetscErrorCode PetscOptionsDeprecatedNoObject(MPI_Comm comm, const char prefix[], const char oldname[], const char newname[], const char version[], const char info[])
1537: Logically Collective
1539: Input Parameters:
1540: + comm - communicator on which to print deprecated message
1541: . prefix - prefix for the option, generally obtained with `((PetscObject)obj)->prefix`, may be `NULL`
1542: . oldname - the old, deprecated option
1543: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1544: . version - a string describing the version of first deprecation, e.g. `"3.9"`
1545: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1547: Options Database Key:
1548: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1550: Level: developer
1552: Notes:
1553: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecatedNoObject()` occurs before the
1554: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1555: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1557: Not to be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecated()` in that case.
1559: Only the process of MPI rank zero prints the deprecation warning.
1561: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1563: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1565: .seealso: `PetscOptionsDeprecated()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1566: M*/
1567: #define PetscOptionsDeprecatedNoObject(comm, prefix, oldname, newname, version, info) PetscOptionsDeprecated_Private(NULL, comm, prefix, oldname, newname, version, info)
1568: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1570: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1571: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1572: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1573: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1574: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1575: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1576: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1577: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1578: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1579: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1580: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1581: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1582: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1583: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1584: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1585: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1586: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1587: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1588: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1589: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1590: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[], const char[], const char[]);
1592: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1593: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1594: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1596: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);