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, const char *const *);
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 _n_PetscOptionItems *PetscOptionItems;
126: struct _n_PetscOptionItems {
127: PetscInt count;
128: PetscOptionItem next;
129: char *prefix, *pprefix;
130: char *title;
131: MPI_Comm comm;
132: PetscBool printhelp, changedmethod, alreadyprinted;
133: PetscObject object;
134: PetscOptions options;
135: };
137: #if defined(PETSC_CLANG_STATIC_ANALYZER)
138: extern PetscOptionItems PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
139: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
140: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
141: PetscErrorCode PetscOptionsEnd(void);
142: #else
143: /*MC
144: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
145: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
146: use `PetscObjectOptionsBegin()` rather than this call.
148: Synopsis:
149: #include <petscoptions.h>
150: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
152: Collective
154: Input Parameters:
155: + comm - communicator that shares GUI
156: . prefix - options prefix for all options displayed on window (optional)
157: . title - short descriptive text, for example "Krylov Solver Options"
158: - mansec - section of manual pages for options, for example `KSP` (optional)
160: Level: intermediate
162: Notes:
163: This is a macro that handles its own error checking, it does not return an error code.
165: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
167: One can add subheadings with `PetscOptionsHeadBegin()`.
169: Developer Notes:
170: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
171: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
172: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
173: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
174: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
175: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
176: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
177: default values are printed if -help was given.
178: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
179: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
180: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
181: currently set.
183: Fortran Note:
184: Returns ierr error code as the final argument per PETSc Fortran API
186: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
187: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
188: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
189: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
190: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
191: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
192: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
193: M*/
194: #define PetscOptionsBegin(comm, prefix, mess, sec) \
195: do { \
196: struct _n_PetscOptionItems PetscOptionsObjectBase; \
197: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
198: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
199: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
200: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
202: /*MC
203: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
204: displayed on the same window of a GUI that allows the user to set the options interactively.
206: Synopsis:
207: #include <petscoptions.h>
208: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
210: Collective
212: Input Parameter:
213: . obj - object to set options for
215: Level: intermediate
217: Notes:
218: This is a macro that handles its own error checking, it does not return an error code.
220: Needs to be ended by a call the `PetscOptionsEnd()`
222: Can add subheadings with `PetscOptionsHeadBegin()`
224: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
225: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
226: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
227: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
228: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
229: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
230: `PetscOptionsFList()`, `PetscOptionsEList()`
231: M*/
232: #define PetscObjectOptionsBegin(obj) \
233: do { \
234: struct _n_PetscOptionItems PetscOptionsObjectBase; \
235: PetscOptionItems PetscOptionsObject = &PetscOptionsObjectBase; \
236: PetscOptionsObject->options = ((PetscObject)obj)->options; \
237: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
238: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
240: /*MC
241: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
242: displayed on the same window of a GUI that allows the user to set the options interactively.
244: Synopsis:
245: #include <petscoptions.h>
246: PetscErrorCode PetscOptionsEnd(void)
248: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
250: Level: intermediate
252: Notes:
253: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
255: This is a macro that handles its own error checking, it does not return an error code.
257: Fortran Note:
258: Returns ierr error code as the final argument per PETSc Fortran API
260: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
261: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
262: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
263: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
264: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
265: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
266: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
267: M*/
268: #define PetscOptionsEnd() \
269: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
270: } \
271: } \
272: while (0)
273: #endif /* PETSC_CLANG_STATIC_ANALYZER */
275: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems, MPI_Comm, const char[], const char[], const char[]);
276: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems);
277: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems);
278: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems, const char[]);
280: #if defined(PETSC_CLANG_STATIC_ANALYZER)
281: template <typename... T>
282: void PetscOptionsHeadBegin(T...);
283: void PetscOptionsHeadEnd(void);
284: template <typename... T>
285: PetscErrorCode PetscOptionsEnum(T...);
286: template <typename... T>
287: PetscErrorCode PetscOptionsInt(T...);
288: template <typename... T>
289: PetscErrorCode PetscOptionsBoundedInt(T...);
290: template <typename... T>
291: PetscErrorCode PetscOptionsRangeInt(T...);
292: template <typename... T>
293: PetscErrorCode PetscOptionsReal(T...);
294: template <typename... T>
295: PetscErrorCode PetscOptionsScalar(T...);
296: template <typename... T>
297: PetscErrorCode PetscOptionsName(T...);
298: template <typename... T>
299: PetscErrorCode PetscOptionsString(T...);
300: template <typename... T>
301: PetscErrorCode PetscOptionsBool(T...);
302: template <typename... T>
303: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
304: template <typename... T>
305: PetscErrorCode PetscOptionsBoolGroup(T...);
306: template <typename... T>
307: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
308: template <typename... T>
309: PetscErrorCode PetscOptionsFList(T...);
310: template <typename... T>
311: PetscErrorCode PetscOptionsEList(T...);
312: template <typename... T>
313: PetscErrorCode PetscOptionsRealArray(T...);
314: template <typename... T>
315: PetscErrorCode PetscOptionsScalarArray(T...);
316: template <typename... T>
317: PetscErrorCode PetscOptionsIntArray(T...);
318: template <typename... T>
319: PetscErrorCode PetscOptionsStringArray(T...);
320: template <typename... T>
321: PetscErrorCode PetscOptionsBoolArray(T...);
322: template <typename... T>
323: PetscErrorCode PetscOptionsEnumArray(T...);
324: template <typename... T>
325: PetscErrorCode PetscOptionsDeprecated(T...);
326: template <typename... T>
327: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
328: #else
329: /*MC
330: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
331: in `KSPSetFromOptions_GMRES()`.
333: Logically Collective on the communicator passed in `PetscOptionsBegin()`
335: Input Parameter:
336: . head - the heading text
338: Level: developer
340: Notes:
341: Handles errors directly, hence does not return an error code
343: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
345: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
347: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
348: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
349: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
350: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
351: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
352: `PetscOptionsFList()`, `PetscOptionsEList()`
353: M*/
354: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
355: do { \
356: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
357: } while (0)
359: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
361: /*MC
362: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
363: See, for example, `KSPSetFromOptions_GMRES()`.
365: Synopsis:
366: #include <petscoptions.h>
367: PetscErrorCode PetscOptionsHeadEnd(void)
369: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
371: Level: intermediate
373: Notes:
374: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
376: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
378: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
379: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
380: from the function.
382: This is only for use with the PETSc options GUI
384: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
385: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
386: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
387: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
388: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
389: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
390: M*/
391: #define PetscOptionsHeadEnd() \
392: do { \
393: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
394: } while (0)
396: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
398: /*MC
399: PetscOptionsEnum - Gets the enum value for a particular option in the database.
401: Synopsis:
402: #include <petscoptions.h>
403: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
405: Logically Collective on the communicator passed in `PetscOptionsBegin()`
407: Input Parameters:
408: + opt - option name
409: . text - short string that describes the option
410: . man - manual page with additional information on option
411: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
412: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
413: .vb
414: PetscOptionsEnum(..., obj->value,&object->value,...) or
415: value = defaultvalue
416: PetscOptionsEnum(..., value,&value,&set);
417: if (set) {
418: .ve
420: Output Parameters:
421: + value - the value to return
422: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
424: Level: beginner
426: Notes:
427: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
429: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
431: If the user does not supply the option at all `value` is NOT changed. Thus
432: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
434: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
436: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
437: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
438: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
439: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
440: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
441: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
442: `PetscOptionsFList()`, `PetscOptionsEList()`
443: M*/
444: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
446: /*MC
447: PetscOptionsInt - Gets the integer value for a particular option in the database.
449: Synopsis:
450: #include <petscoptions.h>
451: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
453: Logically Collective on the communicator passed in `PetscOptionsBegin()`
455: Input Parameters:
456: + opt - option name
457: . text - short string that describes the option
458: . man - manual page with additional information on option
459: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
460: .vb
461: PetscOptionsInt(..., obj->value, &obj->value, ...) or
462: value = defaultvalue
463: PetscOptionsInt(..., value, &value, &set);
464: if (set) {
465: .ve
467: Output Parameters:
468: + value - the integer value to return
469: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
471: Level: beginner
473: Notes:
474: If the user does not supply the option at all `value` is NOT changed. Thus
475: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
477: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
479: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
481: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
482: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
483: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
484: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
485: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
486: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
487: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
488: M*/
489: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_INT_MIN, PETSC_INT_MAX)
491: /*MC
492: PetscOptionsMPIInt - Gets the MPI integer value for a particular option in the database.
494: Synopsis:
495: #include <petscoptions.h>
496: PetscErrorCode PetscOptionsMPIInt(const char opt[], const char text[], const char man[], PetscMPIInt currentvalue, PetscMPIInt *value, PetscBool *set)
498: Logically Collective on the communicator passed in `PetscOptionsBegin()`
500: Input Parameters:
501: + opt - option name
502: . text - short string that describes the option
503: . man - manual page with additional information on option
504: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
505: .vb
506: PetscOptionsInt(..., obj->value, &obj->value, ...) or
507: value = defaultvalue
508: PetscOptionsInt(..., value, &value, &set);
509: if (set) {
510: .ve
512: Output Parameters:
513: + value - the MPI integer value to return
514: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
516: Level: beginner
518: Notes:
519: If the user does not supply the option at all `value` is NOT changed. Thus
520: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
522: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
524: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
526: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
527: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
528: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
529: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
530: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
531: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
532: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
533: M*/
534: #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)
536: /*MC
537: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
539: Synopsis:
540: #include <petscoptions.h>
541: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
543: Logically Collective on the communicator passed in `PetscOptionsBegin()`
545: Input Parameters:
546: + opt - option name
547: . text - short string that describes the option
548: . man - manual page with additional information on option
549: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
550: .vb
551: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
552: .ve
553: or
554: .vb
555: value = defaultvalue
556: PetscOptionsBoundedInt(..., value, &value, &set, ...);
557: if (set) {
558: .ve
559: - bound - the requested value should be greater than or equal to this bound or an error is generated
561: Output Parameters:
562: + value - the integer value to return
563: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
565: Level: beginner
567: Notes:
568: If the user does not supply the option at all `value` is NOT changed. Thus
569: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
571: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
573: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
575: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
576: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
577: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
578: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
579: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
580: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
581: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
582: M*/
583: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_INT_MAX)
585: /*MC
586: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
588: Synopsis:
589: #include <petscoptions.h>
590: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
592: Logically Collective on the communicator passed in `PetscOptionsBegin()`
594: Input Parameters:
595: + opt - option name
596: . text - short string that describes the option
597: . man - manual page with additional information on option
598: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
599: .vb
600: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
601: .ve
602: or
603: .vb
604: value = defaultvalue
605: PetscOptionsRangeInt(..., value, &value, &set, ...);
606: if (set) {
607: .ve
608: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
609: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
611: Output Parameters:
612: + value - the integer value to return
613: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
615: Level: beginner
617: Notes:
618: If the user does not supply the option at all `value` is NOT changed. Thus
619: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
621: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
623: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
625: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
626: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
627: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
628: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
629: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
630: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
631: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
632: M*/
633: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
635: /*MC
636: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
638: Synopsis:
639: #include <petscoptions.h>
640: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
642: Logically Collective on the communicator passed in `PetscOptionsBegin()`
644: Input Parameters:
645: + opt - option name
646: . text - short string that describes the option
647: . man - manual page with additional information on option
648: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
649: .vb
650: PetscOptionsReal(..., obj->value,&obj->value,...) or
651: value = defaultvalue
652: PetscOptionsReal(..., value,&value,&set);
653: if (set) {
654: .ve
656: Output Parameters:
657: + value - the value to return
658: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
660: Level: beginner
662: Notes:
663: If the user does not supply the option at all `value` is NOT changed. Thus
664: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
666: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
668: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
670: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
671: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
672: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
673: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
674: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
675: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
676: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
677: M*/
678: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
680: /*MC
681: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
683: Synopsis:
684: #include <petscoptions.h>
685: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
687: Logically Collective on the communicator passed in `PetscOptionsBegin()`
689: Input Parameters:
690: + opt - option name
691: . text - short string that describes the option
692: . man - manual page with additional information on option
693: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
694: .vb
695: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
696: .ve
697: or
698: .vb
699: value = defaultvalue
700: PetscOptionsBoundedReal(..., value, &value, &set, ...);
701: if (set) {
702: .ve
703: - bound - the requested value should be greater than or equal to this bound or an error is generated
705: Output Parameters:
706: + value - the real value to return
707: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
709: Level: beginner
711: Notes:
712: If the user does not supply the option at all `value` is NOT changed. Thus
713: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
715: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
717: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
719: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
720: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
721: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
722: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
723: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
724: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
725: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
726: M*/
727: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
729: /*MC
730: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
732: Synopsis:
733: #include <petscoptions.h>
734: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
736: Logically Collective on the communicator passed in `PetscOptionsBegin()`
738: Input Parameters:
739: + opt - option name
740: . text - short string that describes the option
741: . man - manual page with additional information on option
742: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
743: .vb
744: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
745: .ve
746: or
747: .vb
748: value = defaultvalue
749: PetscOptionsRangeReal(..., value, &value, &set, ...);
750: if (set) {
751: .ve
752: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
753: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
755: Output Parameters:
756: + value - the value to return
757: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
759: Level: beginner
761: Notes:
762: If the user does not supply the option at all `value` is NOT changed. Thus
763: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
765: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
767: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
769: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
770: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
771: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
772: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
773: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
774: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
775: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
776: M*/
777: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
779: /*MC
780: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
782: Synopsis:
783: #include <petscoptions.h>
784: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
786: Logically Collective on the communicator passed in `PetscOptionsBegin()`
788: Input Parameters:
789: + opt - option name
790: . text - short string that describes the option
791: . man - manual page with additional information on option
792: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
793: .vb
794: PetscOptionsScalar(..., obj->value,&obj->value,...) or
795: value = defaultvalue
796: PetscOptionsScalar(..., value,&value,&set);
797: if (set) {
798: .ve
800: Output Parameters:
801: + value - the value to return
802: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
804: Level: beginner
806: Notes:
807: If the user does not supply the option at all `value` is NOT changed. Thus
808: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
810: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
812: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
814: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
815: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
816: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
817: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
818: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
819: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
820: `PetscOptionsFList()`, `PetscOptionsEList()`
821: M*/
822: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
824: /*MC
825: 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
826: its value is set to false.
828: Synopsis:
829: #include <petscoptions.h>
830: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
832: Logically Collective on the communicator passed in `PetscOptionsBegin()`
834: Input Parameters:
835: + opt - option name
836: . text - short string that describes the option
837: - man - manual page with additional information on option
839: Output Parameter:
840: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
842: Level: beginner
844: Note:
845: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
847: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
848: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
849: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
850: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
851: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
852: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
853: `PetscOptionsFList()`, `PetscOptionsEList()`
854: M*/
855: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
857: /*MC
858: PetscOptionsString - Gets the string value for a particular option in the database.
860: Synopsis:
861: #include <petscoptions.h>
862: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
864: Logically Collective on the communicator passed in `PetscOptionsBegin()`
866: Input Parameters:
867: + opt - option name
868: . text - short string that describes the option
869: . man - manual page with additional information on option
870: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
871: - len - length of the result string including null terminator
873: Output Parameters:
874: + value - the value to return
875: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
877: Level: beginner
879: Notes:
880: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
882: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
884: If the user does not supply the option at all `value` is NOT changed. Thus
885: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
887: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
889: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
890: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
891: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
892: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
893: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
894: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
895: `PetscOptionsFList()`, `PetscOptionsEList()`
896: M*/
897: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
899: /*MC
900: PetscOptionsBool - Determines if a particular option is in the database with a true or false
902: Synopsis:
903: #include <petscoptions.h>
904: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
906: Logically Collective on the communicator passed in `PetscOptionsBegin()`
908: Input Parameters:
909: + opt - option name
910: . text - short string that describes the option
911: . man - manual page with additional information on option
912: - currentvalue - the current value
914: Output Parameters:
915: + flg - `PETSC_TRUE` or `PETSC_FALSE`
916: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`, pass `NULL` if not needed
918: Level: beginner
920: Notes:
921: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
922: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
924: 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`
925: is equivalent to `-requested_bool true`
927: If the user does not supply the option at all `flg` is NOT changed. Thus
928: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
930: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
932: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
933: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
934: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
935: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
936: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
937: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
938: `PetscOptionsFList()`, `PetscOptionsEList()`
939: M*/
940: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
942: /*MC
943: PetscOptionsBool3 - Determines if a particular option is in the database with a true, false, or unknown
945: Synopsis:
946: #include <petscoptions.h>
947: PetscErrorCode PetscOptionsBool3(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool3 *flg, 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
955: - currentvalue - the current value
957: Output Parameters:
958: + flg - `PETSC_BOOL3_TRUE`, `PETSC_BOOL3_FALSE`, or `PETSC_BOOL3_UNKNOWN`
959: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
961: Level: beginner
963: Notes:
964: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
965: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
967: 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`
968: is equivalent to `-requested_bool true`
970: If the user does not supply the option at all `flg` is NOT changed. Thus
971: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
973: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
975: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
976: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
977: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
978: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
979: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
980: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
981: `PetscOptionsFList()`, `PetscOptionsEList()`
982: M*/
983: #define PetscOptionsBool3(opt, text, man, currentvalue, value, set) PetscOptionsBool3_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
985: /*MC
986: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
987: which at most a single value can be true.
989: Synopsis:
990: #include <petscoptions.h>
991: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
993: Logically Collective on the communicator passed in `PetscOptionsBegin()`
995: Input Parameters:
996: + opt - option name
997: . text - short string that describes the option
998: - man - manual page with additional information on option
1000: Output Parameter:
1001: . set - whether that option was set or not
1003: Level: intermediate
1005: Notes:
1006: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1008: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
1010: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1011: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1012: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1013: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1014: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1015: `PetscOptionsFList()`, `PetscOptionsEList()`
1016: M*/
1017: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
1019: /*MC
1020: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
1021: which at most a single value can be true.
1023: Synopsis:
1024: #include <petscoptions.h>
1025: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
1027: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1029: Input Parameters:
1030: + opt - option name
1031: . text - short string that describes the option
1032: - man - manual page with additional information on option
1034: Output Parameter:
1035: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1037: Level: intermediate
1039: Notes:
1040: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1042: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
1044: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1045: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1046: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1047: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1048: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1049: `PetscOptionsFList()`, `PetscOptionsEList()`
1050: M*/
1051: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
1053: /*MC
1054: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
1055: which at most a single value can be true.
1057: Synopsis:
1058: #include <petscoptions.h>
1059: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
1061: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1063: Input Parameters:
1064: + opt - option name
1065: . text - short string that describes the option
1066: - man - manual page with additional information on option
1068: Output Parameter:
1069: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1071: Level: intermediate
1073: Notes:
1074: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1076: Must follow a `PetscOptionsBoolGroupBegin()`
1078: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1079: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1080: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1081: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1082: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1083: `PetscOptionsFList()`, `PetscOptionsEList()`
1084: M*/
1085: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
1087: /*MC
1088: PetscOptionsFList - Puts a list of option values that a single one may be selected from
1090: Synopsis:
1091: #include <petscoptions.h>
1092: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1094: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1096: Input Parameters:
1097: + opt - option name
1098: . ltext - short string that describes the option
1099: . man - manual page with additional information on option
1100: . list - the possible choices
1101: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1102: .vb
1103: PetscOptionsFlist(..., obj->value,value,len,&set);
1104: if (set) {
1105: .ve
1106: - len - the length of the character array value
1108: Output Parameters:
1109: + value - the value to return
1110: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1112: Level: intermediate
1114: Notes:
1115: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1117: If the user does not supply the option at all `value` is NOT changed. Thus
1118: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1120: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1122: See `PetscOptionsEList()` for when the choices are given in a string array
1124: To get a listing of all currently specified options,
1125: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1127: Developer Note:
1128: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1130: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1131: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1132: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1133: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1134: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1135: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1136: M*/
1137: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1139: /*MC
1140: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1142: Synopsis:
1143: #include <petscoptions.h>
1144: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1146: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1148: Input Parameters:
1149: + opt - option name
1150: . ltext - short string that describes the option
1151: . man - manual page with additional information on option
1152: . list - the possible choices (one of these must be selected, anything else is invalid)
1153: . ntext - number of choices
1154: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1155: .vb
1156: PetscOptionsEList(..., obj->value,&value,&set);
1157: .ve if (set) {
1159: Output Parameters:
1160: + value - the index of the value to return
1161: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1163: Level: intermediate
1165: Notes:
1166: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1168: If the user does not supply the option at all `value` is NOT changed. Thus
1169: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1171: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1173: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1174: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1175: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1176: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1177: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1178: `PetscOptionsFList()`, `PetscOptionsEnum()`
1179: M*/
1180: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1182: /*MC
1183: PetscOptionsRealArray - Gets an array of double values for a particular
1184: option in the database. The values must be separated with commas with
1185: no intervening spaces.
1187: Synopsis:
1188: #include <petscoptions.h>
1189: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1191: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1193: Input Parameters:
1194: + opt - the option one is seeking
1195: . text - short string describing option
1196: . man - manual page for option
1197: - n - maximum number of values that value has room for
1199: Output Parameters:
1200: + value - location to copy values
1201: . n - actual number of values found
1202: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1204: Level: beginner
1206: Note:
1207: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1209: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1210: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1211: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1212: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1213: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1214: `PetscOptionsFList()`, `PetscOptionsEList()`
1215: M*/
1216: #define PetscOptionsRealArray(opt, text, man, value, n, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1218: /*MC
1219: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1220: option in the database. The values must be separated with commas with
1221: no intervening spaces.
1223: Synopsis:
1224: #include <petscoptions.h>
1225: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1227: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1229: Input Parameters:
1230: + opt - the option one is seeking
1231: . text - short string describing option
1232: . man - manual page for option
1233: - n - maximum number of values allowed in the value array
1235: Output Parameters:
1236: + value - location to copy values
1237: . n - actual number of values found
1238: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1240: Level: beginner
1242: Note:
1243: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1245: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1246: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1247: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1248: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1249: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1250: `PetscOptionsFList()`, `PetscOptionsEList()`
1251: M*/
1252: #define PetscOptionsScalarArray(opt, text, man, value, n, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1254: /*MC
1255: PetscOptionsIntArray - Gets an array of integers for a particular
1256: option in the database.
1258: Synopsis:
1259: #include <petscoptions.h>
1260: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1262: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1264: Input Parameters:
1265: + opt - the option one is seeking
1266: . text - short string describing option
1267: . man - manual page for option
1268: - n - maximum number of values
1270: Output Parameters:
1271: + value - location to copy values
1272: . n - actual number of values found
1273: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1275: Level: beginner
1277: Notes:
1278: The array can be passed as
1279: + a comma separated list - 0,1,2,3,4,5,6,7
1280: . a range (start\-end+1) - 0-8
1281: . a range with given increment (start\-end+1:inc) - 0-7:2
1282: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1284: There must be no intervening spaces between the values.
1286: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1288: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1289: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1290: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1291: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1292: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1293: `PetscOptionsFList()`, `PetscOptionsEList()`
1294: M*/
1295: #define PetscOptionsIntArray(opt, text, man, value, n, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1297: /*MC
1298: PetscOptionsStringArray - Gets an array of string values for a particular
1299: option in the database. The values must be separated with commas with
1300: no intervening spaces.
1302: Synopsis:
1303: #include <petscoptions.h>
1304: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1306: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1308: Input Parameters:
1309: + opt - the option one is seeking
1310: . text - short string describing option
1311: . man - manual page for option
1312: - n - maximum number of strings
1314: Output Parameters:
1315: + value - location to copy strings
1316: . n - actual number of strings found
1317: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1319: Level: beginner
1321: Notes:
1322: The user should pass in an array of pointers to char, to hold all the
1323: strings returned by this function.
1325: The user is responsible for deallocating the strings that are
1326: returned.
1328: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1330: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1331: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1332: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1333: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1334: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1335: `PetscOptionsFList()`, `PetscOptionsEList()`
1336: M*/
1337: #define PetscOptionsStringArray(opt, text, man, value, n, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1339: /*MC
1340: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1341: option in the database. The values must be separated with commas with
1342: no intervening spaces.
1344: Synopsis:
1345: #include <petscoptions.h>
1346: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1348: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1350: Input Parameters:
1351: + opt - the option one is seeking
1352: . text - short string describing option
1353: . man - manual page for option
1354: - n - maximum number of values allowed in the value array
1356: Output Parameters:
1357: + value - location to copy values
1358: . n - actual number of values found
1359: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1361: Level: beginner
1363: Notes:
1364: The user should pass in an array of `PetscBool`
1366: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1368: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1369: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1370: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1371: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1372: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1373: `PetscOptionsFList()`, `PetscOptionsEList()`
1374: M*/
1375: #define PetscOptionsBoolArray(opt, text, man, value, n, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, value, n, set)
1377: /*MC
1378: PetscOptionsEnumArray - Gets an array of enum values for a particular
1379: option in the database.
1381: Synopsis:
1382: #include <petscoptions.h>
1383: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1385: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1387: Input Parameters:
1388: + opt - the option one is seeking
1389: . text - short string describing option
1390: . man - manual page for option
1391: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1392: - n - maximum number of values allowed in the value array
1394: Output Parameters:
1395: + value - location to copy values
1396: . n - actual number of values found
1397: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1399: Level: beginner
1401: Notes:
1402: The array must be passed as a comma separated list.
1404: There must be no intervening spaces between the values.
1406: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1408: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1409: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1410: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1411: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1412: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1413: `PetscOptionsFList()`, `PetscOptionsEList()`
1414: M*/
1415: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1417: /*MC
1418: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1420: Prints a deprecation warning, unless an option is supplied to suppress.
1422: Logically Collective
1424: Input Parameters:
1425: + oldname - the old, deprecated option
1426: . newname - the new option, or `NULL` if option is purely removed
1427: . version - a string describing the version of first deprecation, e.g. "3.9"
1428: - info - additional information string, or `NULL`.
1430: Options Database Key:
1431: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1433: Level: developer
1435: Notes:
1436: If `newname` is provided then the options database will automatically check the database for `oldname`.
1438: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1439: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1440: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1442: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1443: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1444: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1445: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1446: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1448: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1449: M*/
1450: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1452: /*MC
1453: PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1455: Prints a deprecation warning, unless an option is supplied to suppress.
1457: Logically Collective
1459: Input Parameters:
1460: + oldname - the old, deprecated option
1461: . newname - the new option, or `NULL` if option is purely removed
1462: . version - a string describing the version of first deprecation, e.g. "3.9"
1463: - info - additional information string, or `NULL`.
1465: Options Database Key:
1466: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1468: Level: developer
1470: Notes:
1471: If `newname` is provided then the options database will automatically check the database for `oldname`.
1473: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1474: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1475: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1477: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1478: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1479: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1480: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1482: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1483: M*/
1484: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1485: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1487: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1488: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1489: PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt);
1490: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1491: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1492: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1493: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1494: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1495: PETSC_EXTERN PetscErrorCode PetscOptionsBool3_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool3, PetscBool3 *, PetscBool *);
1496: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1497: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1498: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *);
1499: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1500: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1501: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1502: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1503: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1504: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1505: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1506: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1507: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]);
1509: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1510: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems);
1511: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1513: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);