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