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)
222: Level: intermediate
224: Notes:
225: This is a macro that handles its own error checking, it does not return an error code.
227: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
229: One can add subheadings with `PetscOptionsHeadBegin()`.
231: Developer Notes:
232: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
233: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
234: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
235: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
236: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
237: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
238: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
239: default values are printed if -help was given.
240: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
241: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
242: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
243: currently set.
245: Fortran Note:
246: Returns ierr error code as the final argument per PETSc Fortran API
248: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
249: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
250: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
251: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
252: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
253: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
254: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
255: M*/
256: #define PetscOptionsBegin(comm, prefix, mess, sec) \
257: do { \
258: struct _n_PetscOptionItems PetscOptionsObjectBase; \
259: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
260: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
261: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
262: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
264: /*MC
265: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
266: displayed on the same window of a GUI that allows the user to set the options interactively.
268: Synopsis:
269: #include <petscoptions.h>
270: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
272: Collective
274: Input Parameter:
275: . obj - object to set options for
277: Level: intermediate
279: Notes:
280: This is a macro that handles its own error checking, it does not return an error code.
282: Needs to be ended by a call the `PetscOptionsEnd()`
284: Can add subheadings with `PetscOptionsHeadBegin()`
286: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
287: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
288: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
289: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
290: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
291: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
292: `PetscOptionsFList()`, `PetscOptionsEList()`
293: M*/
294: #define PetscObjectOptionsBegin(obj) \
295: do { \
296: struct _n_PetscOptionItems PetscOptionsObjectBase; \
297: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
298: PetscOptionsObject->options = ((PetscObject)obj)->options; \
299: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
300: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
302: /*MC
303: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
304: displayed on the same window of a GUI that allows the user to set the options interactively.
306: Synopsis:
307: #include <petscoptions.h>
308: PetscErrorCode PetscOptionsEnd(void)
310: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
312: Level: intermediate
314: Notes:
315: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
317: This is a macro that handles its own error checking, it does not return an error code.
319: Fortran Note:
320: Returns ierr error code as the final argument per PETSc Fortran API
322: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
323: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
324: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
325: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
326: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
327: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
328: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
329: M*/
330: #define PetscOptionsEnd() \
331: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
332: } \
333: } \
334: while (0)
335: #endif /* PETSC_CLANG_STATIC_ANALYZER */
337: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[]);
338: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems);
339: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems);
340: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems, const char[]);
342: #if PetscDefined(CLANG_STATIC_ANALYZER)
343: template <typename... T>
344: void PetscOptionsHeadBegin(T...);
345: void PetscOptionsHeadEnd(void);
346: template <typename... T>
347: PetscErrorCode PetscOptionsEnum(T...);
348: template <typename... T>
349: PetscErrorCode PetscOptionsInt(T...);
350: template <typename... T>
351: PetscErrorCode PetscOptionsBoundedInt(T...);
352: template <typename... T>
353: PetscErrorCode PetscOptionsRangeInt(T...);
354: template <typename... T>
355: PetscErrorCode PetscOptionsReal(T...);
356: template <typename... T>
357: PetscErrorCode PetscOptionsScalar(T...);
358: template <typename... T>
359: PetscErrorCode PetscOptionsName(T...);
360: template <typename... T>
361: PetscErrorCode PetscOptionsString(T...);
362: template <typename... T>
363: PetscErrorCode PetscOptionsBool(T...);
364: template <typename... T>
365: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
366: template <typename... T>
367: PetscErrorCode PetscOptionsBoolGroup(T...);
368: template <typename... T>
369: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
370: template <typename... T>
371: PetscErrorCode PetscOptionsFList(T...);
372: template <typename... T>
373: PetscErrorCode PetscOptionsEList(T...);
374: template <typename... T>
375: PetscErrorCode PetscOptionsRealArray(T...);
376: template <typename... T>
377: PetscErrorCode PetscOptionsScalarArray(T...);
378: template <typename... T>
379: PetscErrorCode PetscOptionsIntArray(T...);
380: template <typename... T>
381: PetscErrorCode PetscOptionsStringArray(T...);
382: template <typename... T>
383: PetscErrorCode PetscOptionsBoolArray(T...);
384: template <typename... T>
385: PetscErrorCode PetscOptionsEnumArray(T...);
386: template <typename... T>
387: PetscErrorCode PetscOptionsDeprecated(T...);
388: template <typename... T>
389: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
390: #else
391: /*MC
392: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
393: in `KSPSetFromOptions_GMRES()`.
395: Synopsis:
396: #include <petscoptions.h>
397: PetscErrorCode PetscOptionsHeadBegin(PetscOptionsObject optionsobject, const char head[]) PeNS
399: Logically Collective on the communicator passed in `PetscOptionsBegin()`
401: Input Parameters:
402: + optionsobject - argument from calling function, see `KSPSetFromOptions_GMRES()`
403: - head - the heading text
405: Level: developer
407: Notes:
408: Handles errors directly, hence does not return an error code
410: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
412: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
414: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
415: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
416: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
417: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
418: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
419: `PetscOptionsFList()`, `PetscOptionsEList()`
420: M*/
421: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
422: do { \
423: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
424: } while (0)
426: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
428: /*MC
429: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
430: See, for example, `KSPSetFromOptions_GMRES()`.
432: Synopsis:
433: #include <petscoptions.h>
434: PetscErrorCode PetscOptionsHeadEnd(void)
436: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
438: Level: intermediate
440: Notes:
441: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
443: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
445: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
446: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
447: from the function.
449: This is only for use with the PETSc options GUI
451: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
452: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
453: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
454: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
455: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
456: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
457: M*/
458: #define PetscOptionsHeadEnd() \
459: do { \
460: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
461: } while (0)
463: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
465: /*MC
466: PetscOptionsEnum - Gets the enum value for a particular option in the database.
468: Synopsis:
469: #include <petscoptions.h>
470: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
472: Logically Collective on the communicator passed in `PetscOptionsBegin()`
474: Input Parameters:
475: + opt - option name
476: . text - short string that describes the option
477: . man - manual page with additional information on option
478: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by `NULL`
479: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
480: .vb
481: PetscOptionsEnum(..., obj->value,&object->value,...) or
482: value = defaultvalue
483: PetscOptionsEnum(..., value,&value,&set);
484: if (set) {
485: .ve
487: Output Parameters:
488: + value - the value to return
489: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
491: Level: beginner
493: Notes:
494: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
496: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
498: If the user does not supply the option at all `value` is NOT changed. Thus
499: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
501: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
503: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
504: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
505: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
506: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
507: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
508: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
509: `PetscOptionsFList()`, `PetscOptionsEList()`
510: M*/
511: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
513: /*MC
514: PetscOptionsInt - Gets the integer value for a particular option in the database.
516: Synopsis:
517: #include <petscoptions.h>
518: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
520: Logically Collective on the communicator passed in `PetscOptionsBegin()`
522: Input Parameters:
523: + opt - option name
524: . text - short string that describes the option
525: . man - manual page with additional information on option
526: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
527: .vb
528: PetscOptionsInt(..., obj->value, &obj->value, ...) or
529: value = defaultvalue
530: PetscOptionsInt(..., value, &value, &set);
531: if (set) {
532: .ve
534: Output Parameters:
535: + value - the integer value to return
536: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
538: Level: beginner
540: Notes:
541: If the user does not supply the option at all `value` is NOT changed. Thus
542: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
544: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
546: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
548: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
549: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
550: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
551: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
552: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
553: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
554: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
555: M*/
556: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
558: /*MC
559: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
561: Synopsis:
562: #include <petscoptions.h>
563: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
565: Logically Collective on the communicator passed in `PetscOptionsBegin()`
567: Input Parameters:
568: + opt - option name
569: . text - short string that describes the option
570: . man - manual page with additional information on option
571: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
572: .vb
573: PetscOptionsInt(..., obj->value, &obj->value, ...) or
574: value = defaultvalue
575: PetscOptionsInt(..., value, &value, &set);
576: if (set) {
577: .ve
579: Output Parameters:
580: + value - the MPI integer value to return
581: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
583: Level: beginner
585: Notes:
586: If the user does not supply the option at all `value` is NOT changed. Thus
587: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
589: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
591: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
593: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
594: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
595: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
596: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
597: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
598: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
599: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
600: M*/
601: #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)
603: /*MC
604: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
606: Synopsis:
607: #include <petscoptions.h>
608: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
610: Logically Collective on the communicator passed in `PetscOptionsBegin()`
612: Input Parameters:
613: + opt - option name
614: . text - short string that describes the option
615: . man - manual page with additional information on option
616: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
617: .vb
618: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
619: .ve
620: or
621: .vb
622: value = defaultvalue
623: PetscOptionsBoundedInt(..., value, &value, &set, ...);
624: if (set) {
625: .ve
626: - bound - the requested value should be greater than or equal to this bound or an error is generated
628: Output Parameters:
629: + value - the integer 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: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
643: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
644: `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 PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
652: /*MC
653: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
655: Synopsis:
656: #include <petscoptions.h>
657: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
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: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
668: .ve
669: or
670: .vb
671: value = defaultvalue
672: PetscOptionsRangeInt(..., value, &value, &set, ...);
673: if (set) {
674: .ve
675: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
676: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
678: Output Parameters:
679: + value - the integer value to return
680: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
682: Level: beginner
684: Notes:
685: If the user does not supply the option at all `value` is NOT changed. Thus
686: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
688: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
690: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
692: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
693: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
694: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
695: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
696: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
697: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
698: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
699: M*/
700: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
702: /*MC
703: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
705: Synopsis:
706: #include <petscoptions.h>
707: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
709: Logically Collective on the communicator passed in `PetscOptionsBegin()`
711: Input Parameters:
712: + opt - option name
713: . text - short string that describes the option
714: . man - manual page with additional information on option
715: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
716: .vb
717: PetscOptionsReal(..., obj->value,&obj->value,...) or
718: value = defaultvalue
719: PetscOptionsReal(..., value,&value,&set);
720: if (set) {
721: .ve
723: Output Parameters:
724: + value - the value to return
725: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
727: Level: beginner
729: Notes:
730: If the user does not supply the option at all `value` is NOT changed. Thus
731: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
733: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
735: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
737: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
738: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
739: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
740: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
741: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
742: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
743: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
744: M*/
745: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
747: /*MC
748: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
750: Synopsis:
751: #include <petscoptions.h>
752: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
754: Logically Collective on the communicator passed in `PetscOptionsBegin()`
756: Input Parameters:
757: + opt - option name
758: . text - short string that describes the option
759: . man - manual page with additional information on option
760: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
761: .vb
762: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
763: .ve
764: or
765: .vb
766: value = defaultvalue
767: PetscOptionsBoundedReal(..., value, &value, &set, ...);
768: if (set) {
769: .ve
770: - bound - the requested value should be greater than or equal to this bound or an error is generated
772: Output Parameters:
773: + value - the real 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: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
787: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
788: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
789: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
790: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
791: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
792: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
793: M*/
794: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
796: /*MC
797: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
799: Synopsis:
800: #include <petscoptions.h>
801: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
803: Logically Collective on the communicator passed in `PetscOptionsBegin()`
805: Input Parameters:
806: + opt - option name
807: . text - short string that describes the option
808: . man - manual page with additional information on option
809: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
810: .vb
811: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
812: .ve
813: or
814: .vb
815: value = defaultvalue
816: PetscOptionsRangeReal(..., value, &value, &set, ...);
817: if (set) {
818: .ve
819: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
820: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
822: Output Parameters:
823: + value - the value to return
824: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
826: Level: beginner
828: Notes:
829: If the user does not supply the option at all `value` is NOT changed. Thus
830: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
832: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
834: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
836: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
837: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
838: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
839: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
840: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
841: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
842: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
843: M*/
844: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
846: /*MC
847: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
849: Synopsis:
850: #include <petscoptions.h>
851: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
853: Logically Collective on the communicator passed in `PetscOptionsBegin()`
855: Input Parameters:
856: + opt - option name
857: . text - short string that describes the option
858: . man - manual page with additional information on option
859: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
860: .vb
861: PetscOptionsScalar(..., obj->value,&obj->value,...) or
862: value = defaultvalue
863: PetscOptionsScalar(..., value,&value,&set);
864: if (set) {
865: .ve
867: Output Parameters:
868: + value - the value to return
869: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
871: Level: beginner
873: Notes:
874: If the user does not supply the option at all `value` is NOT changed. Thus
875: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
877: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
879: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
881: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
882: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
883: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
884: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
885: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
886: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
887: `PetscOptionsFList()`, `PetscOptionsEList()`
888: M*/
889: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
891: /*MC
892: 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
893: its value is set to false.
895: Synopsis:
896: #include <petscoptions.h>
897: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
899: Logically Collective on the communicator passed in `PetscOptionsBegin()`
901: Input Parameters:
902: + opt - option name
903: . text - short string that describes the option
904: - man - manual page with additional information on option
906: Output Parameter:
907: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
909: Level: beginner
911: Note:
912: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
914: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
915: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
916: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
917: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
918: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
919: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
920: `PetscOptionsFList()`, `PetscOptionsEList()`
921: M*/
922: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
924: /*MC
925: PetscOptionsString - Gets the string value for a particular option in the database.
927: Synopsis:
928: #include <petscoptions.h>
929: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
931: Logically Collective on the communicator passed in `PetscOptionsBegin()`
933: Input Parameters:
934: + opt - option name
935: . text - short string that describes the option
936: . man - manual page with additional information on option
937: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
938: - len - length of the result string including null terminator
940: Output Parameters:
941: + value - the value to return
942: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
944: Level: beginner
946: Notes:
947: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
949: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
951: If the user does not supply the option at all `value` is NOT changed. Thus
952: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
954: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
956: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
957: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
958: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
959: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
960: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
961: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
962: `PetscOptionsFList()`, `PetscOptionsEList()`
963: M*/
964: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
966: /*MC
967: PetscOptionsBool - Determines if a particular option is in the database with a true or false
969: Synopsis:
970: #include <petscoptions.h>
971: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
973: Logically Collective on the communicator passed in `PetscOptionsBegin()`
975: Input Parameters:
976: + opt - option name
977: . text - short string that describes the option
978: . man - manual page with additional information on option
979: - currentvalue - the current value
981: Output Parameters:
982: + flg - `PETSC_TRUE` or `PETSC_FALSE`
983: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
985: Level: beginner
987: Notes:
988: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
990: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
992: 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`
993: is equivalent to `-requested_bool true`
995: If the user does not supply the option at all `flg` is NOT changed. Thus
996: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
998: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1000: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1001: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1002: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1003: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1004: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1005: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1006: `PetscOptionsFList()`, `PetscOptionsEList()`
1007: M*/
1008: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1010: /*MC
1011: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
1013: Synopsis:
1014: #include <petscoptions.h>
1015: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
1017: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1019: Input Parameters:
1020: + opt - option name
1021: . text - short string that describes the option
1022: . man - manual page with additional information on option
1023: - currentvalue - the current value
1025: Output Parameters:
1026: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
1027: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1029: Level: beginner
1031: Notes:
1032: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_BOOL3_TRUE`
1034: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_BOOL3_FALSE`
1036: The option values UNKNOWN and AUTO (case-insensitive) all translate to `PETSC_BOOL3_UNKNOWN`
1038: 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`
1039: is equivalent to `-requested_bool true`
1041: If the user does not supply the option at all `flg` is NOT changed. Thus
1042: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1044: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1046: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1047: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1048: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1049: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1050: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1051: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1052: `PetscOptionsFList()`, `PetscOptionsEList()`
1053: M*/
1054: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1056: /*MC
1057: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1058: which at most a single value can be true.
1060: Synopsis:
1061: #include <petscoptions.h>
1062: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
1064: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1066: Input Parameters:
1067: + opt - option name
1068: . text - short string that describes the option
1069: - man - manual page with additional information on option
1071: Output Parameter:
1072: . set - whether that option was set or not
1074: Level: intermediate
1076: Notes:
1077: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1079: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1081: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1082: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1083: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1084: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1085: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1086: `PetscOptionsFList()`, `PetscOptionsEList()`
1087: M*/
1088: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1090: /*MC
1091: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1092: which at most a single value can be true.
1094: Synopsis:
1095: #include <petscoptions.h>
1096: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1098: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1100: Input Parameters:
1101: + opt - option name
1102: . text - short string that describes the option
1103: - man - manual page with additional information on option
1105: Output Parameter:
1106: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1108: Level: intermediate
1110: Notes:
1111: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1113: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1115: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1116: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1117: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1118: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1119: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1120: `PetscOptionsFList()`, `PetscOptionsEList()`
1121: M*/
1122: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1124: /*MC
1125: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1126: which at most a single value can be true.
1128: Synopsis:
1129: #include <petscoptions.h>
1130: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1132: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1134: Input Parameters:
1135: + opt - option name
1136: . text - short string that describes the option
1137: - man - manual page with additional information on option
1139: Output Parameter:
1140: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1142: Level: intermediate
1144: Notes:
1145: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1147: Must follow a `PetscOptionsBoolGroupBegin()`
1149: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1150: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1151: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1152: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1153: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1154: `PetscOptionsFList()`, `PetscOptionsEList()`
1155: M*/
1156: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1158: /*MC
1159: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1161: Synopsis:
1162: #include <petscoptions.h>
1163: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1165: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1167: Input Parameters:
1168: + opt - option name
1169: . ltext - short string that describes the option
1170: . man - manual page with additional information on option
1171: . list - the possible choices
1172: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1173: .vb
1174: PetscOptionsFlist(..., obj->value,value,len,&set);
1175: if (set) {
1176: .ve
1177: - len - the length of the character array value
1179: Output Parameters:
1180: + value - the value to return
1181: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1183: Level: intermediate
1185: Notes:
1186: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1188: If the user does not supply the option at all `value` is NOT changed. Thus
1189: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1191: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1193: See `PetscOptionsEList()` for when the choices are given in a string array
1195: To get a listing of all currently specified options,
1196: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1198: Developer Note:
1199: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1201: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1202: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1203: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1204: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1205: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1206: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1207: M*/
1208: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1210: /*MC
1211: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1213: Synopsis:
1214: #include <petscoptions.h>
1215: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1217: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1219: Input Parameters:
1220: + opt - option name
1221: . ltext - short string that describes the option
1222: . man - manual page with additional information on option
1223: . list - the possible choices (one of these must be selected, anything else is invalid)
1224: . ntext - number of choices
1225: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1226: .vb
1227: PetscOptionsEList(..., obj->value,&value,&set);
1228: .ve if (set) {
1230: Output Parameters:
1231: + value - the index of the value to return
1232: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1234: Level: intermediate
1236: Notes:
1237: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1239: If the user does not supply the option at all `value` is NOT changed. Thus
1240: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1242: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1244: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1245: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1246: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1247: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1248: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1249: `PetscOptionsFList()`, `PetscOptionsEnum()`
1250: M*/
1251: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1253: /*MC
1254: PetscOptionsRealArray - Gets an array of double values for a particular
1255: option in the database. The values must be separated with commas with
1256: no intervening spaces.
1258: Synopsis:
1259: #include <petscoptions.h>
1260: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1262: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1264: Input Parameters:
1265: + opt - the option one is seeking
1266: . text - short string describing option
1267: . man - manual page for option
1268: - n - maximum number of values that value has room for
1270: Output Parameters:
1271: + value - location to copy values
1272: . n - actual number of values found
1273: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1275: Level: beginner
1277: Note:
1278: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1280: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1281: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1282: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1283: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1284: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1285: `PetscOptionsFList()`, `PetscOptionsEList()`
1286: M*/
1287: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1289: /*MC
1290: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1291: option in the database. The values must be separated with commas with
1292: no intervening spaces.
1294: Synopsis:
1295: #include <petscoptions.h>
1296: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1298: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1300: Input Parameters:
1301: + opt - the option one is seeking
1302: . text - short string describing option
1303: . man - manual page for option
1304: - n - maximum number of values allowed in the value array
1306: Output Parameters:
1307: + value - location to copy values
1308: . n - actual number of values found
1309: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1311: Level: beginner
1313: Note:
1314: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1316: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1317: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1318: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1319: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1320: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1321: `PetscOptionsFList()`, `PetscOptionsEList()`
1322: M*/
1323: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1325: /*MC
1326: PetscOptionsIntArray - Gets an array of integers for a particular
1327: option in the database.
1329: Synopsis:
1330: #include <petscoptions.h>
1331: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1333: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1335: Input Parameters:
1336: + opt - the option one is seeking
1337: . text - short string describing option
1338: . man - manual page for option
1339: - n - maximum number of values
1341: Output Parameters:
1342: + value - location to copy values
1343: . n - actual number of values found
1344: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1346: Level: beginner
1348: Notes:
1349: The array can be passed as
1350: + a comma separated list - 0,1,2,3,4,5,6,7
1351: . a range (start\-end+1) - 0-8
1352: . a range with given increment (start\-end+1:inc) - 0-7:2
1353: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1355: There must be no intervening spaces between the values.
1357: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1359: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1360: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1361: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1362: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1363: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1364: `PetscOptionsFList()`, `PetscOptionsEList()`
1365: M*/
1366: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1368: /*MC
1369: PetscOptionsStringArray - Gets an array of string values for a particular
1370: option in the database. The values must be separated with commas with
1371: no intervening spaces.
1373: Synopsis:
1374: #include <petscoptions.h>
1375: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1377: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1379: Input Parameters:
1380: + opt - the option one is seeking
1381: . text - short string describing option
1382: . man - manual page for option
1383: - n - maximum number of strings
1385: Output Parameters:
1386: + value - location to copy strings
1387: . n - actual number of strings found
1388: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1390: Level: beginner
1392: Notes:
1393: The user should pass in an array of pointers to char, to hold all the
1394: strings returned by this function.
1396: The user is responsible for deallocating the strings that are
1397: returned.
1399: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1401: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1402: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1403: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1404: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1405: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1406: `PetscOptionsFList()`, `PetscOptionsEList()`
1407: M*/
1408: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1410: /*MC
1411: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1412: option in the database. The values must be separated with commas with
1413: no intervening spaces.
1415: Synopsis:
1416: #include <petscoptions.h>
1417: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1419: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1421: Input Parameters:
1422: + opt - the option one is seeking
1423: . text - short string describing option
1424: . man - manual page for option
1425: - n - maximum number of values allowed in the value array
1427: Output Parameters:
1428: + value - location to copy values
1429: . n - actual number of values found
1430: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1432: Level: beginner
1434: Notes:
1435: The option values TRUE, YES, ON (case-insensitive) and 1 all translate to `PETSC_TRUE`
1437: The option values FALSE, NO, OFF (case-insensitive) and 0 all translate to `PETSC_FALSE`
1439: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1441: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1442: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1443: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1444: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1445: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1446: `PetscOptionsFList()`, `PetscOptionsEList()`
1447: M*/
1448: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1450: /*MC
1451: PetscOptionsEnumArray - Gets an array of enum values for a particular
1452: option in the database.
1454: Synopsis:
1455: #include <petscoptions.h>
1456: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1458: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1460: Input Parameters:
1461: + opt - the option one is seeking
1462: . text - short string describing option
1463: . man - manual page for option
1464: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1465: - n - maximum number of values allowed in the value array
1467: Output Parameters:
1468: + value - location to copy values
1469: . n - actual number of values found
1470: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1472: Level: beginner
1474: Notes:
1475: The array must be passed as a comma separated list.
1477: There must be no intervening spaces between the values.
1479: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1481: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1482: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1483: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1484: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1485: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1486: `PetscOptionsFList()`, `PetscOptionsEList()`
1487: M*/
1488: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1490: /*MC
1491: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`.
1492: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1494: Synopsis:
1495: #include <petscoptions.h>
1496: PetscErrorCode PetscOptionsDeprecated(const char oldname[], const char newname[], const char version[], const char info[])
1498: Logically Collective
1500: Input Parameters:
1501: + oldname - the old, deprecated option
1502: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1503: . version - a string describing the version of first deprecation, e.g., `"3.9"`
1504: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1506: Options Database Key:
1507: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1509: Level: developer
1511: Notes:
1512: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1513: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1514: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1516: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecatedNoObject()` otherwise.
1518: Only the process of MPI rank zero that owns the `PetscOptionsItems` argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`) prints the deprecation warning.
1520: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1522: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1524: .seealso: `PetscOptionsDeprecatedNoObject()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1525: M*/
1526: #define PetscOptionsDeprecated(oldname, newname, version, info) PetscOptionsDeprecated_Private(PetscOptionsObject, PETSC_COMM_SELF, NULL, oldname, newname, version, info)
1528: /*MC
1529: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global `PetscOptionsObject`, optionally replacing it with `newname`.
1530: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1532: Synopsis:
1533: #include <petscoptions.h>
1534: PetscErrorCode PetscOptionsDeprecatedNoObject(MPI_Comm comm, const char prefix[], const char oldname[], const char newname[], const char version[], const char info[])
1536: Logically Collective
1538: Input Parameters:
1539: + comm - communicator on which to print deprecated message
1540: . prefix - prefix for the option, generally obtained with `((PetscObject)obj)->prefix`, may be `NULL`
1541: . oldname - the old, deprecated option
1542: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1543: . version - a string describing the version of first deprecation, e.g. `"3.9"`
1544: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1546: Options Database Key:
1547: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1549: Level: developer
1551: Notes:
1552: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecatedNoObject()` occurs before the
1553: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1554: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1556: Not to be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecated()` in that case.
1558: Only the process of MPI rank zero prints the deprecation warning.
1560: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1562: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1564: .seealso: `PetscOptionsDeprecated()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1565: M*/
1566: #define PetscOptionsDeprecatedNoObject(comm, prefix, oldname, newname, version, info) PetscOptionsDeprecated_Private(NULL, comm, prefix, oldname, newname, version, info)
1567: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1569: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1570: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1571: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1572: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1573: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1574: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1575: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1576: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1577: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1578: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1579: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1580: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1581: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1582: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1583: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1584: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1585: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1586: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1587: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1588: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1589: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[], const char[], const char[]);
1591: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1592: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1593: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1595: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);