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: typedef struct _n_PetscOptions *PetscOptions;
21: PETSC_EXTERN PetscErrorCode PetscOptionsCreate(PetscOptions *);
22: PETSC_EXTERN PetscErrorCode PetscOptionsPush(PetscOptions);
23: PETSC_EXTERN PetscErrorCode PetscOptionsPop(void);
24: PETSC_EXTERN PetscErrorCode PetscOptionsDestroy(PetscOptions *);
25: PETSC_EXTERN PetscErrorCode PetscOptionsCreateDefault(void);
26: PETSC_EXTERN PetscErrorCode PetscOptionsDestroyDefault(void);
28: PETSC_EXTERN PetscErrorCode PetscOptionsHasHelp(PetscOptions, PetscBool *);
29: PETSC_EXTERN PetscErrorCode PetscOptionsHasName(PetscOptions, const char[], const char[], PetscBool *);
30: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool(PetscOptions, const char[], const char[], PetscBool *, PetscBool *);
31: PETSC_EXTERN PetscErrorCode PetscOptionsGetBool3(PetscOptions, const char[], const char[], PetscBool3 *, PetscBool *);
32: PETSC_EXTERN PetscErrorCode PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
33: PETSC_EXTERN PetscErrorCode PetscOptionsGetMPIInt(PetscOptions, const char[], const char[], PetscMPIInt *, PetscBool *);
34: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
35: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
36: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
37: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
38: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
40: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
41: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
42: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
43: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
44: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
45: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
47: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
48: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
49: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
50: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
51: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
53: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
54: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
55: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
56: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
57: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
58: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
59: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
61: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
62: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
63: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
64: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
65: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
66: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
67: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, char **);
68: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
69: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
70: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
72: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
73: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
74: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
75: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
76: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
78: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscCtxDestroyFn *);
79: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
81: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
82: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
84: PETSC_EXTERN PetscBool PetscOptionsPublish;
86: /*
87: See manual page for PetscOptionsBegin()
89: PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
90: options being handled with a PetscOptionsBegin/End()
92: */
93: typedef enum {
94: OPTION_INT,
95: OPTION_BOOL,
96: OPTION_REAL,
97: OPTION_FLIST,
98: OPTION_STRING,
99: OPTION_REAL_ARRAY,
100: OPTION_SCALAR_ARRAY,
101: OPTION_HEAD,
102: OPTION_INT_ARRAY,
103: OPTION_ELIST,
104: OPTION_BOOL_ARRAY,
105: OPTION_STRING_ARRAY
106: } PetscOptionType;
108: typedef struct _n_PetscOptionItem *PetscOptionItem;
109: struct _n_PetscOptionItem {
110: char *option;
111: char *text;
112: void *data; /* used to hold the default value and then any value it is changed to by GUI */
113: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
114: const char *const *list; /* used for available values for PetscOptionsEList() */
115: char nlist; /* number of entries in list */
116: char *man;
117: PetscInt arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc), never a giant value */
118: PetscBool set; /* the user has changed this value in the GUI */
119: PetscOptionType type;
120: PetscOptionItem next;
121: char *pman;
122: void *edata;
123: };
125: typedef struct _p_PetscOptionItems {
126: PetscInt count;
127: PetscOptionItem next;
128: char *prefix, *pprefix;
129: char *title;
130: MPI_Comm comm;
131: PetscBool printhelp, changedmethod, alreadyprinted;
132: PetscObject object;
133: PetscOptions options;
134: } PetscOptionItems;
136: #if defined(PETSC_CLANG_STATIC_ANALYZER)
137: extern PetscOptionItems *PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
138: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
139: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
140: PetscErrorCode PetscOptionsEnd(void);
141: #else
142: /*MC
143: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
144: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
145: use `PetscObjectOptionsBegin()` rather than this call.
147: Synopsis:
148: #include <petscoptions.h>
149: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
151: Collective
153: Input Parameters:
154: + comm - communicator that shares GUI
155: . prefix - options prefix for all options displayed on window (optional)
156: . title - short descriptive text, for example "Krylov Solver Options"
157: - mansec - section of manual pages for options, for example `KSP` (optional)
159: Level: intermediate
161: Notes:
162: This is a macro that handles its own error checking, it does not return an error code.
164: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
166: One can add subheadings with `PetscOptionsHeadBegin()`.
168: Developer Notes:
169: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
170: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
171: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
172: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
173: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
174: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
175: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
176: default values are printed if -help was given.
177: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
178: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
179: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
180: currently set.
182: Fortran Note:
183: Returns ierr error code per PETSc Fortran API
185: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
186: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
187: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
188: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
189: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
190: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
191: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
192: M*/
193: #define PetscOptionsBegin(comm, prefix, mess, sec) \
194: do { \
195: PetscOptionItems PetscOptionsObjectBase; \
196: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
197: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
198: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
199: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
201: /*MC
202: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
203: displayed on the same window of a GUI that allows the user to set the options interactively.
205: Synopsis:
206: #include <petscoptions.h>
207: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
209: Collective
211: Input Parameter:
212: . obj - object to set options for
214: Level: intermediate
216: Notes:
217: This is a macro that handles its own error checking, it does not return an error code.
219: Needs to be ended by a call the `PetscOptionsEnd()`
221: Can add subheadings with `PetscOptionsHeadBegin()`
223: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
224: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
225: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
226: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
227: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
228: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
229: `PetscOptionsFList()`, `PetscOptionsEList()`
230: M*/
231: #define PetscObjectOptionsBegin(obj) \
232: do { \
233: PetscOptionItems PetscOptionsObjectBase; \
234: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
235: PetscOptionsObject->options = (obj)->options; \
236: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
237: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
239: /*MC
240: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
241: displayed on the same window of a GUI that allows the user to set the options interactively.
243: Synopsis:
244: #include <petscoptions.h>
245: PetscErrorCode PetscOptionsEnd(void)
247: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
249: Level: intermediate
251: Notes:
252: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
254: This is a macro that handles its own error checking, it does not return an error code.
256: Fortran Note:
257: Returns ierr error code per PETSc Fortran API
259: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
260: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
261: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
262: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
263: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
264: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
265: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
266: M*/
267: #define PetscOptionsEnd() \
268: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
269: } \
270: } \
271: while (0)
272: #endif /* PETSC_CLANG_STATIC_ANALYZER */
274: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *, MPI_Comm, const char[], const char[], const char[]);
275: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems *);
276: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *);
277: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems *, const char[]);
279: #if defined(PETSC_CLANG_STATIC_ANALYZER)
280: template <typename... T>
281: void PetscOptionsHeadBegin(T...);
282: void PetscOptionsHeadEnd(void);
283: template <typename... T>
284: PetscErrorCode PetscOptionsEnum(T...);
285: template <typename... T>
286: PetscErrorCode PetscOptionsInt(T...);
287: template <typename... T>
288: PetscErrorCode PetscOptionsBoundedInt(T...);
289: template <typename... T>
290: PetscErrorCode PetscOptionsRangeInt(T...);
291: template <typename... T>
292: PetscErrorCode PetscOptionsReal(T...);
293: template <typename... T>
294: PetscErrorCode PetscOptionsScalar(T...);
295: template <typename... T>
296: PetscErrorCode PetscOptionsName(T...);
297: template <typename... T>
298: PetscErrorCode PetscOptionsString(T...);
299: template <typename... T>
300: PetscErrorCode PetscOptionsBool(T...);
301: template <typename... T>
302: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
303: template <typename... T>
304: PetscErrorCode PetscOptionsBoolGroup(T...);
305: template <typename... T>
306: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
307: template <typename... T>
308: PetscErrorCode PetscOptionsFList(T...);
309: template <typename... T>
310: PetscErrorCode PetscOptionsEList(T...);
311: template <typename... T>
312: PetscErrorCode PetscOptionsRealArray(T...);
313: template <typename... T>
314: PetscErrorCode PetscOptionsScalarArray(T...);
315: template <typename... T>
316: PetscErrorCode PetscOptionsIntArray(T...);
317: template <typename... T>
318: PetscErrorCode PetscOptionsStringArray(T...);
319: template <typename... T>
320: PetscErrorCode PetscOptionsBoolArray(T...);
321: template <typename... T>
322: PetscErrorCode PetscOptionsEnumArray(T...);
323: template <typename... T>
324: PetscErrorCode PetscOptionsDeprecated(T...);
325: template <typename... T>
326: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
327: #else
328: /*MC
329: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
330: in `KSPSetFromOptions_GMRES()`.
332: Logically Collective on the communicator passed in `PetscOptionsBegin()`
334: Input Parameter:
335: . head - the heading text
337: Level: developer
339: Notes:
340: Handles errors directly, hence does not return an error code
342: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
344: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
346: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
347: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
348: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
349: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
350: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
351: `PetscOptionsFList()`, `PetscOptionsEList()`
352: M*/
353: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
354: do { \
355: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
356: } while (0)
358: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
360: /*MC
361: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
362: See, for example, `KSPSetFromOptions_GMRES()`.
364: Synopsis:
365: #include <petscoptions.h>
366: PetscErrorCode PetscOptionsHeadEnd(void)
368: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
370: Level: intermediate
372: Notes:
373: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
375: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
377: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
378: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
379: from the function.
381: This is only for use with the PETSc options GUI
383: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
384: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
385: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
386: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
387: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
388: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
389: M*/
390: #define PetscOptionsHeadEnd() \
391: do { \
392: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
393: } while (0)
395: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
397: /*MC
398: PetscOptionsEnum - Gets the enum value for a particular option in the database.
400: Synopsis:
401: #include <petscoptions.h>
402: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
404: Logically Collective on the communicator passed in `PetscOptionsBegin()`
406: Input Parameters:
407: + opt - option name
408: . text - short string that describes the option
409: . man - manual page with additional information on option
410: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
411: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
412: .vb
413: PetscOptionsEnum(..., obj->value,&object->value,...) or
414: value = defaultvalue
415: PetscOptionsEnum(..., value,&value,&set);
416: if (set) {
417: .ve
419: Output Parameters:
420: + value - the value to return
421: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
423: Level: beginner
425: Notes:
426: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
428: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
430: If the user does not supply the option at all `value` is NOT changed. Thus
431: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
433: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
435: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
436: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
437: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
438: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
439: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
440: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
441: `PetscOptionsFList()`, `PetscOptionsEList()`
442: M*/
443: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
445: /*MC
446: PetscOptionsInt - Gets the integer value for a particular option in the database.
448: Synopsis:
449: #include <petscoptions.h>
450: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
452: Logically Collective on the communicator passed in `PetscOptionsBegin()`
454: Input Parameters:
455: + opt - option name
456: . text - short string that describes the option
457: . man - manual page with additional information on option
458: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
459: .vb
460: PetscOptionsInt(..., obj->value, &obj->value, ...) or
461: value = defaultvalue
462: PetscOptionsInt(..., value, &value, &set);
463: if (set) {
464: .ve
466: Output Parameters:
467: + value - the integer value to return
468: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
470: Level: beginner
472: Notes:
473: If the user does not supply the option at all `value` is NOT changed. Thus
474: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
476: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
478: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
480: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
481: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
482: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
483: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
484: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
485: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
486: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
487: M*/
488: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
490: /*MC
491: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
493: Synopsis:
494: #include <petscoptions.h>
495: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
497: Logically Collective on the communicator passed in `PetscOptionsBegin()`
499: Input Parameters:
500: + opt - option name
501: . text - short string that describes the option
502: . man - manual page with additional information on option
503: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
504: .vb
505: PetscOptionsInt(..., obj->value, &obj->value, ...) or
506: value = defaultvalue
507: PetscOptionsInt(..., value, &value, &set);
508: if (set) {
509: .ve
511: Output Parameters:
512: + value - the MPI integer value to return
513: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
515: Level: beginner
517: Notes:
518: If the user does not supply the option at all `value` is NOT changed. Thus
519: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
521: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
523: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
525: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
526: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
527: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
528: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
529: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
530: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
531: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
532: M*/
533: #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)
535: /*MC
536: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
538: Synopsis:
539: #include <petscoptions.h>
540: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
542: Logically Collective on the communicator passed in `PetscOptionsBegin()`
544: Input Parameters:
545: + opt - option name
546: . text - short string that describes the option
547: . man - manual page with additional information on option
548: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
549: .vb
550: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
551: .ve
552: or
553: .vb
554: value = defaultvalue
555: PetscOptionsBoundedInt(..., value, &value, &set, ...);
556: if (set) {
557: .ve
558: - bound - the requested value should be greater than or equal to this bound or an error is generated
560: Output Parameters:
561: + value - the integer value to return
562: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
564: Level: beginner
566: Notes:
567: If the user does not supply the option at all `value` is NOT changed. Thus
568: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
570: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
572: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
574: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
575: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
576: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
577: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
578: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
579: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
580: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
581: M*/
582: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
584: /*MC
585: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
587: Synopsis:
588: #include <petscoptions.h>
589: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
591: Logically Collective on the communicator passed in `PetscOptionsBegin()`
593: Input Parameters:
594: + opt - option name
595: . text - short string that describes the option
596: . man - manual page with additional information on option
597: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
598: .vb
599: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
600: .ve
601: or
602: .vb
603: value = defaultvalue
604: PetscOptionsRangeInt(..., value, &value, &set, ...);
605: if (set) {
606: .ve
607: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
608: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
610: Output Parameters:
611: + value - the integer value to return
612: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
614: Level: beginner
616: Notes:
617: If the user does not supply the option at all `value` is NOT changed. Thus
618: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
620: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
622: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
624: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
625: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
626: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
627: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
628: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
629: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
630: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
631: M*/
632: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
634: /*MC
635: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
637: Synopsis:
638: #include <petscoptions.h>
639: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
641: Logically Collective on the communicator passed in `PetscOptionsBegin()`
643: Input Parameters:
644: + opt - option name
645: . text - short string that describes the option
646: . man - manual page with additional information on option
647: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
648: .vb
649: PetscOptionsReal(..., obj->value,&obj->value,...) or
650: value = defaultvalue
651: PetscOptionsReal(..., value,&value,&set);
652: if (set) {
653: .ve
655: Output Parameters:
656: + value - the value to return
657: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
659: Level: beginner
661: Notes:
662: If the user does not supply the option at all `value` is NOT changed. Thus
663: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
665: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
667: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
669: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
670: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
671: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
672: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
673: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
674: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
675: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
676: M*/
677: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
679: /*MC
680: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
682: Synopsis:
683: #include <petscoptions.h>
684: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
686: Logically Collective on the communicator passed in `PetscOptionsBegin()`
688: Input Parameters:
689: + opt - option name
690: . text - short string that describes the option
691: . man - manual page with additional information on option
692: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
693: .vb
694: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
695: .ve
696: or
697: .vb
698: value = defaultvalue
699: PetscOptionsBoundedReal(..., value, &value, &set, ...);
700: if (set) {
701: .ve
702: - bound - the requested value should be greater than or equal to this bound or an error is generated
704: Output Parameters:
705: + value - the real value to return
706: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
708: Level: beginner
710: Notes:
711: If the user does not supply the option at all `value` is NOT changed. Thus
712: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
714: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
716: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
718: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
719: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
720: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
721: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
722: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
723: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
724: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
725: M*/
726: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
728: /*MC
729: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
731: Synopsis:
732: #include <petscoptions.h>
733: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
735: Logically Collective on the communicator passed in `PetscOptionsBegin()`
737: Input Parameters:
738: + opt - option name
739: . text - short string that describes the option
740: . man - manual page with additional information on option
741: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
742: .vb
743: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
744: .ve
745: or
746: .vb
747: value = defaultvalue
748: PetscOptionsRangeReal(..., value, &value, &set, ...);
749: if (set) {
750: .ve
751: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
752: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
754: Output Parameters:
755: + value - the value to return
756: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
758: Level: beginner
760: Notes:
761: If the user does not supply the option at all `value` is NOT changed. Thus
762: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
764: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
766: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
768: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
769: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
770: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
771: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
772: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
773: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
774: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
775: M*/
776: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
778: /*MC
779: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
781: Synopsis:
782: #include <petscoptions.h>
783: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
785: Logically Collective on the communicator passed in `PetscOptionsBegin()`
787: Input Parameters:
788: + opt - option name
789: . text - short string that describes the option
790: . man - manual page with additional information on option
791: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
792: .vb
793: PetscOptionsScalar(..., obj->value,&obj->value,...) or
794: value = defaultvalue
795: PetscOptionsScalar(..., value,&value,&set);
796: if (set) {
797: .ve
799: Output Parameters:
800: + value - the value to return
801: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
803: Level: beginner
805: Notes:
806: If the user does not supply the option at all `value` is NOT changed. Thus
807: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
809: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
811: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
813: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
814: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
815: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
816: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
817: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
818: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
819: `PetscOptionsFList()`, `PetscOptionsEList()`
820: M*/
821: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
823: /*MC
824: 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
825: its value is set to false.
827: Synopsis:
828: #include <petscoptions.h>
829: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
831: Logically Collective on the communicator passed in `PetscOptionsBegin()`
833: Input Parameters:
834: + opt - option name
835: . text - short string that describes the option
836: - man - manual page with additional information on option
838: Output Parameter:
839: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
841: Level: beginner
843: Note:
844: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
846: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
847: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
848: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
849: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
850: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
851: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
852: `PetscOptionsFList()`, `PetscOptionsEList()`
853: M*/
854: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
856: /*MC
857: PetscOptionsString - Gets the string value for a particular option in the database.
859: Synopsis:
860: #include <petscoptions.h>
861: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
863: Logically Collective on the communicator passed in `PetscOptionsBegin()`
865: Input Parameters:
866: + opt - option name
867: . text - short string that describes the option
868: . man - manual page with additional information on option
869: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
870: - len - length of the result string including null terminator
872: Output Parameters:
873: + value - the value to return
874: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
876: Level: beginner
878: Notes:
879: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
881: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
883: If the user does not supply the option at all `value` is NOT changed. Thus
884: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
886: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
888: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
889: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
890: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
891: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
892: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
893: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
894: `PetscOptionsFList()`, `PetscOptionsEList()`
895: M*/
896: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
898: /*MC
899: PetscOptionsBool - Determines if a particular option is in the database with a true or false
901: Synopsis:
902: #include <petscoptions.h>
903: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
905: Logically Collective on the communicator passed in `PetscOptionsBegin()`
907: Input Parameters:
908: + opt - option name
909: . text - short string that describes the option
910: . man - manual page with additional information on option
911: - currentvalue - the current value
913: Output Parameters:
914: + flg - `PETSC_TRUE` or `PETSC_FALSE`
915: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
917: Level: beginner
919: Notes:
920: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
921: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
923: 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`
924: is equivalent to `-requested_bool true`
926: If the user does not supply the option at all `flg` is NOT changed. Thus
927: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
929: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
931: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
932: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
933: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
934: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
935: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
936: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
937: `PetscOptionsFList()`, `PetscOptionsEList()`
938: M*/
939: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
941: /*MC
942: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
943: which at most a single value can be true.
945: Synopsis:
946: #include <petscoptions.h>
947: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
949: Logically Collective on the communicator passed in `PetscOptionsBegin()`
951: Input Parameters:
952: + opt - option name
953: . text - short string that describes the option
954: - man - manual page with additional information on option
956: Output Parameter:
957: . set - whether that option was set or not
959: Level: intermediate
961: Notes:
962: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
964: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
966: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
967: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
968: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
969: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
970: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
971: `PetscOptionsFList()`, `PetscOptionsEList()`
972: M*/
973: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
975: /*MC
976: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
977: which at most a single value can be true.
979: Synopsis:
980: #include <petscoptions.h>
981: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
983: Logically Collective on the communicator passed in `PetscOptionsBegin()`
985: Input Parameters:
986: + opt - option name
987: . text - short string that describes the option
988: - man - manual page with additional information on option
990: Output Parameter:
991: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
993: Level: intermediate
995: Notes:
996: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
998: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1000: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1001: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1002: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1003: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1004: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1005: `PetscOptionsFList()`, `PetscOptionsEList()`
1006: M*/
1007: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1009: /*MC
1010: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1011: which at most a single value can be true.
1013: Synopsis:
1014: #include <petscoptions.h>
1015: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1017: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1019: Input Parameters:
1020: + opt - option name
1021: . text - short string that describes the option
1022: - man - manual page with additional information on option
1024: Output Parameter:
1025: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1027: Level: intermediate
1029: Notes:
1030: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1032: Must follow a `PetscOptionsBoolGroupBegin()`
1034: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1035: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1036: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1037: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1038: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1039: `PetscOptionsFList()`, `PetscOptionsEList()`
1040: M*/
1041: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1043: /*MC
1044: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1046: Synopsis:
1047: #include <petscoptions.h>
1048: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1050: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1052: Input Parameters:
1053: + opt - option name
1054: . ltext - short string that describes the option
1055: . man - manual page with additional information on option
1056: . list - the possible choices
1057: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1058: .vb
1059: PetscOptionsFlist(..., obj->value,value,len,&set);
1060: if (set) {
1061: .ve
1062: - len - the length of the character array value
1064: Output Parameters:
1065: + value - the value to return
1066: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1068: Level: intermediate
1070: Notes:
1071: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1073: If the user does not supply the option at all `value` is NOT changed. Thus
1074: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1076: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1078: See `PetscOptionsEList()` for when the choices are given in a string array
1080: To get a listing of all currently specified options,
1081: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1083: Developer Note:
1084: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1086: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1087: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1088: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1089: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1090: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1091: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1092: M*/
1093: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1095: /*MC
1096: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1098: Synopsis:
1099: #include <petscoptions.h>
1100: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1102: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1104: Input Parameters:
1105: + opt - option name
1106: . ltext - short string that describes the option
1107: . man - manual page with additional information on option
1108: . list - the possible choices (one of these must be selected, anything else is invalid)
1109: . ntext - number of choices
1110: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1111: .vb
1112: PetscOptionsEList(..., obj->value,&value,&set);
1113: .ve if (set) {
1115: Output Parameters:
1116: + value - the index of the value to return
1117: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1119: Level: intermediate
1121: Notes:
1122: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1124: If the user does not supply the option at all `value` is NOT changed. Thus
1125: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1127: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1129: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1130: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1131: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1132: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1133: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1134: `PetscOptionsFList()`, `PetscOptionsEnum()`
1135: M*/
1136: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1138: /*MC
1139: PetscOptionsRealArray - Gets an array of double values for a particular
1140: option in the database. The values must be separated with commas with
1141: no intervening spaces.
1143: Synopsis:
1144: #include <petscoptions.h>
1145: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1147: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1149: Input Parameters:
1150: + opt - the option one is seeking
1151: . text - short string describing option
1152: . man - manual page for option
1153: - n - maximum number of values that value has room for
1155: Output Parameters:
1156: + value - location to copy values
1157: . n - actual number of values found
1158: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1160: Level: beginner
1162: Note:
1163: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1165: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1166: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1167: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1168: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1169: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1170: `PetscOptionsFList()`, `PetscOptionsEList()`
1171: M*/
1172: #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1174: /*MC
1175: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1176: option in the database. The values must be separated with commas with
1177: no intervening spaces.
1179: Synopsis:
1180: #include <petscoptions.h>
1181: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1183: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1185: Input Parameters:
1186: + opt - the option one is seeking
1187: . text - short string describing option
1188: . man - manual page for option
1189: - n - maximum number of values allowed in the value array
1191: Output Parameters:
1192: + value - location to copy values
1193: . n - actual number of values found
1194: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1196: Level: beginner
1198: Note:
1199: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1201: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1202: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1203: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1204: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1205: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1206: `PetscOptionsFList()`, `PetscOptionsEList()`
1207: M*/
1208: #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1210: /*MC
1211: PetscOptionsIntArray - Gets an array of integers for a particular
1212: option in the database.
1214: Synopsis:
1215: #include <petscoptions.h>
1216: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt 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
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: Notes:
1234: The array can be passed as
1235: + a comma separated list - 0,1,2,3,4,5,6,7
1236: . a range (start\-end+1) - 0-8
1237: . a range with given increment (start\-end+1:inc) - 0-7:2
1238: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1240: There must be no intervening spaces between the values.
1242: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1244: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1245: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1246: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1247: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1248: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1249: `PetscOptionsFList()`, `PetscOptionsEList()`
1250: M*/
1251: #define PetscOptionsIntArray(opt, text, man, currentvalue, value, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1253: /*MC
1254: PetscOptionsStringArray - Gets an array of string values for a particular
1255: option in the database. The values must be separated with commas with
1256: no intervening spaces.
1258: Synopsis:
1259: #include <petscoptions.h>
1260: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1262: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1264: Input Parameters:
1265: + opt - the option one is seeking
1266: . text - short string describing option
1267: . man - manual page for option
1268: - nmax - maximum number of strings
1270: Output Parameters:
1271: + value - location to copy strings
1272: . nmax - actual number of strings found
1273: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1275: Level: beginner
1277: Notes:
1278: The user should pass in an array of pointers to char, to hold all the
1279: strings returned by this function.
1281: The user is responsible for deallocating the strings that are
1282: returned.
1284: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1286: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1287: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1288: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1289: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1290: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1291: `PetscOptionsFList()`, `PetscOptionsEList()`
1292: M*/
1293: #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1295: /*MC
1296: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1297: option in the database. The values must be separated with commas with
1298: no intervening spaces.
1300: Synopsis:
1301: #include <petscoptions.h>
1302: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1304: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1306: Input Parameters:
1307: + opt - the option one is seeking
1308: . text - short string describing option
1309: . man - manual page for option
1310: - n - maximum number of values allowed in the value array
1312: Output Parameters:
1313: + value - location to copy values
1314: . n - actual number of values found
1315: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1317: Level: beginner
1319: Notes:
1320: The user should pass in an array of `PetscBool`
1322: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1324: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1325: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1326: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1327: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1328: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1329: `PetscOptionsFList()`, `PetscOptionsEList()`
1330: M*/
1331: #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1333: /*MC
1334: PetscOptionsEnumArray - Gets an array of enum values for a particular
1335: option in the database.
1337: Synopsis:
1338: #include <petscoptions.h>
1339: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1341: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1343: Input Parameters:
1344: + opt - the option one is seeking
1345: . text - short string describing option
1346: . man - manual page for option
1347: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1348: - n - maximum number of values allowed in the value array
1350: Output Parameters:
1351: + value - location to copy values
1352: . n - actual number of values found
1353: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1355: Level: beginner
1357: Notes:
1358: The array must be passed as a comma separated list.
1360: There must be no intervening spaces between the values.
1362: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1364: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1365: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1366: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1367: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1368: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1369: `PetscOptionsFList()`, `PetscOptionsEList()`
1370: M*/
1371: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1373: /*MC
1374: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1376: Prints a deprecation warning, unless an option is supplied to suppress.
1378: Logically Collective
1380: Input Parameters:
1381: + oldname - the old, deprecated option
1382: . newname - the new option, or `NULL` if option is purely removed
1383: . version - a string describing the version of first deprecation, e.g. "3.9"
1384: - info - additional information string, or `NULL`.
1386: Options Database Key:
1387: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1389: Level: developer
1391: Notes:
1392: If `newname` is provided then the options database will automatically check the database for `oldname`.
1394: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1395: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1396: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1398: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1399: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1400: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1401: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1402: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1404: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1405: M*/
1406: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1408: /*MC
1409: PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1411: Prints a deprecation warning, unless an option is supplied to suppress.
1413: Logically Collective
1415: Input Parameters:
1416: + oldname - the old, deprecated option
1417: . newname - the new option, or `NULL` if option is purely removed
1418: . version - a string describing the version of first deprecation, e.g. "3.9"
1419: - info - additional information string, or `NULL`.
1421: Options Database Key:
1422: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1424: Level: developer
1426: Notes:
1427: If `newname` is provided then the options database will automatically check the database for `oldname`.
1429: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1430: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1431: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1433: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1434: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1435: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1436: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1438: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1439: M*/
1440: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1441: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1443: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1444: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1445: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1446: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1447: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1448: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1449: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems *, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1450: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1451: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1452: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1453: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1454: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1455: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1456: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1457: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1458: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1459: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1460: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1461: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1462: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *, const char[], const char[], const char[], const char[]);
1464: PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void);
1466: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems *, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1467: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems *);
1468: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1470: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);