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 defined(PETSC_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 defined(PETSC_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: Logically Collective on the communicator passed in `PetscOptionsBegin()`
397: Input Parameter:
398: . head - the heading text
400: Level: developer
402: Notes:
403: Handles errors directly, hence does not return an error code
405: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
407: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
409: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
410: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
411: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
412: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
413: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
414: `PetscOptionsFList()`, `PetscOptionsEList()`
415: M*/
416: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
417: do { \
418: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
419: } while (0)
421: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
423: /*MC
424: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
425: See, for example, `KSPSetFromOptions_GMRES()`.
427: Synopsis:
428: #include <petscoptions.h>
429: PetscErrorCode PetscOptionsHeadEnd(void)
431: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
433: Level: intermediate
435: Notes:
436: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
438: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
440: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
441: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
442: from the function.
444: This is only for use with the PETSc options GUI
446: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
447: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
448: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
449: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
450: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
451: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
452: M*/
453: #define PetscOptionsHeadEnd() \
454: do { \
455: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
456: } while (0)
458: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
460: /*MC
461: PetscOptionsEnum - Gets the enum value for a particular option in the database.
463: Synopsis:
464: #include <petscoptions.h>
465: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
467: Logically Collective on the communicator passed in `PetscOptionsBegin()`
469: Input Parameters:
470: + opt - option name
471: . text - short string that describes the option
472: . man - manual page with additional information on option
473: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
474: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
475: .vb
476: PetscOptionsEnum(..., obj->value,&object->value,...) or
477: value = defaultvalue
478: PetscOptionsEnum(..., value,&value,&set);
479: if (set) {
480: .ve
482: Output Parameters:
483: + value - the value to return
484: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
486: Level: beginner
488: Notes:
489: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
491: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
493: If the user does not supply the option at all `value` is NOT changed. Thus
494: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
496: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
498: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
499: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
500: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
501: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
502: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
503: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
504: `PetscOptionsFList()`, `PetscOptionsEList()`
505: M*/
506: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
508: /*MC
509: PetscOptionsInt - Gets the integer value for a particular option in the database.
511: Synopsis:
512: #include <petscoptions.h>
513: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
515: Logically Collective on the communicator passed in `PetscOptionsBegin()`
517: Input Parameters:
518: + opt - option name
519: . text - short string that describes the option
520: . man - manual page with additional information on option
521: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
522: .vb
523: PetscOptionsInt(..., obj->value, &obj->value, ...) or
524: value = defaultvalue
525: PetscOptionsInt(..., value, &value, &set);
526: if (set) {
527: .ve
529: Output Parameters:
530: + value - the integer value to return
531: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
533: Level: beginner
535: Notes:
536: If the user does not supply the option at all `value` is NOT changed. Thus
537: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
539: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
541: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
543: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
544: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
545: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
546: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
547: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
548: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
549: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
550: M*/
551: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
553: /*MC
554: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
556: Synopsis:
557: #include <petscoptions.h>
558: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
560: Logically Collective on the communicator passed in `PetscOptionsBegin()`
562: Input Parameters:
563: + opt - option name
564: . text - short string that describes the option
565: . man - manual page with additional information on option
566: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
567: .vb
568: PetscOptionsInt(..., obj->value, &obj->value, ...) or
569: value = defaultvalue
570: PetscOptionsInt(..., value, &value, &set);
571: if (set) {
572: .ve
574: Output Parameters:
575: + value - the MPI integer value to return
576: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
578: Level: beginner
580: Notes:
581: If the user does not supply the option at all `value` is NOT changed. Thus
582: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
584: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
586: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
588: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
589: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
590: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
591: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
592: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
593: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
594: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
595: M*/
596: #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)
598: /*MC
599: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
601: Synopsis:
602: #include <petscoptions.h>
603: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
605: Logically Collective on the communicator passed in `PetscOptionsBegin()`
607: Input Parameters:
608: + opt - option name
609: . text - short string that describes the option
610: . man - manual page with additional information on option
611: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
612: .vb
613: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
614: .ve
615: or
616: .vb
617: value = defaultvalue
618: PetscOptionsBoundedInt(..., value, &value, &set, ...);
619: if (set) {
620: .ve
621: - bound - the requested value should be greater than or equal to this bound or an error is generated
623: Output Parameters:
624: + value - the integer value to return
625: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
627: Level: beginner
629: Notes:
630: If the user does not supply the option at all `value` is NOT changed. Thus
631: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
633: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
635: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
637: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
638: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
639: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
640: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
641: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
642: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
643: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
644: M*/
645: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
647: /*MC
648: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
650: Synopsis:
651: #include <petscoptions.h>
652: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
654: Logically Collective on the communicator passed in `PetscOptionsBegin()`
656: Input Parameters:
657: + opt - option name
658: . text - short string that describes the option
659: . man - manual page with additional information on option
660: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
661: .vb
662: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
663: .ve
664: or
665: .vb
666: value = defaultvalue
667: PetscOptionsRangeInt(..., value, &value, &set, ...);
668: if (set) {
669: .ve
670: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
671: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
673: Output Parameters:
674: + value - the integer value to return
675: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
677: Level: beginner
679: Notes:
680: If the user does not supply the option at all `value` is NOT changed. Thus
681: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
683: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
685: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
687: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
688: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
689: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
690: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
691: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
692: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
693: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
694: M*/
695: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
697: /*MC
698: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
700: Synopsis:
701: #include <petscoptions.h>
702: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
704: Logically Collective on the communicator passed in `PetscOptionsBegin()`
706: Input Parameters:
707: + opt - option name
708: . text - short string that describes the option
709: . man - manual page with additional information on option
710: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
711: .vb
712: PetscOptionsReal(..., obj->value,&obj->value,...) or
713: value = defaultvalue
714: PetscOptionsReal(..., value,&value,&set);
715: if (set) {
716: .ve
718: Output Parameters:
719: + value - the value to return
720: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
722: Level: beginner
724: Notes:
725: If the user does not supply the option at all `value` is NOT changed. Thus
726: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
728: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
730: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
732: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
733: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
734: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
735: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
736: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
737: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
738: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
739: M*/
740: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
742: /*MC
743: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
745: Synopsis:
746: #include <petscoptions.h>
747: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
749: Logically Collective on the communicator passed in `PetscOptionsBegin()`
751: Input Parameters:
752: + opt - option name
753: . text - short string that describes the option
754: . man - manual page with additional information on option
755: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
756: .vb
757: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
758: .ve
759: or
760: .vb
761: value = defaultvalue
762: PetscOptionsBoundedReal(..., value, &value, &set, ...);
763: if (set) {
764: .ve
765: - bound - the requested value should be greater than or equal to this bound or an error is generated
767: Output Parameters:
768: + value - the real value to return
769: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
771: Level: beginner
773: Notes:
774: If the user does not supply the option at all `value` is NOT changed. Thus
775: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
777: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
779: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
781: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
782: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
783: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
784: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
785: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
786: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
787: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
788: M*/
789: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
791: /*MC
792: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
794: Synopsis:
795: #include <petscoptions.h>
796: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
798: Logically Collective on the communicator passed in `PetscOptionsBegin()`
800: Input Parameters:
801: + opt - option name
802: . text - short string that describes the option
803: . man - manual page with additional information on option
804: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
805: .vb
806: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
807: .ve
808: or
809: .vb
810: value = defaultvalue
811: PetscOptionsRangeReal(..., value, &value, &set, ...);
812: if (set) {
813: .ve
814: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
815: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
817: Output Parameters:
818: + value - the value to return
819: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
821: Level: beginner
823: Notes:
824: If the user does not supply the option at all `value` is NOT changed. Thus
825: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
827: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
829: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
831: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
832: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
833: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
834: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
835: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
836: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
837: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
838: M*/
839: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
841: /*MC
842: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
844: Synopsis:
845: #include <petscoptions.h>
846: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
848: Logically Collective on the communicator passed in `PetscOptionsBegin()`
850: Input Parameters:
851: + opt - option name
852: . text - short string that describes the option
853: . man - manual page with additional information on option
854: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
855: .vb
856: PetscOptionsScalar(..., obj->value,&obj->value,...) or
857: value = defaultvalue
858: PetscOptionsScalar(..., value,&value,&set);
859: if (set) {
860: .ve
862: Output Parameters:
863: + value - the value to return
864: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
866: Level: beginner
868: Notes:
869: If the user does not supply the option at all `value` is NOT changed. Thus
870: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
872: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
874: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
876: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
877: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
878: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
879: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
880: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
881: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
882: `PetscOptionsFList()`, `PetscOptionsEList()`
883: M*/
884: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
886: /*MC
887: 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
888: its value is set to false.
890: Synopsis:
891: #include <petscoptions.h>
892: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
894: Logically Collective on the communicator passed in `PetscOptionsBegin()`
896: Input Parameters:
897: + opt - option name
898: . text - short string that describes the option
899: - man - manual page with additional information on option
901: Output Parameter:
902: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
904: Level: beginner
906: Note:
907: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
909: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
910: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
911: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
912: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
913: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
914: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
915: `PetscOptionsFList()`, `PetscOptionsEList()`
916: M*/
917: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
919: /*MC
920: PetscOptionsString - Gets the string value for a particular option in the database.
922: Synopsis:
923: #include <petscoptions.h>
924: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
926: Logically Collective on the communicator passed in `PetscOptionsBegin()`
928: Input Parameters:
929: + opt - option name
930: . text - short string that describes the option
931: . man - manual page with additional information on option
932: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
933: - len - length of the result string including null terminator
935: Output Parameters:
936: + value - the value to return
937: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
939: Level: beginner
941: Notes:
942: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
944: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
946: If the user does not supply the option at all `value` is NOT changed. Thus
947: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
949: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
951: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
952: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
953: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
954: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
955: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
956: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
957: `PetscOptionsFList()`, `PetscOptionsEList()`
958: M*/
959: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
961: /*MC
962: PetscOptionsBool - Determines if a particular option is in the database with a true or false
964: Synopsis:
965: #include <petscoptions.h>
966: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
968: Logically Collective on the communicator passed in `PetscOptionsBegin()`
970: Input Parameters:
971: + opt - option name
972: . text - short string that describes the option
973: . man - manual page with additional information on option
974: - currentvalue - the current value
976: Output Parameters:
977: + flg - `PETSC_TRUE` or `PETSC_FALSE`
978: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
980: Level: beginner
982: Notes:
983: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
984: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
986: 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`
987: is equivalent to `-requested_bool true`
989: If the user does not supply the option at all `flg` is NOT changed. Thus
990: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
992: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
994: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
995: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
996: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
997: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
998: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
999: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1000: `PetscOptionsFList()`, `PetscOptionsEList()`
1001: M*/
1002: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1004: /*MC
1005: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
1007: Synopsis:
1008: #include <petscoptions.h>
1009: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
1011: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1013: Input Parameters:
1014: + opt - option name
1015: . text - short string that describes the option
1016: . man - manual page with additional information on option
1017: - currentvalue - the current value
1019: Output Parameters:
1020: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
1021: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1023: Level: beginner
1025: Notes:
1026: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
1027: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
1029: 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`
1030: is equivalent to `-requested_bool true`
1032: If the user does not supply the option at all `flg` is NOT changed. Thus
1033: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1035: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1037: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1038: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1039: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1040: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1041: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1042: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1043: `PetscOptionsFList()`, `PetscOptionsEList()`
1044: M*/
1045: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1047: /*MC
1048: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1049: which at most a single value can be true.
1051: Synopsis:
1052: #include <petscoptions.h>
1053: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
1055: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1057: Input Parameters:
1058: + opt - option name
1059: . text - short string that describes the option
1060: - man - manual page with additional information on option
1062: Output Parameter:
1063: . set - whether that option was set or not
1065: Level: intermediate
1067: Notes:
1068: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1070: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1072: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1073: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1074: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1075: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1076: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1077: `PetscOptionsFList()`, `PetscOptionsEList()`
1078: M*/
1079: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1081: /*MC
1082: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1083: which at most a single value can be true.
1085: Synopsis:
1086: #include <petscoptions.h>
1087: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1089: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1091: Input Parameters:
1092: + opt - option name
1093: . text - short string that describes the option
1094: - man - manual page with additional information on option
1096: Output Parameter:
1097: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1099: Level: intermediate
1101: Notes:
1102: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1104: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1106: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1107: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1108: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1109: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1110: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1111: `PetscOptionsFList()`, `PetscOptionsEList()`
1112: M*/
1113: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1115: /*MC
1116: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1117: which at most a single value can be true.
1119: Synopsis:
1120: #include <petscoptions.h>
1121: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1123: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1125: Input Parameters:
1126: + opt - option name
1127: . text - short string that describes the option
1128: - man - manual page with additional information on option
1130: Output Parameter:
1131: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1133: Level: intermediate
1135: Notes:
1136: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1138: Must follow a `PetscOptionsBoolGroupBegin()`
1140: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1141: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1142: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1143: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1144: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1145: `PetscOptionsFList()`, `PetscOptionsEList()`
1146: M*/
1147: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1149: /*MC
1150: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1152: Synopsis:
1153: #include <petscoptions.h>
1154: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1156: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1158: Input Parameters:
1159: + opt - option name
1160: . ltext - short string that describes the option
1161: . man - manual page with additional information on option
1162: . list - the possible choices
1163: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1164: .vb
1165: PetscOptionsFlist(..., obj->value,value,len,&set);
1166: if (set) {
1167: .ve
1168: - len - the length of the character array value
1170: Output Parameters:
1171: + value - the value to return
1172: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1174: Level: intermediate
1176: Notes:
1177: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1179: If the user does not supply the option at all `value` is NOT changed. Thus
1180: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1182: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1184: See `PetscOptionsEList()` for when the choices are given in a string array
1186: To get a listing of all currently specified options,
1187: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1189: Developer Note:
1190: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1192: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1193: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1194: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1195: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1196: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1197: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1198: M*/
1199: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1201: /*MC
1202: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1204: Synopsis:
1205: #include <petscoptions.h>
1206: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1208: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1210: Input Parameters:
1211: + opt - option name
1212: . ltext - short string that describes the option
1213: . man - manual page with additional information on option
1214: . list - the possible choices (one of these must be selected, anything else is invalid)
1215: . ntext - number of choices
1216: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1217: .vb
1218: PetscOptionsEList(..., obj->value,&value,&set);
1219: .ve if (set) {
1221: Output Parameters:
1222: + value - the index of the value to return
1223: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1225: Level: intermediate
1227: Notes:
1228: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1230: If the user does not supply the option at all `value` is NOT changed. Thus
1231: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1233: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1235: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1236: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1237: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1238: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1239: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1240: `PetscOptionsFList()`, `PetscOptionsEnum()`
1241: M*/
1242: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1244: /*MC
1245: PetscOptionsRealArray - Gets an array of double values for a particular
1246: option in the database. The values must be separated with commas with
1247: no intervening spaces.
1249: Synopsis:
1250: #include <petscoptions.h>
1251: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1253: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1255: Input Parameters:
1256: + opt - the option one is seeking
1257: . text - short string describing option
1258: . man - manual page for option
1259: - n - maximum number of values that value has room for
1261: Output Parameters:
1262: + value - location to copy values
1263: . n - actual number of values found
1264: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1266: Level: beginner
1268: Note:
1269: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1271: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1272: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1273: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1274: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1275: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1276: `PetscOptionsFList()`, `PetscOptionsEList()`
1277: M*/
1278: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1280: /*MC
1281: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1282: option in the database. The values must be separated with commas with
1283: no intervening spaces.
1285: Synopsis:
1286: #include <petscoptions.h>
1287: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1289: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1291: Input Parameters:
1292: + opt - the option one is seeking
1293: . text - short string describing option
1294: . man - manual page for option
1295: - n - maximum number of values allowed in the value array
1297: Output Parameters:
1298: + value - location to copy values
1299: . n - actual number of values found
1300: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1302: Level: beginner
1304: Note:
1305: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1307: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1308: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1309: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1310: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1311: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1312: `PetscOptionsFList()`, `PetscOptionsEList()`
1313: M*/
1314: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1316: /*MC
1317: PetscOptionsIntArray - Gets an array of integers for a particular
1318: option in the database.
1320: Synopsis:
1321: #include <petscoptions.h>
1322: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1324: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1326: Input Parameters:
1327: + opt - the option one is seeking
1328: . text - short string describing option
1329: . man - manual page for option
1330: - n - maximum number of values
1332: Output Parameters:
1333: + value - location to copy values
1334: . n - actual number of values found
1335: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1337: Level: beginner
1339: Notes:
1340: The array can be passed as
1341: + a comma separated list - 0,1,2,3,4,5,6,7
1342: . a range (start\-end+1) - 0-8
1343: . a range with given increment (start\-end+1:inc) - 0-7:2
1344: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1346: There must be no intervening spaces between the values.
1348: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1350: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1351: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1352: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1353: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1354: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1355: `PetscOptionsFList()`, `PetscOptionsEList()`
1356: M*/
1357: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1359: /*MC
1360: PetscOptionsStringArray - Gets an array of string values for a particular
1361: option in the database. The values must be separated with commas with
1362: no intervening spaces.
1364: Synopsis:
1365: #include <petscoptions.h>
1366: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1368: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1370: Input Parameters:
1371: + opt - the option one is seeking
1372: . text - short string describing option
1373: . man - manual page for option
1374: - n - maximum number of strings
1376: Output Parameters:
1377: + value - location to copy strings
1378: . n - actual number of strings found
1379: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1381: Level: beginner
1383: Notes:
1384: The user should pass in an array of pointers to char, to hold all the
1385: strings returned by this function.
1387: The user is responsible for deallocating the strings that are
1388: returned.
1390: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1392: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1393: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1394: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1395: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1396: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1397: `PetscOptionsFList()`, `PetscOptionsEList()`
1398: M*/
1399: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1401: /*MC
1402: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1403: option in the database. The values must be separated with commas with
1404: no intervening spaces.
1406: Synopsis:
1407: #include <petscoptions.h>
1408: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1410: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1412: Input Parameters:
1413: + opt - the option one is seeking
1414: . text - short string describing option
1415: . man - manual page for option
1416: - n - maximum number of values allowed in the value array
1418: Output Parameters:
1419: + value - location to copy values
1420: . n - actual number of values found
1421: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1423: Level: beginner
1425: Notes:
1426: The user should pass in an array of `PetscBool`
1428: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1430: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1431: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1432: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1433: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1434: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1435: `PetscOptionsFList()`, `PetscOptionsEList()`
1436: M*/
1437: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1439: /*MC
1440: PetscOptionsEnumArray - Gets an array of enum values for a particular
1441: option in the database.
1443: Synopsis:
1444: #include <petscoptions.h>
1445: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1447: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1449: Input Parameters:
1450: + opt - the option one is seeking
1451: . text - short string describing option
1452: . man - manual page for option
1453: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1454: - n - maximum number of values allowed in the value array
1456: Output Parameters:
1457: + value - location to copy values
1458: . n - actual number of values found
1459: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1461: Level: beginner
1463: Notes:
1464: The array must be passed as a comma separated list.
1466: There must be no intervening spaces between the values.
1468: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1470: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1471: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1472: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1473: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1474: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1475: `PetscOptionsFList()`, `PetscOptionsEList()`
1476: M*/
1477: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1479: /*MC
1480: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1482: Prints a deprecation warning, unless an option is supplied to suppress.
1484: Logically Collective
1486: Input Parameters:
1487: + oldname - the old, deprecated option
1488: . newname - the new option, or `NULL` if option is purely removed
1489: . version - a string describing the version of first deprecation, e.g. "3.9"
1490: - info - additional information string, or `NULL`.
1492: Options Database Key:
1493: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1495: Level: developer
1497: Notes:
1498: If `newname` is provided then the options database will automatically check the database for `oldname`.
1500: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1501: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1502: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1504: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1505: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1506: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1507: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1508: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1510: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1511: M*/
1512: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1514: /*MC
1515: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1517: Prints a deprecation warning, unless an option is supplied to suppress.
1519: Logically Collective
1521: Input Parameters:
1522: + oldname - the old, deprecated option
1523: . newname - the new option, or `NULL` if option is purely removed
1524: . version - a string describing the version of first deprecation, e.g. "3.9"
1525: - info - additional information string, or `NULL`.
1527: Options Database Key:
1528: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1530: Level: developer
1532: Notes:
1533: If `newname` is provided then the options database will automatically check the database for `oldname`.
1535: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1536: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1537: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1539: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1540: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1541: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1542: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1544: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1545: M*/
1546: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1547: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1549: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1550: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1551: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1552: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1553: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1554: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1555: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1556: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1557: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1558: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1559: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1560: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1561: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1562: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1563: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1564: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1565: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1566: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1567: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1568: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1569: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);
1571: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1572: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1573: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1575: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);