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: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
989: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
991: 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`
992: is equivalent to `-requested_bool true`
994: If the user does not supply the option at all `flg` is NOT changed. Thus
995: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
997: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
999: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1000: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1001: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1002: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1003: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1004: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1005: `PetscOptionsFList()`, `PetscOptionsEList()`
1006: M*/
1007: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1009: /*MC
1010: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
1012: Synopsis:
1013: #include <petscoptions.h>
1014: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
1016: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1018: Input Parameters:
1019: + opt - option name
1020: . text - short string that describes the option
1021: . man - manual page with additional information on option
1022: - currentvalue - the current value
1024: Output Parameters:
1025: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
1026: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1028: Level: beginner
1030: Notes:
1031: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
1032: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
1034: 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`
1035: is equivalent to `-requested_bool true`
1037: If the user does not supply the option at all `flg` is NOT changed. Thus
1038: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1040: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1042: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1043: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1044: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1045: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1046: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1047: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1048: `PetscOptionsFList()`, `PetscOptionsEList()`
1049: M*/
1050: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1052: /*MC
1053: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1054: which at most a single value can be true.
1056: Synopsis:
1057: #include <petscoptions.h>
1058: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
1060: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1062: Input Parameters:
1063: + opt - option name
1064: . text - short string that describes the option
1065: - man - manual page with additional information on option
1067: Output Parameter:
1068: . set - whether that option was set or not
1070: Level: intermediate
1072: Notes:
1073: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1075: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1077: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1078: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1079: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1080: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1081: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1082: `PetscOptionsFList()`, `PetscOptionsEList()`
1083: M*/
1084: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1086: /*MC
1087: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1088: which at most a single value can be true.
1090: Synopsis:
1091: #include <petscoptions.h>
1092: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1094: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1096: Input Parameters:
1097: + opt - option name
1098: . text - short string that describes the option
1099: - man - manual page with additional information on option
1101: Output Parameter:
1102: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1104: Level: intermediate
1106: Notes:
1107: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1109: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1111: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1112: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1113: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1114: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1115: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1116: `PetscOptionsFList()`, `PetscOptionsEList()`
1117: M*/
1118: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1120: /*MC
1121: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1122: which at most a single value can be true.
1124: Synopsis:
1125: #include <petscoptions.h>
1126: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1128: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1130: Input Parameters:
1131: + opt - option name
1132: . text - short string that describes the option
1133: - man - manual page with additional information on option
1135: Output Parameter:
1136: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1138: Level: intermediate
1140: Notes:
1141: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1143: Must follow a `PetscOptionsBoolGroupBegin()`
1145: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1146: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1147: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1148: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1149: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1150: `PetscOptionsFList()`, `PetscOptionsEList()`
1151: M*/
1152: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1154: /*MC
1155: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1157: Synopsis:
1158: #include <petscoptions.h>
1159: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1161: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1163: Input Parameters:
1164: + opt - option name
1165: . ltext - short string that describes the option
1166: . man - manual page with additional information on option
1167: . list - the possible choices
1168: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1169: .vb
1170: PetscOptionsFlist(..., obj->value,value,len,&set);
1171: if (set) {
1172: .ve
1173: - len - the length of the character array value
1175: Output Parameters:
1176: + value - the value to return
1177: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1179: Level: intermediate
1181: Notes:
1182: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1184: If the user does not supply the option at all `value` is NOT changed. Thus
1185: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1187: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1189: See `PetscOptionsEList()` for when the choices are given in a string array
1191: To get a listing of all currently specified options,
1192: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1194: Developer Note:
1195: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1197: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1198: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1199: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1200: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1201: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1202: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1203: M*/
1204: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1206: /*MC
1207: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1209: Synopsis:
1210: #include <petscoptions.h>
1211: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1213: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1215: Input Parameters:
1216: + opt - option name
1217: . ltext - short string that describes the option
1218: . man - manual page with additional information on option
1219: . list - the possible choices (one of these must be selected, anything else is invalid)
1220: . ntext - number of choices
1221: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1222: .vb
1223: PetscOptionsEList(..., obj->value,&value,&set);
1224: .ve if (set) {
1226: Output Parameters:
1227: + value - the index of the value to return
1228: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1230: Level: intermediate
1232: Notes:
1233: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1235: If the user does not supply the option at all `value` is NOT changed. Thus
1236: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1238: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1240: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1241: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1242: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1243: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1244: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1245: `PetscOptionsFList()`, `PetscOptionsEnum()`
1246: M*/
1247: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1249: /*MC
1250: PetscOptionsRealArray - Gets an array of double values for a particular
1251: option in the database. The values must be separated with commas with
1252: no intervening spaces.
1254: Synopsis:
1255: #include <petscoptions.h>
1256: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1258: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1260: Input Parameters:
1261: + opt - the option one is seeking
1262: . text - short string describing option
1263: . man - manual page for option
1264: - n - maximum number of values that value has room for
1266: Output Parameters:
1267: + value - location to copy values
1268: . n - actual number of values found
1269: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1271: Level: beginner
1273: Note:
1274: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1276: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1277: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1278: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1279: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1280: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1281: `PetscOptionsFList()`, `PetscOptionsEList()`
1282: M*/
1283: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1285: /*MC
1286: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1287: option in the database. The values must be separated with commas with
1288: no intervening spaces.
1290: Synopsis:
1291: #include <petscoptions.h>
1292: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1294: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1296: Input Parameters:
1297: + opt - the option one is seeking
1298: . text - short string describing option
1299: . man - manual page for option
1300: - n - maximum number of values allowed in the value array
1302: Output Parameters:
1303: + value - location to copy values
1304: . n - actual number of values found
1305: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1307: Level: beginner
1309: Note:
1310: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1312: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1313: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1314: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1315: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1316: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1317: `PetscOptionsFList()`, `PetscOptionsEList()`
1318: M*/
1319: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1321: /*MC
1322: PetscOptionsIntArray - Gets an array of integers for a particular
1323: option in the database.
1325: Synopsis:
1326: #include <petscoptions.h>
1327: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1329: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1331: Input Parameters:
1332: + opt - the option one is seeking
1333: . text - short string describing option
1334: . man - manual page for option
1335: - n - maximum number of values
1337: Output Parameters:
1338: + value - location to copy values
1339: . n - actual number of values found
1340: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1342: Level: beginner
1344: Notes:
1345: The array can be passed as
1346: + a comma separated list - 0,1,2,3,4,5,6,7
1347: . a range (start\-end+1) - 0-8
1348: . a range with given increment (start\-end+1:inc) - 0-7:2
1349: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1351: There must be no intervening spaces between the values.
1353: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1355: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1356: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1357: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1358: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1359: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1360: `PetscOptionsFList()`, `PetscOptionsEList()`
1361: M*/
1362: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1364: /*MC
1365: PetscOptionsStringArray - Gets an array of string values for a particular
1366: option in the database. The values must be separated with commas with
1367: no intervening spaces.
1369: Synopsis:
1370: #include <petscoptions.h>
1371: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1373: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1375: Input Parameters:
1376: + opt - the option one is seeking
1377: . text - short string describing option
1378: . man - manual page for option
1379: - n - maximum number of strings
1381: Output Parameters:
1382: + value - location to copy strings
1383: . n - actual number of strings found
1384: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1386: Level: beginner
1388: Notes:
1389: The user should pass in an array of pointers to char, to hold all the
1390: strings returned by this function.
1392: The user is responsible for deallocating the strings that are
1393: returned.
1395: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1397: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1398: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1399: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1400: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1401: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1402: `PetscOptionsFList()`, `PetscOptionsEList()`
1403: M*/
1404: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1406: /*MC
1407: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1408: option in the database. The values must be separated with commas with
1409: no intervening spaces.
1411: Synopsis:
1412: #include <petscoptions.h>
1413: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1415: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1417: Input Parameters:
1418: + opt - the option one is seeking
1419: . text - short string describing option
1420: . man - manual page for option
1421: - n - maximum number of values allowed in the value array
1423: Output Parameters:
1424: + value - location to copy values
1425: . n - actual number of values found
1426: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1428: Level: beginner
1430: Notes:
1431: The user should pass in an array of `PetscBool`
1433: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1435: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1436: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1437: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1438: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1439: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1440: `PetscOptionsFList()`, `PetscOptionsEList()`
1441: M*/
1442: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1444: /*MC
1445: PetscOptionsEnumArray - Gets an array of enum values for a particular
1446: option in the database.
1448: Synopsis:
1449: #include <petscoptions.h>
1450: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1452: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1454: Input Parameters:
1455: + opt - the option one is seeking
1456: . text - short string describing option
1457: . man - manual page for option
1458: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1459: - n - maximum number of values allowed in the value array
1461: Output Parameters:
1462: + value - location to copy values
1463: . n - actual number of values found
1464: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1466: Level: beginner
1468: Notes:
1469: The array must be passed as a comma separated list.
1471: There must be no intervening spaces between the values.
1473: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1475: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1476: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1477: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1478: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1479: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1480: `PetscOptionsFList()`, `PetscOptionsEList()`
1481: M*/
1482: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1484: /*MC
1485: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`.
1486: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1488: Synopsis:
1489: #include <petscoptions.h>
1490: PetscErrorCode PetscOptionsDeprecated(const char oldname[], const char newname[], const char version[], const char info[])
1492: Logically Collective
1494: Input Parameters:
1495: + oldname - the old, deprecated option
1496: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1497: . version - a string describing the version of first deprecation, e.g., `"3.9"`
1498: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1500: Options Database Key:
1501: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1503: Level: developer
1505: Notes:
1506: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1507: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1508: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1510: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecatedNoObject()` otherwise.
1512: Only the process of MPI rank zero that owns the `PetscOptionsItems` argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`) prints the deprecation warning.
1514: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1516: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1518: .seealso: `PetscOptionsDeprecatedNoObject()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1519: M*/
1520: #define PetscOptionsDeprecated(oldname, newname, version, info) PetscOptionsDeprecated_Private(PetscOptionsObject, oldname, newname, version, info)
1522: /*MC
1523: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global `PetscOptionsObject`, optionally replacing it with `newname`.
1524: By default this will trigger a deprecation warning at runtime if `oldname` is in the options database.
1526: Synopsis:
1527: #include <petscoptions.h>
1528: PetscErrorCode PetscOptionsDeprecatedNoObject(const char oldname[], const char newname[], const char version[], const char info[])
1530: Logically Collective
1532: Input Parameters:
1533: + oldname - the old, deprecated option
1534: . newname - the new option, or `NULL` if the option is removed and not simply renamed
1535: . version - a string describing the version of first deprecation, e.g. `"3.9"`
1536: - info - additional information string, or `NULL`. Must be provided if `newname` is `NULL`
1538: Options Database Key:
1539: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1541: Level: developer
1543: Notes:
1544: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecatedNoObject()` occurs before the
1545: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1546: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1548: Not to be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. Use `PetscOptionsDeprecated()` in that case.
1550: Only the process of MPI rank zero prints the deprecation warning.
1552: If `newname` is provided, any use of `oldname` in the options database is replaced with `newname`. Otherwise, `oldname` remains in the options database.
1554: There is a limit on the length of the warning printed, so long strings provided as `info` may be truncated.
1556: .seealso: `PetscOptionsDeprecated()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1557: M*/
1558: #define PetscOptionsDeprecatedNoObject(oldname, newname, version, info) PetscOptionsDeprecated_Private(NULL, oldname, newname, version, info)
1559: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1561: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1562: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1563: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1564: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1565: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1566: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1567: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1568: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1569: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1570: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1571: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1572: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1573: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1574: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1575: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1576: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1577: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1578: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1579: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1580: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1581: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);
1583: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1584: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1585: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1587: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);