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: typedef enum {
12: PETSC_OPT_CODE,
13: PETSC_OPT_COMMAND_LINE,
14: PETSC_OPT_FILE,
15: PETSC_OPT_ENVIRONMENT,
16: NUM_PETSC_OPT_SOURCE
17: } PetscOptionSource;
19: #define PETSC_MAX_OPTION_NAME 512
20: /*S
21: PetscOptions - PETSc's runtime options database object; the holder of all PETSc command-line and configuration options for a session, looked up via `PetscOptionsGet*()`
23: Level: beginner
25: Notes:
26: 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).
28: Each `PetscObject` may also carry its own non-default options through `PetscObjectSetOptions()`.
30: .seealso: `PetscOptionsCreate()`, `PetscOptionsDestroy()`, `PetscOptionsPush()`, `PetscOptionsPop()`, `PetscOptionsGetBool()`,
31: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, `PetscOptionsGetString()`, `PetscOptionsSetValue()`, `PetscOptionsView()`
32: S*/
33: typedef struct _n_PetscOptions *PetscOptions;
34: PETSC_EXTERN PetscErrorCode PetscOptionsCreate(PetscOptions *);
35: PETSC_EXTERN PetscErrorCode PetscOptionsPush(PetscOptions);
36: PETSC_EXTERN PetscErrorCode PetscOptionsPop(void);
37: PETSC_EXTERN PetscErrorCode PetscOptionsDestroy(PetscOptions *);
38: PETSC_EXTERN PetscErrorCode PetscOptionsCreateDefault(void);
39: PETSC_EXTERN PetscErrorCode PetscOptionsDestroyDefault(void);
41: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
42: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
43: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
44: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool3(PetscOptions, const char[], const char[], PetscBool3 *, PetscBool *);
45: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
46: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
47: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
48: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
49: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
50: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
51: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
53: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
54: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
55: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
56: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
57: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
58: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
60: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
61: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
62: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
63: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
64: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
66: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
67: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
68: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
69: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
70: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
71: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
72: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
74: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
75: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
76: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
77: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
78: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
79: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
80: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, const char *const *);
81: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
82: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
83: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
85: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
86: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
87: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
88: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
89: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
91: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscCtxDestroyFn *);
92: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
94: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
95: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
97: PETSC_EXTERN PetscBool PetscOptionsPublish;
99: /*
100: See manual page for PetscOptionsBegin()
102: PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
103: options being handled with a PetscOptionsBegin/End()
105: */
106: typedef enum {
107: OPTION_INT,
108: OPTION_BOOL,
109: OPTION_REAL,
110: OPTION_FLIST,
111: OPTION_STRING,
112: OPTION_REAL_ARRAY,
113: OPTION_SCALAR_ARRAY,
114: OPTION_HEAD,
115: OPTION_INT_ARRAY,
116: OPTION_ELIST,
117: OPTION_BOOL_ARRAY,
118: OPTION_STRING_ARRAY
119: } PetscOptionType;
121: /*S
122: 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
124: Level: developer
126: .seealso: `PetscOptions`, `PetscOptionItems`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsInt()`, `PetscOptionsBool()`
127: S*/
128: typedef struct _n_PetscOptionItem *PetscOptionItem;
129: struct _n_PetscOptionItem {
130: char *option;
131: char *text;
132: void *data; /* used to hold the default value and then any value it is changed to by GUI */
133: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
134: const char *const *list; /* used for available values for PetscOptionsEList() */
135: char nlist; /* number of entries in list */
136: char *man;
137: PetscInt arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
138: PetscBool set; /* the user has changed this value in the GUI */
139: PetscOptionType type;
140: PetscOptionItem next;
141: char *pman;
142: void *edata;
143: };
145: /*S
146: 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`
148: Level: developer
150: .seealso: `PetscOptions`, `PetscOptionItem`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscObjectOptionsBegin()`
151: S*/
152: typedef struct _n_PetscOptionItems *PetscOptionItems;
153: struct _n_PetscOptionItems {
154: PetscInt count;
155: PetscOptionItem next;
156: char *prefix, *pprefix;
157: char *title;
158: MPI_Comm comm;
159: PetscBool printhelp, changedmethod, alreadyprinted;
160: PetscObject object;
161: PetscOptions options;
162: };
164: #if defined(PETSC_CLANG_STATIC_ANALYZER)
165: extern PetscOptionItems PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
166: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
167: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
168: PetscErrorCode PetscOptionsEnd(void);
169: #else
170: /*MC
171: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
172: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
173: use `PetscObjectOptionsBegin()` rather than this call.
175: Synopsis:
176: #include <petscoptions.h>
177: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
179: Collective
181: Input Parameters:
182: + comm - communicator that shares GUI
183: . prefix - options prefix for all options displayed on window (optional)
184: . title - short descriptive text, for example "Krylov Solver Options"
185: - mansec - section of manual pages for options, for example `KSP` (optional)
187: Level: intermediate
189: Notes:
190: This is a macro that handles its own error checking, it does not return an error code.
192: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
194: One can add subheadings with `PetscOptionsHeadBegin()`.
196: Developer Notes:
197: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
198: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
199: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
200: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
201: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
202: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
203: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
204: default values are printed if -help was given.
205: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
206: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
207: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
208: currently set.
210: Fortran Note:
211: Returns ierr error code as the final argument per PETSc Fortran API
213: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
214: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
215: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
216: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
217: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
218: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
219: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
220: M*/
221: #define PetscOptionsBegin(comm, prefix, mess, sec) \
222: do { \
223: struct _n_PetscOptionItems PetscOptionsObjectBase; \
224: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
225: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
226: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
227: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
229: /*MC
230: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
231: displayed on the same window of a GUI that allows the user to set the options interactively.
233: Synopsis:
234: #include <petscoptions.h>
235: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
237: Collective
239: Input Parameter:
240: . obj - object to set options for
242: Level: intermediate
244: Notes:
245: This is a macro that handles its own error checking, it does not return an error code.
247: Needs to be ended by a call the `PetscOptionsEnd()`
249: Can add subheadings with `PetscOptionsHeadBegin()`
251: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
252: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
253: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
254: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
255: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
256: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
257: `PetscOptionsFList()`, `PetscOptionsEList()`
258: M*/
259: #define PetscObjectOptionsBegin(obj) \
260: do { \
261: struct _n_PetscOptionItems PetscOptionsObjectBase; \
262: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
263: PetscOptionsObject->options = ((PetscObject)obj)->options; \
264: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
265: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
267: /*MC
268: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
269: displayed on the same window of a GUI that allows the user to set the options interactively.
271: Synopsis:
272: #include <petscoptions.h>
273: PetscErrorCode PetscOptionsEnd(void)
275: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
277: Level: intermediate
279: Notes:
280: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
282: This is a macro that handles its own error checking, it does not return an error code.
284: Fortran Note:
285: Returns ierr error code as the final argument per PETSc Fortran API
287: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
288: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
289: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
290: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
291: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
292: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
293: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
294: M*/
295: #define PetscOptionsEnd() \
296: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
297: } \
298: } \
299: while (0)
300: #endif /* PETSC_CLANG_STATIC_ANALYZER */
302: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[]);
303: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems);
304: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems);
305: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems, const char[]);
307: #if defined(PETSC_CLANG_STATIC_ANALYZER)
308: template <typename... T>
309: void PetscOptionsHeadBegin(T...);
310: void PetscOptionsHeadEnd(void);
311: template <typename... T>
312: PetscErrorCode PetscOptionsEnum(T...);
313: template <typename... T>
314: PetscErrorCode PetscOptionsInt(T...);
315: template <typename... T>
316: PetscErrorCode PetscOptionsBoundedInt(T...);
317: template <typename... T>
318: PetscErrorCode PetscOptionsRangeInt(T...);
319: template <typename... T>
320: PetscErrorCode PetscOptionsReal(T...);
321: template <typename... T>
322: PetscErrorCode PetscOptionsScalar(T...);
323: template <typename... T>
324: PetscErrorCode PetscOptionsName(T...);
325: template <typename... T>
326: PetscErrorCode PetscOptionsString(T...);
327: template <typename... T>
328: PetscErrorCode PetscOptionsBool(T...);
329: template <typename... T>
330: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
331: template <typename... T>
332: PetscErrorCode PetscOptionsBoolGroup(T...);
333: template <typename... T>
334: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
335: template <typename... T>
336: PetscErrorCode PetscOptionsFList(T...);
337: template <typename... T>
338: PetscErrorCode PetscOptionsEList(T...);
339: template <typename... T>
340: PetscErrorCode PetscOptionsRealArray(T...);
341: template <typename... T>
342: PetscErrorCode PetscOptionsScalarArray(T...);
343: template <typename... T>
344: PetscErrorCode PetscOptionsIntArray(T...);
345: template <typename... T>
346: PetscErrorCode PetscOptionsStringArray(T...);
347: template <typename... T>
348: PetscErrorCode PetscOptionsBoolArray(T...);
349: template <typename... T>
350: PetscErrorCode PetscOptionsEnumArray(T...);
351: template <typename... T>
352: PetscErrorCode PetscOptionsDeprecated(T...);
353: template <typename... T>
354: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
355: #else
356: /*MC
357: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
358: in `KSPSetFromOptions_GMRES()`.
360: Logically Collective on the communicator passed in `PetscOptionsBegin()`
362: Input Parameter:
363: . head - the heading text
365: Level: developer
367: Notes:
368: Handles errors directly, hence does not return an error code
370: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
372: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
374: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
375: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
376: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
377: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
378: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
379: `PetscOptionsFList()`, `PetscOptionsEList()`
380: M*/
381: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
382: do { \
383: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
384: } while (0)
386: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
388: /*MC
389: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
390: See, for example, `KSPSetFromOptions_GMRES()`.
392: Synopsis:
393: #include <petscoptions.h>
394: PetscErrorCode PetscOptionsHeadEnd(void)
396: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
398: Level: intermediate
400: Notes:
401: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
403: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
405: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
406: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
407: from the function.
409: This is only for use with the PETSc options GUI
411: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
412: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
413: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
414: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
415: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
416: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
417: M*/
418: #define PetscOptionsHeadEnd() \
419: do { \
420: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
421: } while (0)
423: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
425: /*MC
426: PetscOptionsEnum - Gets the enum value for a particular option in the database.
428: Synopsis:
429: #include <petscoptions.h>
430: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
432: Logically Collective on the communicator passed in `PetscOptionsBegin()`
434: Input Parameters:
435: + opt - option name
436: . text - short string that describes the option
437: . man - manual page with additional information on option
438: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
439: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
440: .vb
441: PetscOptionsEnum(..., obj->value,&object->value,...) or
442: value = defaultvalue
443: PetscOptionsEnum(..., value,&value,&set);
444: if (set) {
445: .ve
447: Output Parameters:
448: + value - the value to return
449: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
451: Level: beginner
453: Notes:
454: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
456: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
458: If the user does not supply the option at all `value` is NOT changed. Thus
459: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
461: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
463: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
464: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
465: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
466: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
467: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
468: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
469: `PetscOptionsFList()`, `PetscOptionsEList()`
470: M*/
471: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
473: /*MC
474: PetscOptionsInt - Gets the integer value for a particular option in the database.
476: Synopsis:
477: #include <petscoptions.h>
478: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
480: Logically Collective on the communicator passed in `PetscOptionsBegin()`
482: Input Parameters:
483: + opt - option name
484: . text - short string that describes the option
485: . man - manual page with additional information on option
486: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
487: .vb
488: PetscOptionsInt(..., obj->value, &obj->value, ...) or
489: value = defaultvalue
490: PetscOptionsInt(..., value, &value, &set);
491: if (set) {
492: .ve
494: Output Parameters:
495: + value - the integer value to return
496: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
498: Level: beginner
500: Notes:
501: If the user does not supply the option at all `value` is NOT changed. Thus
502: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
504: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
506: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
508: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
509: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
510: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
511: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
512: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
513: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
514: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
515: M*/
516: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
518: /*MC
519: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
521: Synopsis:
522: #include <petscoptions.h>
523: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
525: Logically Collective on the communicator passed in `PetscOptionsBegin()`
527: Input Parameters:
528: + opt - option name
529: . text - short string that describes the option
530: . man - manual page with additional information on option
531: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
532: .vb
533: PetscOptionsInt(..., obj->value, &obj->value, ...) or
534: value = defaultvalue
535: PetscOptionsInt(..., value, &value, &set);
536: if (set) {
537: .ve
539: Output Parameters:
540: + value - the MPI integer value to return
541: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
543: Level: beginner
545: Notes:
546: If the user does not supply the option at all `value` is NOT changed. Thus
547: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
549: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
551: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
553: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
554: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
555: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
556: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
557: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
558: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
559: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
560: M*/
561: #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)
563: /*MC
564: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
566: Synopsis:
567: #include <petscoptions.h>
568: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
570: Logically Collective on the communicator passed in `PetscOptionsBegin()`
572: Input Parameters:
573: + opt - option name
574: . text - short string that describes the option
575: . man - manual page with additional information on option
576: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
577: .vb
578: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
579: .ve
580: or
581: .vb
582: value = defaultvalue
583: PetscOptionsBoundedInt(..., value, &value, &set, ...);
584: if (set) {
585: .ve
586: - bound - the requested value should be greater than or equal to this bound or an error is generated
588: Output Parameters:
589: + value - the integer value to return
590: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
592: Level: beginner
594: Notes:
595: If the user does not supply the option at all `value` is NOT changed. Thus
596: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
598: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
600: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
602: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
603: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
604: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
605: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
606: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
607: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
608: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
609: M*/
610: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
612: /*MC
613: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
615: Synopsis:
616: #include <petscoptions.h>
617: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
619: Logically Collective on the communicator passed in `PetscOptionsBegin()`
621: Input Parameters:
622: + opt - option name
623: . text - short string that describes the option
624: . man - manual page with additional information on option
625: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
626: .vb
627: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
628: .ve
629: or
630: .vb
631: value = defaultvalue
632: PetscOptionsRangeInt(..., value, &value, &set, ...);
633: if (set) {
634: .ve
635: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
636: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
638: Output Parameters:
639: + value - the integer value to return
640: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
642: Level: beginner
644: Notes:
645: If the user does not supply the option at all `value` is NOT changed. Thus
646: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
648: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
650: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
652: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
653: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
654: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
655: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
656: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
657: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
658: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
659: M*/
660: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
662: /*MC
663: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
665: Synopsis:
666: #include <petscoptions.h>
667: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
669: Logically Collective on the communicator passed in `PetscOptionsBegin()`
671: Input Parameters:
672: + opt - option name
673: . text - short string that describes the option
674: . man - manual page with additional information on option
675: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
676: .vb
677: PetscOptionsReal(..., obj->value,&obj->value,...) or
678: value = defaultvalue
679: PetscOptionsReal(..., value,&value,&set);
680: if (set) {
681: .ve
683: Output Parameters:
684: + value - the value to return
685: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
687: Level: beginner
689: Notes:
690: If the user does not supply the option at all `value` is NOT changed. Thus
691: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
693: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
695: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
697: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
698: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
699: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
700: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
701: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
702: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
703: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
704: M*/
705: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
707: /*MC
708: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
710: Synopsis:
711: #include <petscoptions.h>
712: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
714: Logically Collective on the communicator passed in `PetscOptionsBegin()`
716: Input Parameters:
717: + opt - option name
718: . text - short string that describes the option
719: . man - manual page with additional information on option
720: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
721: .vb
722: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
723: .ve
724: or
725: .vb
726: value = defaultvalue
727: PetscOptionsBoundedReal(..., value, &value, &set, ...);
728: if (set) {
729: .ve
730: - bound - the requested value should be greater than or equal to this bound or an error is generated
732: Output Parameters:
733: + value - the real value to return
734: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
736: Level: beginner
738: Notes:
739: If the user does not supply the option at all `value` is NOT changed. Thus
740: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
742: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
744: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
746: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
747: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`,
748: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
749: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
750: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
751: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
752: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
753: M*/
754: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
756: /*MC
757: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
759: Synopsis:
760: #include <petscoptions.h>
761: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
763: Logically Collective on the communicator passed in `PetscOptionsBegin()`
765: Input Parameters:
766: + opt - option name
767: . text - short string that describes the option
768: . man - manual page with additional information on option
769: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
770: .vb
771: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
772: .ve
773: or
774: .vb
775: value = defaultvalue
776: PetscOptionsRangeReal(..., value, &value, &set, ...);
777: if (set) {
778: .ve
779: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
780: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
782: Output Parameters:
783: + value - the value to return
784: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
786: Level: beginner
788: Notes:
789: If the user does not supply the option at all `value` is NOT changed. Thus
790: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
792: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
794: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
796: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
797: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`,
798: `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
799: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
800: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
801: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
802: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
803: M*/
804: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
806: /*MC
807: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
809: Synopsis:
810: #include <petscoptions.h>
811: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
813: Logically Collective on the communicator passed in `PetscOptionsBegin()`
815: Input Parameters:
816: + opt - option name
817: . text - short string that describes the option
818: . man - manual page with additional information on option
819: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
820: .vb
821: PetscOptionsScalar(..., obj->value,&obj->value,...) or
822: value = defaultvalue
823: PetscOptionsScalar(..., value,&value,&set);
824: if (set) {
825: .ve
827: Output Parameters:
828: + value - the value to return
829: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
831: Level: beginner
833: Notes:
834: If the user does not supply the option at all `value` is NOT changed. Thus
835: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
837: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
839: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
841: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
842: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
843: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
844: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
845: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
846: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
847: `PetscOptionsFList()`, `PetscOptionsEList()`
848: M*/
849: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
851: /*MC
852: 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
853: its value is set to false.
855: Synopsis:
856: #include <petscoptions.h>
857: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
859: Logically Collective on the communicator passed in `PetscOptionsBegin()`
861: Input Parameters:
862: + opt - option name
863: . text - short string that describes the option
864: - man - manual page with additional information on option
866: Output Parameter:
867: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
869: Level: beginner
871: Note:
872: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
874: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
875: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
876: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
877: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
878: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
879: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
880: `PetscOptionsFList()`, `PetscOptionsEList()`
881: M*/
882: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
884: /*MC
885: PetscOptionsString - Gets the string value for a particular option in the database.
887: Synopsis:
888: #include <petscoptions.h>
889: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
891: Logically Collective on the communicator passed in `PetscOptionsBegin()`
893: Input Parameters:
894: + opt - option name
895: . text - short string that describes the option
896: . man - manual page with additional information on option
897: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
898: - len - length of the result string including null terminator
900: Output Parameters:
901: + value - the value to return
902: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
904: Level: beginner
906: Notes:
907: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
909: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
911: If the user does not supply the option at all `value` is NOT changed. Thus
912: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
914: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
916: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
917: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
918: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
919: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
920: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
921: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
922: `PetscOptionsFList()`, `PetscOptionsEList()`
923: M*/
924: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
926: /*MC
927: PetscOptionsBool - Determines if a particular option is in the database with a true or false
929: Synopsis:
930: #include <petscoptions.h>
931: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
933: Logically Collective on the communicator passed in `PetscOptionsBegin()`
935: Input Parameters:
936: + opt - option name
937: . text - short string that describes the option
938: . man - manual page with additional information on option
939: - currentvalue - the current value
941: Output Parameters:
942: + flg - `PETSC_TRUE` or `PETSC_FALSE`
943: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
945: Level: beginner
947: Notes:
948: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
949: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
951: 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`
952: is equivalent to `-requested_bool true`
954: If the user does not supply the option at all `flg` is NOT changed. Thus
955: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
957: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
959: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
960: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
961: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
962: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
963: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
964: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
965: `PetscOptionsFList()`, `PetscOptionsEList()`
966: M*/
967: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
969: /*MC
970: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
972: Synopsis:
973: #include <petscoptions.h>
974: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, PetscBool *set)
976: Logically Collective on the communicator passed in `PetscOptionsBegin()`
978: Input Parameters:
979: + opt - option name
980: . text - short string that describes the option
981: . man - manual page with additional information on option
982: - currentvalue - the current value
984: Output Parameters:
985: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
986: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
988: Level: beginner
990: Notes:
991: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
992: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
994: 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`
995: is equivalent to `-requested_bool true`
997: If the user does not supply the option at all `flg` is NOT changed. Thus
998: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1000: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1002: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
1003: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1004: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
1005: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1006: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1007: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1008: `PetscOptionsFList()`, `PetscOptionsEList()`
1009: M*/
1010: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1012: /*MC
1013: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
1014: which at most a single value can be true.
1016: Synopsis:
1017: #include <petscoptions.h>
1018: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
1020: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1022: Input Parameters:
1023: + opt - option name
1024: . text - short string that describes the option
1025: - man - manual page with additional information on option
1027: Output Parameter:
1028: . set - whether that option was set or not
1030: Level: intermediate
1032: Notes:
1033: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1035: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1037: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1038: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1039: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1040: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1041: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1042: `PetscOptionsFList()`, `PetscOptionsEList()`
1043: M*/
1044: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1046: /*MC
1047: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1048: which at most a single value can be true.
1050: Synopsis:
1051: #include <petscoptions.h>
1052: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1054: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1056: Input Parameters:
1057: + opt - option name
1058: . text - short string that describes the option
1059: - man - manual page with additional information on option
1061: Output Parameter:
1062: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1064: Level: intermediate
1066: Notes:
1067: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1069: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1071: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1072: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1073: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1074: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1075: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1076: `PetscOptionsFList()`, `PetscOptionsEList()`
1077: M*/
1078: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1080: /*MC
1081: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1082: which at most a single value can be true.
1084: Synopsis:
1085: #include <petscoptions.h>
1086: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1088: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1090: Input Parameters:
1091: + opt - option name
1092: . text - short string that describes the option
1093: - man - manual page with additional information on option
1095: Output Parameter:
1096: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1098: Level: intermediate
1100: Notes:
1101: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1103: Must follow a `PetscOptionsBoolGroupBegin()`
1105: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1106: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1107: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1108: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1109: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1110: `PetscOptionsFList()`, `PetscOptionsEList()`
1111: M*/
1112: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1114: /*MC
1115: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1117: Synopsis:
1118: #include <petscoptions.h>
1119: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1121: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1123: Input Parameters:
1124: + opt - option name
1125: . ltext - short string that describes the option
1126: . man - manual page with additional information on option
1127: . list - the possible choices
1128: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1129: .vb
1130: PetscOptionsFlist(..., obj->value,value,len,&set);
1131: if (set) {
1132: .ve
1133: - len - the length of the character array value
1135: Output Parameters:
1136: + value - the value to return
1137: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1139: Level: intermediate
1141: Notes:
1142: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1144: If the user does not supply the option at all `value` is NOT changed. Thus
1145: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1147: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1149: See `PetscOptionsEList()` for when the choices are given in a string array
1151: To get a listing of all currently specified options,
1152: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1154: Developer Note:
1155: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1157: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1158: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1159: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1160: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1161: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1162: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1163: M*/
1164: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1166: /*MC
1167: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1169: Synopsis:
1170: #include <petscoptions.h>
1171: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1173: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1175: Input Parameters:
1176: + opt - option name
1177: . ltext - short string that describes the option
1178: . man - manual page with additional information on option
1179: . list - the possible choices (one of these must be selected, anything else is invalid)
1180: . ntext - number of choices
1181: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1182: .vb
1183: PetscOptionsEList(..., obj->value,&value,&set);
1184: .ve if (set) {
1186: Output Parameters:
1187: + value - the index of the value to return
1188: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1190: Level: intermediate
1192: Notes:
1193: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1195: If the user does not supply the option at all `value` is NOT changed. Thus
1196: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1198: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1200: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1201: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1202: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1203: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1204: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1205: `PetscOptionsFList()`, `PetscOptionsEnum()`
1206: M*/
1207: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1209: /*MC
1210: PetscOptionsRealArray - Gets an array of double values for a particular
1211: option in the database. The values must be separated with commas with
1212: no intervening spaces.
1214: Synopsis:
1215: #include <petscoptions.h>
1216: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1218: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1220: Input Parameters:
1221: + opt - the option one is seeking
1222: . text - short string describing option
1223: . man - manual page for option
1224: - n - maximum number of values that value has room for
1226: Output Parameters:
1227: + value - location to copy values
1228: . n - actual number of values found
1229: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1231: Level: beginner
1233: Note:
1234: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1236: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1237: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1238: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1239: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1240: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1241: `PetscOptionsFList()`, `PetscOptionsEList()`
1242: M*/
1243: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1245: /*MC
1246: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1247: option in the database. The values must be separated with commas with
1248: no intervening spaces.
1250: Synopsis:
1251: #include <petscoptions.h>
1252: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1254: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1256: Input Parameters:
1257: + opt - the option one is seeking
1258: . text - short string describing option
1259: . man - manual page for option
1260: - n - maximum number of values allowed in the value array
1262: Output Parameters:
1263: + value - location to copy values
1264: . n - actual number of values found
1265: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1267: Level: beginner
1269: Note:
1270: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1272: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1273: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1274: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1275: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1276: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1277: `PetscOptionsFList()`, `PetscOptionsEList()`
1278: M*/
1279: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1281: /*MC
1282: PetscOptionsIntArray - Gets an array of integers for a particular
1283: option in the database.
1285: Synopsis:
1286: #include <petscoptions.h>
1287: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt 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
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: Notes:
1305: The array can be passed as
1306: + a comma separated list - 0,1,2,3,4,5,6,7
1307: . a range (start\-end+1) - 0-8
1308: . a range with given increment (start\-end+1:inc) - 0-7:2
1309: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1311: There must be no intervening spaces between the values.
1313: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1315: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1316: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1317: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1318: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1319: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1320: `PetscOptionsFList()`, `PetscOptionsEList()`
1321: M*/
1322: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1324: /*MC
1325: PetscOptionsStringArray - Gets an array of string values for a particular
1326: option in the database. The values must be separated with commas with
1327: no intervening spaces.
1329: Synopsis:
1330: #include <petscoptions.h>
1331: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1333: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1335: Input Parameters:
1336: + opt - the option one is seeking
1337: . text - short string describing option
1338: . man - manual page for option
1339: - n - maximum number of strings
1341: Output Parameters:
1342: + value - location to copy strings
1343: . n - actual number of strings found
1344: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1346: Level: beginner
1348: Notes:
1349: The user should pass in an array of pointers to char, to hold all the
1350: strings returned by this function.
1352: The user is responsible for deallocating the strings that are
1353: returned.
1355: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1357: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1358: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1359: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1360: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1361: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1362: `PetscOptionsFList()`, `PetscOptionsEList()`
1363: M*/
1364: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1366: /*MC
1367: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1368: option in the database. The values must be separated with commas with
1369: no intervening spaces.
1371: Synopsis:
1372: #include <petscoptions.h>
1373: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1375: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1377: Input Parameters:
1378: + opt - the option one is seeking
1379: . text - short string describing option
1380: . man - manual page for option
1381: - n - maximum number of values allowed in the value array
1383: Output Parameters:
1384: + value - location to copy values
1385: . n - actual number of values found
1386: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1388: Level: beginner
1390: Notes:
1391: The user should pass in an array of `PetscBool`
1393: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1395: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1396: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1397: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1398: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1399: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1400: `PetscOptionsFList()`, `PetscOptionsEList()`
1401: M*/
1402: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1404: /*MC
1405: PetscOptionsEnumArray - Gets an array of enum values for a particular
1406: option in the database.
1408: Synopsis:
1409: #include <petscoptions.h>
1410: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1412: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1414: Input Parameters:
1415: + opt - the option one is seeking
1416: . text - short string describing option
1417: . man - manual page for option
1418: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1419: - n - maximum number of values allowed in the value array
1421: Output Parameters:
1422: + value - location to copy values
1423: . n - actual number of values found
1424: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1426: Level: beginner
1428: Notes:
1429: The array must be passed as a comma separated list.
1431: There must be no intervening spaces between the values.
1433: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1435: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1436: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1437: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1438: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1439: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1440: `PetscOptionsFList()`, `PetscOptionsEList()`
1441: M*/
1442: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1444: /*MC
1445: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1447: Prints a deprecation warning, unless an option is supplied to suppress.
1449: Logically Collective
1451: Input Parameters:
1452: + oldname - the old, deprecated option
1453: . newname - the new option, or `NULL` if option is purely removed
1454: . version - a string describing the version of first deprecation, e.g. "3.9"
1455: - info - additional information string, or `NULL`.
1457: Options Database Key:
1458: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1460: Level: developer
1462: Notes:
1463: If `newname` is provided then the options database will automatically check the database for `oldname`.
1465: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1466: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1467: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1469: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1470: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1471: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1472: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1473: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1475: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1476: M*/
1477: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1479: /*MC
1480: PetscOptionsDeprecatedNoObject - mark an option as deprecated in the global PetscOptionsObject, 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: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1505: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1506: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1507: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1509: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1510: M*/
1511: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1512: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1514: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1515: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1516: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1517: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1518: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1519: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1520: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1521: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1522: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1523: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1524: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1525: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1526: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1527: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1528: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1529: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1530: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1531: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1532: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1533: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1534: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);
1536: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1537: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1538: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1540: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);