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 PetscOptionsGetInt(PetscOptions, const char[], const char[], PetscInt *, PetscBool *);
32: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnum(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscBool *);
33: PETSC_EXTERN PetscErrorCode PetscOptionsGetEList(PetscOptions, const char[], const char[], const char *const *, PetscInt, PetscInt *, PetscBool *);
34: PETSC_EXTERN PetscErrorCode PetscOptionsGetReal(PetscOptions, const char[], const char[], PetscReal *, PetscBool *);
35: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalar(PetscOptions, const char[], const char[], PetscScalar *, PetscBool *);
36: PETSC_EXTERN PetscErrorCode PetscOptionsGetString(PetscOptions, const char[], const char[], char[], size_t, PetscBool *);
38: PETSC_EXTERN PetscErrorCode PetscOptionsGetBoolArray(PetscOptions, const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
39: PETSC_EXTERN PetscErrorCode PetscOptionsGetEnumArray(PetscOptions, const char[], const char[], const char *const *, PetscEnum *, PetscInt *, PetscBool *);
40: PETSC_EXTERN PetscErrorCode PetscOptionsGetIntArray(PetscOptions, const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
41: PETSC_EXTERN PetscErrorCode PetscOptionsGetRealArray(PetscOptions, const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
42: PETSC_EXTERN PetscErrorCode PetscOptionsGetScalarArray(PetscOptions, const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
43: PETSC_EXTERN PetscErrorCode PetscOptionsGetStringArray(PetscOptions, const char[], const char[], char *[], PetscInt *, PetscBool *);
45: PETSC_EXTERN PetscErrorCode PetscOptionsValidKey(const char[], PetscBool *);
46: PETSC_EXTERN PetscErrorCode PetscOptionsSetAlias(PetscOptions, const char[], const char[]);
47: PETSC_EXTERN PetscErrorCode PetscOptionsSetValue(PetscOptions, const char[], const char[]);
48: PETSC_EXTERN PetscErrorCode PetscOptionsClearValue(PetscOptions, const char[]);
49: PETSC_EXTERN PetscErrorCode PetscOptionsFindPair(PetscOptions, const char[], const char[], const char *[], PetscBool *);
51: PETSC_EXTERN PetscErrorCode PetscOptionsGetAll(PetscOptions, char *[]);
52: PETSC_EXTERN PetscErrorCode PetscOptionsAllUsed(PetscOptions, PetscInt *);
53: PETSC_EXTERN PetscErrorCode PetscOptionsUsed(PetscOptions, const char[], PetscBool *);
54: PETSC_EXTERN PetscErrorCode PetscOptionsLeft(PetscOptions);
55: PETSC_EXTERN PetscErrorCode PetscOptionsLeftGet(PetscOptions, PetscInt *, char ***, char ***);
56: PETSC_EXTERN PetscErrorCode PetscOptionsLeftRestore(PetscOptions, PetscInt *, char ***, char ***);
57: PETSC_EXTERN PetscErrorCode PetscOptionsView(PetscOptions, PetscViewer);
59: PETSC_EXTERN PetscErrorCode PetscOptionsReject(PetscOptions, const char[], const char[], const char[]);
60: PETSC_EXTERN PetscErrorCode PetscOptionsInsert(PetscOptions, int *, char ***, const char[]);
61: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFile(MPI_Comm, PetscOptions, const char[], PetscBool);
62: PETSC_EXTERN PetscErrorCode PetscOptionsInsertFileYAML(MPI_Comm, PetscOptions, const char[], PetscBool);
63: PETSC_EXTERN PetscErrorCode PetscOptionsInsertString(PetscOptions, const char[]);
64: PETSC_EXTERN PetscErrorCode PetscOptionsInsertStringYAML(PetscOptions, const char[]);
65: PETSC_EXTERN PetscErrorCode PetscOptionsInsertArgs(PetscOptions, int, char **);
66: PETSC_EXTERN PetscErrorCode PetscOptionsClear(PetscOptions);
67: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPush(PetscOptions, const char[]);
68: PETSC_EXTERN PetscErrorCode PetscOptionsPrefixPop(PetscOptions);
70: PETSC_EXTERN PetscErrorCode PetscOptionsGetenv(MPI_Comm, const char[], char[], size_t, PetscBool *);
71: PETSC_EXTERN PetscErrorCode PetscOptionsStringToBool(const char[], PetscBool *);
72: PETSC_EXTERN PetscErrorCode PetscOptionsStringToInt(const char[], PetscInt *);
73: PETSC_EXTERN PetscErrorCode PetscOptionsStringToReal(const char[], PetscReal *);
74: PETSC_EXTERN PetscErrorCode PetscOptionsStringToScalar(const char[], PetscScalar *);
76: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*)(const char[], const char[], PetscOptionSource, void *), void *, PetscErrorCode (*)(void **));
77: PETSC_EXTERN PetscErrorCode PetscOptionsMonitorDefault(const char[], const char[], PetscOptionSource, void *);
79: PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions);
80: PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *);
82: PETSC_EXTERN PetscBool PetscOptionsPublish;
84: /*
85: See manual page for PetscOptionsBegin()
87: PetscOptionsItem and PetscOptionsItems are a single option (such as ksp_type) and a collection of such single
88: options being handled with a PetscOptionsBegin/End()
90: */
91: typedef enum {
92: OPTION_INT,
93: OPTION_BOOL,
94: OPTION_REAL,
95: OPTION_FLIST,
96: OPTION_STRING,
97: OPTION_REAL_ARRAY,
98: OPTION_SCALAR_ARRAY,
99: OPTION_HEAD,
100: OPTION_INT_ARRAY,
101: OPTION_ELIST,
102: OPTION_BOOL_ARRAY,
103: OPTION_STRING_ARRAY
104: } PetscOptionType;
106: typedef struct _n_PetscOptionItem *PetscOptionItem;
107: struct _n_PetscOptionItem {
108: char *option;
109: char *text;
110: void *data; /* used to hold the default value and then any value it is changed to by GUI */
111: PetscFunctionList flist; /* used for available values for PetscOptionsList() */
112: const char *const *list; /* used for available values for PetscOptionsEList() */
113: char nlist; /* number of entries in list */
114: char *man;
115: size_t arraylength; /* number of entries in data in the case that it is an array (of PetscInt etc) */
116: PetscBool set; /* the user has changed this value in the GUI */
117: PetscOptionType type;
118: PetscOptionItem next;
119: char *pman;
120: void *edata;
121: };
123: typedef struct _p_PetscOptionItems {
124: PetscInt count;
125: PetscOptionItem next;
126: char *prefix, *pprefix;
127: char *title;
128: MPI_Comm comm;
129: PetscBool printhelp, changedmethod, alreadyprinted;
130: PetscObject object;
131: PetscOptions options;
132: } PetscOptionItems;
134: #if defined(PETSC_CLANG_STATIC_ANALYZER)
135: extern PetscOptionItems *PetscOptionsObject; /* declare this so that the PetscOptions stubs work */
136: PetscErrorCode PetscOptionsBegin(MPI_Comm, const char *, const char *, const char *);
137: PetscErrorCode PetscObjectOptionsBegin(PetscObject);
138: PetscErrorCode PetscOptionsEnd(void);
139: #else
140: /*MC
141: PetscOptionsBegin - Begins a set of queries on the options database that are related and should be
142: displayed on the same window of a GUI that allows the user to set the options interactively. Often one should
143: use `PetscObjectOptionsBegin()` rather than this call.
145: Synopsis:
146: #include <petscoptions.h>
147: PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[])
149: Collective
151: Input Parameters:
152: + comm - communicator that shares GUI
153: . prefix - options prefix for all options displayed on window (optional)
154: . title - short descriptive text, for example "Krylov Solver Options"
155: - mansec - section of manual pages for options, for example `KSP` (optional)
157: Level: intermediate
159: Notes:
160: This is a macro that handles its own error checking, it does not return an error code.
162: The set of queries needs to be ended by a call to `PetscOptionsEnd()`.
164: One can add subheadings with `PetscOptionsHeadBegin()`.
166: Developer Notes:
167: `PetscOptionsPublish` is set in `PetscOptionsCheckInitial_Private()` with `-saws_options`. When `PetscOptionsPublish` is set the
168: loop between `PetscOptionsBegin()` and `PetscOptionsEnd()` is run THREE times with `PetscOptionsPublishCount` of values -1,0,1.
169: Otherwise the loop is run ONCE with a `PetscOptionsPublishCount` of 1.
170: + \-1 - `PetscOptionsInt()` etc. just call `PetscOptionsGetInt()` etc.
171: . 0 - The GUI objects are created in `PetscOptionsInt()` etc. and displayed in `PetscOptionsEnd()` and the options
172: database updated with user changes; `PetscOptionsGetInt()` etc. are also called.
173: - 1 - `PetscOptionsInt()` etc. again call `PetscOptionsGetInt()` etc. (possibly getting new values), in addition the help message and
174: default values are printed if -help was given.
175: When `PetscOptionsObject.changedmethod` is set this causes `PetscOptionsPublishCount` to be reset to -2 (so in the next loop iteration it is -1)
176: and the whole process is repeated. This is to handle when, for example, the `KSPType` is changed thus changing the list of
177: options available so they need to be redisplayed so the user can change the. Changing `PetscOptionsObjects.changedmethod` is never
178: currently set.
180: Fortran Note:
181: Returns ierr error code per PETSc Fortran API
183: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
184: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
185: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
186: `PetscOptionsName()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
187: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
188: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
189: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
190: M*/
191: #define PetscOptionsBegin(comm, prefix, mess, sec) \
192: do { \
193: PetscOptionItems PetscOptionsObjectBase; \
194: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
195: PetscCall(PetscMemzero(PetscOptionsObject, sizeof(*PetscOptionsObject))); \
196: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
197: PetscCall(PetscOptionsBegin_Private(PetscOptionsObject, comm, prefix, mess, sec))
199: /*MC
200: PetscObjectOptionsBegin - Begins a set of queries on the options database that are related and should be
201: displayed on the same window of a GUI that allows the user to set the options interactively.
203: Synopsis:
204: #include <petscoptions.h>
205: PetscErrorCode PetscObjectOptionsBegin(PetscObject obj)
207: Collective
209: Input Parameter:
210: . obj - object to set options for
212: Level: intermediate
214: Notes:
215: This is a macro that handles its own error checking, it does not return an error code.
217: Needs to be ended by a call the `PetscOptionsEnd()`
219: Can add subheadings with `PetscOptionsHeadBegin()`
221: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
222: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
223: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
224: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
225: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
226: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
227: `PetscOptionsFList()`, `PetscOptionsEList()`
228: M*/
229: #define PetscObjectOptionsBegin(obj) \
230: do { \
231: PetscOptionItems PetscOptionsObjectBase; \
232: PetscOptionItems *PetscOptionsObject = &PetscOptionsObjectBase; \
233: PetscOptionsObject->options = ((PetscObject)obj)->options; \
234: for (PetscOptionsObject->count = (PetscOptionsPublish ? -1 : 1); PetscOptionsObject->count < 2; PetscOptionsObject->count++) { \
235: PetscCall(PetscObjectOptionsBegin_Private(obj, PetscOptionsObject))
237: /*MC
238: PetscOptionsEnd - Ends a set of queries on the options database that are related and should be
239: displayed on the same window of a GUI that allows the user to set the options interactively.
241: Synopsis:
242: #include <petscoptions.h>
243: PetscErrorCode PetscOptionsEnd(void)
245: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
247: Level: intermediate
249: Notes:
250: Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()`
252: This is a macro that handles its own error checking, it does not return an error code.
254: Fortran Note:
255: Returns ierr error code per PETSc Fortran API
257: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
258: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`
259: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
260: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsHeadBegin()`,
261: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
262: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
263: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscObjectOptionsBegin()`
264: M*/
265: #define PetscOptionsEnd() \
266: PetscCall(PetscOptionsEnd_Private(PetscOptionsObject)); \
267: } \
268: } \
269: while (0)
270: #endif /* PETSC_CLANG_STATIC_ANALYZER */
272: PETSC_EXTERN PetscErrorCode PetscOptionsBegin_Private(PetscOptionItems *, MPI_Comm, const char[], const char[], const char[]);
273: PETSC_EXTERN PetscErrorCode PetscObjectOptionsBegin_Private(PetscObject, PetscOptionItems *);
274: PETSC_EXTERN PetscErrorCode PetscOptionsEnd_Private(PetscOptionItems *);
275: PETSC_EXTERN PetscErrorCode PetscOptionsHeadBegin(PetscOptionItems *, const char[]);
277: #if defined(PETSC_CLANG_STATIC_ANALYZER)
278: template <typename... T>
279: void PetscOptionsHeadBegin(T...);
280: void PetscOptionsHeadEnd(void);
281: template <typename... T>
282: PetscErrorCode PetscOptionsEnum(T...);
283: template <typename... T>
284: PetscErrorCode PetscOptionsInt(T...);
285: template <typename... T>
286: PetscErrorCode PetscOptionsBoundedInt(T...);
287: template <typename... T>
288: PetscErrorCode PetscOptionsRangeInt(T...);
289: template <typename... T>
290: PetscErrorCode PetscOptionsReal(T...);
291: template <typename... T>
292: PetscErrorCode PetscOptionsScalar(T...);
293: template <typename... T>
294: PetscErrorCode PetscOptionsName(T...);
295: template <typename... T>
296: PetscErrorCode PetscOptionsString(T...);
297: template <typename... T>
298: PetscErrorCode PetscOptionsBool(T...);
299: template <typename... T>
300: PetscErrorCode PetscOptionsBoolGroupBegin(T...);
301: template <typename... T>
302: PetscErrorCode PetscOptionsBoolGroup(T...);
303: template <typename... T>
304: PetscErrorCode PetscOptionsBoolGroupEnd(T...);
305: template <typename... T>
306: PetscErrorCode PetscOptionsFList(T...);
307: template <typename... T>
308: PetscErrorCode PetscOptionsEList(T...);
309: template <typename... T>
310: PetscErrorCode PetscOptionsRealArray(T...);
311: template <typename... T>
312: PetscErrorCode PetscOptionsScalarArray(T...);
313: template <typename... T>
314: PetscErrorCode PetscOptionsIntArray(T...);
315: template <typename... T>
316: PetscErrorCode PetscOptionsStringArray(T...);
317: template <typename... T>
318: PetscErrorCode PetscOptionsBoolArray(T...);
319: template <typename... T>
320: PetscErrorCode PetscOptionsEnumArray(T...);
321: template <typename... T>
322: PetscErrorCode PetscOptionsDeprecated(T...);
323: template <typename... T>
324: PetscErrorCode PetscOptionsDeprecatedNoObject(T...);
325: #else
326: /*MC
327: PetscOptionsHeadBegin - Puts a heading before listing any more published options. Used, for example,
328: in `KSPSetFromOptions_GMRES()`.
330: Logically Collective on the communicator passed in `PetscOptionsBegin()`
332: Input Parameter:
333: . head - the heading text
335: Level: developer
337: Notes:
338: Handles errors directly, hence does not return an error code
340: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument
342: Must be followed by a call to `PetscOptionsHeadEnd()` in the same function.
344: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
345: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
346: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
347: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
348: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
349: `PetscOptionsFList()`, `PetscOptionsEList()`
350: M*/
351: #define PetscOptionsHeadBegin(PetscOptionsObject, head) \
352: do { \
353: if (PetscOptionsObject->printhelp && PetscOptionsObject->count == 1 && !PetscOptionsObject->alreadyprinted) PetscCall((*PetscHelpPrintf)(PetscOptionsObject->comm, " %s\n", head)); \
354: } while (0)
356: #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__)
358: /*MC
359: PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()`
360: See, for example, `KSPSetFromOptions_GMRES()`.
362: Synopsis:
363: #include <petscoptions.h>
364: PetscErrorCode PetscOptionsHeadEnd(void)
366: Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()`
368: Level: intermediate
370: Notes:
371: Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()`
373: Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function.
375: This needs to be used only if the code below `PetscOptionsHeadEnd()` can be run ONLY once.
376: See, for example, `PCSetFromOptions_Composite()`. This is a `return(0)` in it for early exit
377: from the function.
379: This is only for use with the PETSc options GUI
381: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
382: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
383: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
384: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
385: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
386: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
387: M*/
388: #define PetscOptionsHeadEnd() \
389: do { \
390: if (PetscOptionsObject->count != 1) PetscFunctionReturn(PETSC_SUCCESS); \
391: } while (0)
393: #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__)
395: /*MC
396: PetscOptionsEnum - Gets the enum value for a particular option in the database.
398: Synopsis:
399: #include <petscoptions.h>
400: PetscErrorCode PetscOptionsEnum(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum currentvalue, PetscEnum *value, PetscBool *set)
402: Logically Collective on the communicator passed in `PetscOptionsBegin()`
404: Input Parameters:
405: + opt - option name
406: . text - short string that describes the option
407: . man - manual page with additional information on option
408: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
409: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
410: .vb
411: PetscOptionsEnum(..., obj->value,&object->value,...) or
412: value = defaultvalue
413: PetscOptionsEnum(..., value,&value,&set);
414: if (set) {
415: .ve
417: Output Parameters:
418: + value - the value to return
419: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
421: Level: beginner
423: Notes:
424: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
426: `list` is usually something like `PCASMTypes` or some other predefined list of enum names
428: If the user does not supply the option at all `value` is NOT changed. Thus
429: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
431: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
433: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
434: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
435: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
436: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
437: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
438: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
439: `PetscOptionsFList()`, `PetscOptionsEList()`
440: M*/
441: #define PetscOptionsEnum(opt, text, man, list, currentvalue, value, set) PetscOptionsEnum_Private(PetscOptionsObject, opt, text, man, list, currentvalue, value, set)
443: /*MC
444: PetscOptionsInt - Gets the integer value for a particular option in the database.
446: Synopsis:
447: #include <petscoptions.h>
448: PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set)
450: Logically Collective on the communicator passed in `PetscOptionsBegin()`
452: Input Parameters:
453: + opt - option name
454: . text - short string that describes the option
455: . man - manual page with additional information on option
456: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
457: .vb
458: PetscOptionsInt(..., obj->value, &obj->value, ...) or
459: value = defaultvalue
460: PetscOptionsInt(..., value, &value, &set);
461: if (set) {
462: .ve
464: Output Parameters:
465: + value - the integer value to return
466: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
468: Level: beginner
470: Notes:
471: If the user does not supply the option at all `value` is NOT changed. Thus
472: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
474: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
476: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
478: .seealso: `PetscOptionsBoundedInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
479: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
480: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
481: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
482: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
483: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
484: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
485: M*/
486: #define PetscOptionsInt(opt, text, man, currentvalue, value, set) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_INT, PETSC_MAX_INT)
488: /*MC
489: PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database.
491: Synopsis:
492: #include <petscoptions.h>
493: PetscErrorCode PetscOptionsBoundedInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt bound)
495: Logically Collective on the communicator passed in `PetscOptionsBegin()`
497: Input Parameters:
498: + opt - option name
499: . text - short string that describes the option
500: . man - manual page with additional information on option
501: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
502: .vb
503: PetscOptionsBoundedInt(..., obj->value, &obj->value, ...)
504: .ve
505: or
506: .vb
507: value = defaultvalue
508: PetscOptionsBoundedInt(..., value, &value, &set, ...);
509: if (set) {
510: .ve
511: - bound - the requested value should be greater than or equal to this bound or an error is generated
513: Output Parameters:
514: + value - the integer value to return
515: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
517: Level: beginner
519: Notes:
520: If the user does not supply the option at all `value` is NOT changed. Thus
521: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
523: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
525: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
527: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
528: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
529: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
530: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
531: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
532: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
533: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
534: M*/
535: #define PetscOptionsBoundedInt(opt, text, man, currentvalue, value, set, lb) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_INT)
537: /*MC
538: PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database.
540: Synopsis:
541: #include <petscoptions.h>
542: PetscErrorCode PetscOptionsRangeInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set, PetscInt lb, PetscInt ub)
544: Logically Collective on the communicator passed in `PetscOptionsBegin()`
546: Input Parameters:
547: + opt - option name
548: . text - short string that describes the option
549: . man - manual page with additional information on option
550: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
551: .vb
552: PetscOptionsRangeInt(..., obj->value, &obj->value, ...)
553: .ve
554: or
555: .vb
556: value = defaultvalue
557: PetscOptionsRangeInt(..., value, &value, &set, ...);
558: if (set) {
559: .ve
560: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
561: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
563: Output Parameters:
564: + value - the integer value to return
565: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
567: Level: beginner
569: Notes:
570: If the user does not supply the option at all `value` is NOT changed. Thus
571: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
573: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
575: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
577: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
578: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
579: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
580: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
581: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
582: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
583: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
584: M*/
585: #define PetscOptionsRangeInt(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsInt_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
587: /*MC
588: PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database.
590: Synopsis:
591: #include <petscoptions.h>
592: PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set)
594: Logically Collective on the communicator passed in `PetscOptionsBegin()`
596: Input Parameters:
597: + opt - option name
598: . text - short string that describes the option
599: . man - manual page with additional information on option
600: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
601: .vb
602: PetscOptionsReal(..., obj->value,&obj->value,...) or
603: value = defaultvalue
604: PetscOptionsReal(..., value,&value,&set);
605: if (set) {
606: .ve
608: Output Parameters:
609: + value - the value to return
610: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
612: Level: beginner
614: Notes:
615: If the user does not supply the option at all `value` is NOT changed. Thus
616: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
618: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
620: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
622: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
623: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
624: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
625: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
626: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
627: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
628: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedReal()`, `PetscOptionsRangeReal()`
629: M*/
630: #define PetscOptionsReal(opt, text, man, currentvalue, value, set) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, PETSC_MIN_REAL, PETSC_MAX_REAL)
632: /*MC
633: PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database.
635: Synopsis:
636: #include <petscoptions.h>
637: PetscErrorCode PetscOptionsBoundedReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal bound)
639: Logically Collective on the communicator passed in `PetscOptionsBegin()`
641: Input Parameters:
642: + opt - option name
643: . text - short string that describes the option
644: . man - manual page with additional information on option
645: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
646: .vb
647: PetscOptionsBoundedReal(..., obj->value, &obj->value, ...)
648: .ve
649: or
650: .vb
651: value = defaultvalue
652: PetscOptionsBoundedReal(..., value, &value, &set, ...);
653: if (set) {
654: .ve
655: - bound - the requested value should be greater than or equal to this bound or an error is generated
657: Output Parameters:
658: + value - the real value to return
659: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
661: Level: beginner
663: Notes:
664: If the user does not supply the option at all `value` is NOT changed. Thus
665: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
667: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
669: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
671: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
672: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsRangeInt()`
673: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
674: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
675: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
676: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
677: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsBoundedInt()`, `PetscOptionsRangeReal()`
678: M*/
679: #define PetscOptionsBoundedReal(opt, text, man, currentvalue, value, set, lb) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, PETSC_MAX_REAL)
681: /*MC
682: PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database.
684: Synopsis:
685: #include <petscoptions.h>
686: PetscErrorCode PetscOptionsRangeReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set, PetscReal lb, PetscReal ub)
688: Logically Collective on the communicator passed in `PetscOptionsBegin()`
690: Input Parameters:
691: + opt - option name
692: . text - short string that describes the option
693: . man - manual page with additional information on option
694: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
695: .vb
696: PetscOptionsRangeReal(..., obj->value, &obj->value, ...)
697: .ve
698: or
699: .vb
700: value = defaultvalue
701: PetscOptionsRangeReal(..., value, &value, &set, ...);
702: if (set) {
703: .ve
704: . lb - the lower bound, provided value must be greater than or equal to this value or an error is generated
705: - ub - the upper bound, provided value must be less than or equal to this value or an error is generated
707: Output Parameters:
708: + value - the value to return
709: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
711: Level: beginner
713: Notes:
714: If the user does not supply the option at all `value` is NOT changed. Thus
715: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
717: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
719: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
721: .seealso: `PetscOptionsInt()`, `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
722: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, `PetscOptionsBoundedInt()`
723: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
724: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
725: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
726: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
727: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsRangeInt()`, `PetscOptionsBoundedReal()`
728: M*/
729: #define PetscOptionsRangeReal(opt, text, man, currentvalue, value, set, lb, ub) PetscOptionsReal_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set, lb, ub)
731: /*MC
732: PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database.
734: Synopsis:
735: #include <petscoptions.h>
736: PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set)
738: Logically Collective on the communicator passed in `PetscOptionsBegin()`
740: Input Parameters:
741: + opt - option name
742: . text - short string that describes the option
743: . man - manual page with additional information on option
744: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with either
745: .vb
746: PetscOptionsScalar(..., obj->value,&obj->value,...) or
747: value = defaultvalue
748: PetscOptionsScalar(..., value,&value,&set);
749: if (set) {
750: .ve
752: Output Parameters:
753: + value - the value to return
754: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
756: Level: beginner
758: Notes:
759: If the user does not supply the option at all `value` is NOT changed. Thus
760: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
762: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
764: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
766: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
767: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
768: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
769: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
770: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
771: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
772: `PetscOptionsFList()`, `PetscOptionsEList()`
773: M*/
774: #define PetscOptionsScalar(opt, text, man, currentvalue, value, set) PetscOptionsScalar_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
776: /*MC
777: 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
778: its value is set to false.
780: Synopsis:
781: #include <petscoptions.h>
782: PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set)
784: Logically Collective on the communicator passed in `PetscOptionsBegin()`
786: Input Parameters:
787: + opt - option name
788: . text - short string that describes the option
789: - man - manual page with additional information on option
791: Output Parameter:
792: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
794: Level: beginner
796: Note:
797: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
799: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
800: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
801: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
802: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
803: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
804: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
805: `PetscOptionsFList()`, `PetscOptionsEList()`
806: M*/
807: #define PetscOptionsName(opt, text, man, set) PetscOptionsName_Private(PetscOptionsObject, opt, text, man, set)
809: /*MC
810: PetscOptionsString - Gets the string value for a particular option in the database.
812: Synopsis:
813: #include <petscoptions.h>
814: PetscErrorCode PetscOptionsString(const char opt[], const char text[], const char man[], const char currentvalue[], char value[], size_t len, PetscBool *set)
816: Logically Collective on the communicator passed in `PetscOptionsBegin()`
818: Input Parameters:
819: + opt - option name
820: . text - short string that describes the option
821: . man - manual page with additional information on option
822: . currentvalue - the current value; caller is responsible for setting this value correctly. This is not used to set value
823: - len - length of the result string including null terminator
825: Output Parameters:
826: + value - the value to return
827: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
829: Level: beginner
831: Notes:
832: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
834: If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls).
836: If the user does not supply the option at all `value` is NOT changed. Thus
837: you should ALWAYS initialize `value` if you access it without first checking that `set` is `PETSC_TRUE`.
839: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
841: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
842: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
843: `PetscOptionsInt()`, `PetscOptionsReal()`, `PetscOptionsBool()`,
844: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
845: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
846: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
847: `PetscOptionsFList()`, `PetscOptionsEList()`
848: M*/
849: #define PetscOptionsString(opt, text, man, currentvalue, value, len, set) PetscOptionsString_Private(PetscOptionsObject, opt, text, man, currentvalue, value, len, set)
851: /*MC
852: PetscOptionsBool - Determines if a particular option is in the database with a true or false
854: Synopsis:
855: #include <petscoptions.h>
856: PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set)
858: Logically Collective on the communicator passed in `PetscOptionsBegin()`
860: Input Parameters:
861: + opt - option name
862: . text - short string that describes the option
863: . man - manual page with additional information on option
864: - currentvalue - the current value
866: Output Parameters:
867: + flg - `PETSC_TRUE` or `PETSC_FALSE`
868: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
870: Level: beginner
872: Notes:
873: TRUE, true, YES, yes, nostring, and 1 all translate to `PETSC_TRUE`
874: FALSE, false, NO, no, and 0 all translate to `PETSC_FALSE`
876: 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`
877: is equivalent to `-requested_bool true`
879: If the user does not supply the option at all `flg` is NOT changed. Thus
880: you should ALWAYS initialize the `flg` variable if you access it without first checking that the `set` flag is `PETSC_TRUE`.
882: Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
884: .seealso: `PetscOptionsGetReal()`, `PetscOptionsHasName()`, `PetscOptionsGetString()`, `PetscOptionsGetInt()`,
885: `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
886: `PetscOptionsInt()`, `PetscOptionsString()`, `PetscOptionsReal()`,
887: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
888: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
889: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
890: `PetscOptionsFList()`, `PetscOptionsEList()`
891: M*/
892: #define PetscOptionsBool(opt, text, man, currentvalue, value, set) PetscOptionsBool_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
894: /*MC
895: PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for
896: which at most a single value can be true.
898: Synopsis:
899: #include <petscoptions.h>
900: PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set)
902: Logically Collective on the communicator passed in `PetscOptionsBegin()`
904: Input Parameters:
905: + opt - option name
906: . text - short string that describes the option
907: - man - manual page with additional information on option
909: Output Parameter:
910: . set - whether that option was set or not
912: Level: intermediate
914: Notes:
915: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
917: Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()`
919: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
920: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
921: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
922: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
923: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
924: `PetscOptionsFList()`, `PetscOptionsEList()`
925: M*/
926: #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set)
928: /*MC
929: PetscOptionsBoolGroup - One in a series of logical queries on the options database for
930: which at most a single value can be true.
932: Synopsis:
933: #include <petscoptions.h>
934: PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set)
936: Logically Collective on the communicator passed in `PetscOptionsBegin()`
938: Input Parameters:
939: + opt - option name
940: . text - short string that describes the option
941: - man - manual page with additional information on option
943: Output Parameter:
944: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
946: Level: intermediate
948: Notes:
949: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
951: Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()`
953: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
954: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
955: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
956: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
957: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
958: `PetscOptionsFList()`, `PetscOptionsEList()`
959: M*/
960: #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set)
962: /*MC
963: PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for
964: which at most a single value can be true.
966: Synopsis:
967: #include <petscoptions.h>
968: PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set)
970: Logically Collective on the communicator passed in `PetscOptionsBegin()`
972: Input Parameters:
973: + opt - option name
974: . text - short string that describes the option
975: - man - manual page with additional information on option
977: Output Parameter:
978: . set - `PETSC_TRUE` if found, else `PETSC_FALSE`
980: Level: intermediate
982: Notes:
983: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
985: Must follow a `PetscOptionsBoolGroupBegin()`
987: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
988: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
989: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
990: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
991: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
992: `PetscOptionsFList()`, `PetscOptionsEList()`
993: M*/
994: #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set)
996: /*MC
997: PetscOptionsFList - Puts a list of option values that a single one may be selected from
999: Synopsis:
1000: #include <petscoptions.h>
1001: PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set)
1003: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1005: Input Parameters:
1006: + opt - option name
1007: . ltext - short string that describes the option
1008: . man - manual page with additional information on option
1009: . list - the possible choices
1010: . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1011: .vb
1012: PetscOptionsFlist(..., obj->value,value,len,&set);
1013: if (set) {
1014: .ve
1015: - len - the length of the character array value
1017: Output Parameters:
1018: + value - the value to return
1019: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1021: Level: intermediate
1023: Notes:
1024: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1026: If the user does not supply the option at all `value` is NOT changed. Thus
1027: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1029: The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically.
1031: See `PetscOptionsEList()` for when the choices are given in a string array
1033: To get a listing of all currently specified options,
1034: see `PetscOptionsView()` or `PetscOptionsGetAll()`
1036: Developer Note:
1037: This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list
1039: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1040: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1041: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1042: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1043: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1044: `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()`
1045: M*/
1046: #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set)
1048: /*MC
1049: PetscOptionsEList - Puts a list of option values that a single one may be selected from
1051: Synopsis:
1052: #include <petscoptions.h>
1053: PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set)
1055: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1057: Input Parameters:
1058: + opt - option name
1059: . ltext - short string that describes the option
1060: . man - manual page with additional information on option
1061: . list - the possible choices (one of these must be selected, anything else is invalid)
1062: . ntext - number of choices
1063: - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with
1064: .vb
1065: PetscOptionsEList(..., obj->value,&value,&set);
1066: .ve if (set) {
1068: Output Parameters:
1069: + value - the index of the value to return
1070: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1072: Level: intermediate
1074: Notes:
1075: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1077: If the user does not supply the option at all `value` is NOT changed. Thus
1078: you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`.
1080: See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()`
1082: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1083: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1084: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1085: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1086: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1087: `PetscOptionsFList()`, `PetscOptionsEnum()`
1088: M*/
1089: #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set)
1091: /*MC
1092: PetscOptionsRealArray - Gets an array of double values for a particular
1093: option in the database. The values must be separated with commas with
1094: no intervening spaces.
1096: Synopsis:
1097: #include <petscoptions.h>
1098: PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set)
1100: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1102: Input Parameters:
1103: + opt - the option one is seeking
1104: . text - short string describing option
1105: . man - manual page for option
1106: - n - maximum number of values that value has room for
1108: Output Parameters:
1109: + value - location to copy values
1110: . n - actual number of values found
1111: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1113: Level: beginner
1115: Note:
1116: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1118: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1119: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1120: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1121: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1122: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1123: `PetscOptionsFList()`, `PetscOptionsEList()`
1124: M*/
1125: #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1127: /*MC
1128: PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular
1129: option in the database. The values must be separated with commas with
1130: no intervening spaces.
1132: Synopsis:
1133: #include <petscoptions.h>
1134: PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set)
1136: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1138: Input Parameters:
1139: + opt - the option one is seeking
1140: . text - short string describing option
1141: . man - manual page for option
1142: - n - maximum number of values allowed in the value array
1144: Output Parameters:
1145: + value - location to copy values
1146: . n - actual number of values found
1147: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1149: Level: beginner
1151: Note:
1152: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1154: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1155: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1156: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1157: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1158: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1159: `PetscOptionsFList()`, `PetscOptionsEList()`
1160: M*/
1161: #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1163: /*MC
1164: PetscOptionsIntArray - Gets an array of integers for a particular
1165: option in the database.
1167: Synopsis:
1168: #include <petscoptions.h>
1169: PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set)
1171: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1173: Input Parameters:
1174: + opt - the option one is seeking
1175: . text - short string describing option
1176: . man - manual page for option
1177: - n - maximum number of values
1179: Output Parameters:
1180: + value - location to copy values
1181: . n - actual number of values found
1182: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1184: Level: beginner
1186: Notes:
1187: The array can be passed as
1188: + a comma separated list - 0,1,2,3,4,5,6,7
1189: . a range (start\-end+1) - 0-8
1190: . a range with given increment (start\-end+1:inc) - 0-7:2
1191: - a combination of values and ranges separated by commas - 0,1-8,8-15:2
1193: There must be no intervening spaces between the values.
1195: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1197: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1198: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1199: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1200: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1201: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1202: `PetscOptionsFList()`, `PetscOptionsEList()`
1203: M*/
1204: #define PetscOptionsIntArray(opt, text, man, currentvalue, value, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1206: /*MC
1207: PetscOptionsStringArray - Gets an array of string values for a particular
1208: option in the database. The values must be separated with commas with
1209: no intervening spaces.
1211: Synopsis:
1212: #include <petscoptions.h>
1213: PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set)
1215: Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support
1217: Input Parameters:
1218: + opt - the option one is seeking
1219: . text - short string describing option
1220: . man - manual page for option
1221: - nmax - maximum number of strings
1223: Output Parameters:
1224: + value - location to copy strings
1225: . nmax - actual number of strings found
1226: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1228: Level: beginner
1230: Notes:
1231: The user should pass in an array of pointers to char, to hold all the
1232: strings returned by this function.
1234: The user is responsible for deallocating the strings that are
1235: returned.
1237: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1239: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1240: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1241: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1242: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1243: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1244: `PetscOptionsFList()`, `PetscOptionsEList()`
1245: M*/
1246: #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1248: /*MC
1249: PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular
1250: option in the database. The values must be separated with commas with
1251: no intervening spaces.
1253: Synopsis:
1254: #include <petscoptions.h>
1255: PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set)
1257: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1259: Input Parameters:
1260: + opt - the option one is seeking
1261: . text - short string describing option
1262: . man - manual page for option
1263: - n - maximum number of values allowed in the value array
1265: Output Parameters:
1266: + value - location to copy values
1267: . n - actual number of values found
1268: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1270: Level: beginner
1272: Notes:
1273: The user should pass in an array of `PetscBool`
1275: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1277: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1278: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`,
1279: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1280: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1281: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1282: `PetscOptionsFList()`, `PetscOptionsEList()`
1283: M*/
1284: #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set)
1286: /*MC
1287: PetscOptionsEnumArray - Gets an array of enum values for a particular
1288: option in the database.
1290: Synopsis:
1291: #include <petscoptions.h>
1292: PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set)
1294: Logically Collective on the communicator passed in `PetscOptionsBegin()`
1296: Input Parameters:
1297: + opt - the option one is seeking
1298: . text - short string describing option
1299: . man - manual page for option
1300: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1301: - n - maximum number of values allowed in the value array
1303: Output Parameters:
1304: + value - location to copy values
1305: . n - actual number of values found
1306: - set - `PETSC_TRUE` if found, else `PETSC_FALSE`
1308: Level: beginner
1310: Notes:
1311: The array must be passed as a comma separated list.
1313: There must be no intervening spaces between the values.
1315: Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`
1317: .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`,
1318: `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`,
1319: `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`,
1320: `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`,
1321: `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`,
1322: `PetscOptionsFList()`, `PetscOptionsEList()`
1323: M*/
1324: #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set)
1326: /*MC
1327: PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname`
1329: Prints a deprecation warning, unless an option is supplied to suppress.
1331: Logically Collective
1333: Input Parameters:
1334: + oldname - the old, deprecated option
1335: . newname - the new option, or `NULL` if option is purely removed
1336: . version - a string describing the version of first deprecation, e.g. "3.9"
1337: - info - additional information string, or `NULL`.
1339: Options Database Key:
1340: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1342: Level: developer
1344: Notes:
1345: If `newname` is provided then the options database will automatically check the database for `oldname`.
1347: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1348: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1349: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1351: Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`.
1352: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1353: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1354: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1355: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1357: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1358: M*/
1359: #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info)
1361: /*MC
1362: PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname`
1364: Prints a deprecation warning, unless an option is supplied to suppress.
1366: Logically Collective
1368: Input Parameters:
1369: + oldname - the old, deprecated option
1370: . newname - the new option, or `NULL` if option is purely removed
1371: . version - a string describing the version of first deprecation, e.g. "3.9"
1372: - info - additional information string, or `NULL`.
1374: Options Database Key:
1375: . -options_suppress_deprecated_warnings - do not print deprecation warnings
1377: Level: developer
1379: Notes:
1380: If `newname` is provided then the options database will automatically check the database for `oldname`.
1382: The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the
1383: new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call.
1384: See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails.
1386: Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information
1387: If newname is provided, the old option is replaced. Otherwise, it remains in the options database.
1388: If an option is not replaced, the info argument should be used to advise the user on how to proceed.
1389: There is a limit on the length of the warning printed, so very long strings provided as info may be truncated.
1391: .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()`
1392: M*/
1393: #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info)
1394: #endif /* PETSC_CLANG_STATIC_ANALYZER */
1396: PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *);
1397: PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt);
1398: PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal);
1399: PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *);
1400: PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1401: PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems *, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *);
1402: PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *);
1403: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1404: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1405: PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool *);
1406: PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems *, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *);
1407: PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *);
1408: PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *);
1409: PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *);
1410: PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *);
1411: PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems *, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *);
1412: PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems *, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *);
1413: PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems *, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *);
1414: PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems *, const char[], const char[], const char[], const char[]);
1416: PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void);
1418: PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems *, void *), PetscErrorCode (*)(PetscObject, void *), void *);
1419: PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems *);
1420: PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject);
1422: PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void);