1 /* 2 Routines to determine options set in the options database. 3 */ 4 #pragma once 5 6 #include <petscsys.h> 7 #include <petscviewertypes.h> 8 9 /* SUBMANSEC = Sys */ 10 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; 18 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); 27 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 *); 37 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 *); 44 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 *); 50 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); 58 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); 69 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 *); 75 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 *); 78 79 PETSC_EXTERN PetscErrorCode PetscObjectSetOptions(PetscObject, PetscOptions); 80 PETSC_EXTERN PetscErrorCode PetscObjectGetOptions(PetscObject, PetscOptions *); 81 82 PETSC_EXTERN PetscBool PetscOptionsPublish; 83 84 /* 85 See manual page for PetscOptionsBegin() 86 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() 89 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; 105 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 }; 122 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; 133 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. 144 145 Synopsis: 146 #include <petscoptions.h> 147 PetscErrorCode PetscOptionsBegin(MPI_Comm comm,const char prefix[],const char title[],const char mansec[]) 148 149 Collective 150 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) 156 157 Level: intermediate 158 159 Notes: 160 This is a macro that handles its own error checking, it does not return an error code. 161 162 The set of queries needs to be ended by a call to `PetscOptionsEnd()`. 163 164 One can add subheadings with `PetscOptionsHeadBegin()`. 165 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. 179 180 Fortran Note: 181 Returns ierr error code per PETSc Fortran API 182 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)) 198 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. 202 203 Synopsis: 204 #include <petscoptions.h> 205 PetscErrorCode PetscObjectOptionsBegin(PetscObject obj) 206 207 Collective 208 209 Input Parameter: 210 . obj - object to set options for 211 212 Level: intermediate 213 214 Notes: 215 This is a macro that handles its own error checking, it does not return an error code. 216 217 Needs to be ended by a call the `PetscOptionsEnd()` 218 219 Can add subheadings with `PetscOptionsHeadBegin()` 220 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)) 236 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. 240 241 Synopsis: 242 #include <petscoptions.h> 243 PetscErrorCode PetscOptionsEnd(void) 244 245 Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()` 246 247 Level: intermediate 248 249 Notes: 250 Needs to be preceded by a call to `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` 251 252 This is a macro that handles its own error checking, it does not return an error code. 253 254 Fortran Note: 255 Returns ierr error code per PETSc Fortran API 256 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 */ 271 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[]); 276 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()`. 329 330 Logically Collective on the communicator passed in `PetscOptionsBegin()` 331 332 Input Parameter: 333 . head - the heading text 334 335 Level: developer 336 337 Notes: 338 Handles errors directly, hence does not return an error code 339 340 Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()`, and `PetscOptionsObject` created in `PetscOptionsBegin()` should be the first argument 341 342 Must be followed by a call to `PetscOptionsHeadEnd()` in the same function. 343 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) 355 356 #define PetscOptionsHead(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadBegin()", ) PetscOptionsHeadBegin(__VA_ARGS__) 357 358 /*MC 359 PetscOptionsHeadEnd - Ends a section of options begun with `PetscOptionsHeadBegin()` 360 See, for example, `KSPSetFromOptions_GMRES()`. 361 362 Synopsis: 363 #include <petscoptions.h> 364 PetscErrorCode PetscOptionsHeadEnd(void) 365 366 Collective on the comm used in `PetscOptionsBegin()` or obj used in `PetscObjectOptionsBegin()` 367 368 Level: intermediate 369 370 Notes: 371 Must be between a `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` and a `PetscOptionsEnd()` 372 373 Must be preceded by a call to `PetscOptionsHeadBegin()` in the same function. 374 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. 378 379 This is only for use with the PETSc options GUI 380 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) 392 393 #define PetscOptionsTail(...) PETSC_DEPRECATED_MACRO(3, 18, 0, "PetscOptionsHeadEnd()", ) PetscOptionsHeadEnd(__VA_ARGS__) 394 395 /*MC 396 PetscOptionsEnum - Gets the enum value for a particular option in the database. 397 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) 401 402 Logically Collective on the communicator passed in `PetscOptionsBegin()` 403 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 416 417 Output Parameters: 418 + value - the value to return 419 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 420 421 Level: beginner 422 423 Notes: 424 Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 425 426 `list` is usually something like `PCASMTypes` or some other predefined list of enum names 427 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`. 430 431 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 432 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) 442 443 /*MC 444 PetscOptionsInt - Gets the integer value for a particular option in the database. 445 446 Synopsis: 447 #include <petscoptions.h> 448 PetscErrorCode PetscOptionsInt(const char opt[], const char text[], const char man[], PetscInt currentvalue, PetscInt *value, PetscBool *set) 449 450 Logically Collective on the communicator passed in `PetscOptionsBegin()` 451 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 463 464 Output Parameters: 465 + value - the integer value to return 466 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 467 468 Level: beginner 469 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`. 473 474 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 475 476 Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 477 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) 487 488 /*MC 489 PetscOptionsBoundedInt - Gets an integer value greater than or equal to a given bound for a particular option in the database. 490 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) 494 495 Logically Collective on the communicator passed in `PetscOptionsBegin()` 496 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 512 513 Output Parameters: 514 + value - the integer value to return 515 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 516 517 Level: beginner 518 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`. 522 523 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 524 525 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 526 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) 536 537 /*MC 538 PetscOptionsRangeInt - Gets an integer value within a range of values for a particular option in the database. 539 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) 543 544 Logically Collective on the communicator passed in `PetscOptionsBegin()` 545 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 562 563 Output Parameters: 564 + value - the integer value to return 565 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 566 567 Level: beginner 568 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`. 572 573 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 574 575 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 576 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) 586 587 /*MC 588 PetscOptionsReal - Gets a `PetscReal` value for a particular option in the database. 589 590 Synopsis: 591 #include <petscoptions.h> 592 PetscErrorCode PetscOptionsReal(const char opt[], const char text[], const char man[], PetscReal currentvalue, PetscReal *value, PetscBool *set) 593 594 Logically Collective on the communicator passed in `PetscOptionsBegin()` 595 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 607 608 Output Parameters: 609 + value - the value to return 610 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 611 612 Level: beginner 613 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`. 617 618 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 619 620 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 621 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) 631 632 /*MC 633 PetscOptionsBoundedReal - Gets a `PetscReal` value greater than or equal to a given bound for a particular option in the database. 634 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) 638 639 Logically Collective on the communicator passed in `PetscOptionsBegin()` 640 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 656 657 Output Parameters: 658 + value - the real value to return 659 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 660 661 Level: beginner 662 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`. 666 667 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 668 669 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 670 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) 680 681 /*MC 682 PetscOptionsRangeReal - Gets a `PetscReal` value within a range of values for a particular option in the database. 683 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) 687 688 Logically Collective on the communicator passed in `PetscOptionsBegin()` 689 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 706 707 Output Parameters: 708 + value - the value to return 709 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 710 711 Level: beginner 712 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`. 716 717 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 718 719 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 720 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) 730 731 /*MC 732 PetscOptionsScalar - Gets the `PetscScalar` value for a particular option in the database. 733 734 Synopsis: 735 #include <petscoptions.h> 736 PetscErrorCode PetscOptionsScalar(const char opt[], const char text[], const char man[], PetscScalar currentvalue, PetscScalar *value, PetscBool *set) 737 738 Logically Collective on the communicator passed in `PetscOptionsBegin()` 739 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 751 752 Output Parameters: 753 + value - the value to return 754 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 755 756 Level: beginner 757 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`. 761 762 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 763 764 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 765 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) 775 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. 779 780 Synopsis: 781 #include <petscoptions.h> 782 PetscErrorCode PetscOptionsName(const char opt[], const char text[], const char man[], PetscBool *set) 783 784 Logically Collective on the communicator passed in `PetscOptionsBegin()` 785 786 Input Parameters: 787 + opt - option name 788 . text - short string that describes the option 789 - man - manual page with additional information on option 790 791 Output Parameter: 792 . set - `PETSC_TRUE` if found, else `PETSC_FALSE` 793 794 Level: beginner 795 796 Note: 797 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 798 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) 808 809 /*MC 810 PetscOptionsString - Gets the string value for a particular option in the database. 811 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) 815 816 Logically Collective on the communicator passed in `PetscOptionsBegin()` 817 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 824 825 Output Parameters: 826 + value - the value to return 827 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 828 829 Level: beginner 830 831 Notes: 832 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 833 834 If the user provided no string (for example `-optionname` `-someotheroption`) `set` is set to `PETSC_TRUE` (and the string is filled with nulls). 835 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`. 838 839 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 840 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) 850 851 /*MC 852 PetscOptionsBool - Determines if a particular option is in the database with a true or false 853 854 Synopsis: 855 #include <petscoptions.h> 856 PetscErrorCode PetscOptionsBool(const char opt[], const char text[], const char man[], PetscBool currentvalue, PetscBool *flg, PetscBool *set) 857 858 Logically Collective on the communicator passed in `PetscOptionsBegin()` 859 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 865 866 Output Parameters: 867 + flg - `PETSC_TRUE` or `PETSC_FALSE` 868 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 869 870 Level: beginner 871 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` 875 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` 878 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`. 881 882 Must be between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 883 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) 893 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. 897 898 Synopsis: 899 #include <petscoptions.h> 900 PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set) 901 902 Logically Collective on the communicator passed in `PetscOptionsBegin()` 903 904 Input Parameters: 905 + opt - option name 906 . text - short string that describes the option 907 - man - manual page with additional information on option 908 909 Output Parameter: 910 . set - whether that option was set or not 911 912 Level: intermediate 913 914 Notes: 915 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 916 917 Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()` 918 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) 927 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. 931 932 Synopsis: 933 #include <petscoptions.h> 934 PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set) 935 936 Logically Collective on the communicator passed in `PetscOptionsBegin()` 937 938 Input Parameters: 939 + opt - option name 940 . text - short string that describes the option 941 - man - manual page with additional information on option 942 943 Output Parameter: 944 . set - `PETSC_TRUE` if found, else `PETSC_FALSE` 945 946 Level: intermediate 947 948 Notes: 949 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 950 951 Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()` 952 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) 961 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. 965 966 Synopsis: 967 #include <petscoptions.h> 968 PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set) 969 970 Logically Collective on the communicator passed in `PetscOptionsBegin()` 971 972 Input Parameters: 973 + opt - option name 974 . text - short string that describes the option 975 - man - manual page with additional information on option 976 977 Output Parameter: 978 . set - `PETSC_TRUE` if found, else `PETSC_FALSE` 979 980 Level: intermediate 981 982 Notes: 983 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 984 985 Must follow a `PetscOptionsBoolGroupBegin()` 986 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) 995 996 /*MC 997 PetscOptionsFList - Puts a list of option values that a single one may be selected from 998 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) 1002 1003 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1004 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 1016 1017 Output Parameters: 1018 + value - the value to return 1019 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1020 1021 Level: intermediate 1022 1023 Notes: 1024 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1025 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`. 1028 1029 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 1030 1031 See `PetscOptionsEList()` for when the choices are given in a string array 1032 1033 To get a listing of all currently specified options, 1034 see `PetscOptionsView()` or `PetscOptionsGetAll()` 1035 1036 Developer Note: 1037 This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list 1038 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) 1047 1048 /*MC 1049 PetscOptionsEList - Puts a list of option values that a single one may be selected from 1050 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) 1054 1055 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1056 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) { 1067 1068 Output Parameters: 1069 + value - the index of the value to return 1070 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1071 1072 Level: intermediate 1073 1074 Notes: 1075 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1076 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`. 1079 1080 See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()` 1081 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) 1090 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. 1095 1096 Synopsis: 1097 #include <petscoptions.h> 1098 PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set) 1099 1100 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1101 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 1107 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` 1112 1113 Level: beginner 1114 1115 Note: 1116 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1117 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) 1126 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. 1131 1132 Synopsis: 1133 #include <petscoptions.h> 1134 PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set) 1135 1136 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1137 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 1143 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` 1148 1149 Level: beginner 1150 1151 Note: 1152 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1153 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) 1162 1163 /*MC 1164 PetscOptionsIntArray - Gets an array of integers for a particular 1165 option in the database. 1166 1167 Synopsis: 1168 #include <petscoptions.h> 1169 PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set) 1170 1171 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1172 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 1178 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` 1183 1184 Level: beginner 1185 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 1192 1193 There must be no intervening spaces between the values. 1194 1195 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1196 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) 1205 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. 1210 1211 Synopsis: 1212 #include <petscoptions.h> 1213 PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set) 1214 1215 Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support 1216 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 1222 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` 1227 1228 Level: beginner 1229 1230 Notes: 1231 The user should pass in an array of pointers to char, to hold all the 1232 strings returned by this function. 1233 1234 The user is responsible for deallocating the strings that are 1235 returned. 1236 1237 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1238 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) 1247 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. 1252 1253 Synopsis: 1254 #include <petscoptions.h> 1255 PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set) 1256 1257 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1258 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 1264 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` 1269 1270 Level: beginner 1271 1272 Notes: 1273 The user should pass in an array of `PetscBool` 1274 1275 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1276 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) 1285 1286 /*MC 1287 PetscOptionsEnumArray - Gets an array of enum values for a particular 1288 option in the database. 1289 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) 1293 1294 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1295 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 1302 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` 1307 1308 Level: beginner 1309 1310 Notes: 1311 The array must be passed as a comma separated list. 1312 1313 There must be no intervening spaces between the values. 1314 1315 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1316 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) 1325 1326 /*MC 1327 PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname` 1328 1329 Prints a deprecation warning, unless an option is supplied to suppress. 1330 1331 Logically Collective 1332 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`. 1338 1339 Options Database Key: 1340 . -options_suppress_deprecated_warnings - do not print deprecation warnings 1341 1342 Level: developer 1343 1344 Notes: 1345 If `newname` is provided then the options database will automatically check the database for `oldname`. 1346 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. 1350 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. 1356 1357 .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()` 1358 M*/ 1359 #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info) 1360 1361 /*MC 1362 PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname` 1363 1364 Prints a deprecation warning, unless an option is supplied to suppress. 1365 1366 Logically Collective 1367 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`. 1373 1374 Options Database Key: 1375 . -options_suppress_deprecated_warnings - do not print deprecation warnings 1376 1377 Level: developer 1378 1379 Notes: 1380 If `newname` is provided then the options database will automatically check the database for `oldname`. 1381 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. 1385 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. 1390 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 */ 1395 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[]); 1415 1416 PETSC_EXTERN PetscErrorCode PetscOptionsSAWsDestroy(void); 1417 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); 1421 1422 PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void); 1423