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 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 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` 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 PetscOptionsBoolGroupBegin - First in a series of logical queries on the options database for 944 which at most a single value can be true. 945 946 Synopsis: 947 #include <petscoptions.h> 948 PetscErrorCode PetscOptionsBoolGroupBegin(const char opt[], const char text[], const char man[], PetscBool *set) 949 950 Logically Collective on the communicator passed in `PetscOptionsBegin()` 951 952 Input Parameters: 953 + opt - option name 954 . text - short string that describes the option 955 - man - manual page with additional information on option 956 957 Output Parameter: 958 . set - whether that option was set or not 959 960 Level: intermediate 961 962 Notes: 963 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 964 965 Must be followed by 0 or more `PetscOptionsBoolGroup()`s and `PetscOptionsBoolGroupEnd()` 966 967 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 968 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 969 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 970 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 971 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 972 `PetscOptionsFList()`, `PetscOptionsEList()` 973 M*/ 974 #define PetscOptionsBoolGroupBegin(opt, text, man, set) PetscOptionsBoolGroupBegin_Private(PetscOptionsObject, opt, text, man, set) 975 976 /*MC 977 PetscOptionsBoolGroup - One in a series of logical queries on the options database for 978 which at most a single value can be true. 979 980 Synopsis: 981 #include <petscoptions.h> 982 PetscErrorCode PetscOptionsBoolGroup(const char opt[], const char text[], const char man[], PetscBool *set) 983 984 Logically Collective on the communicator passed in `PetscOptionsBegin()` 985 986 Input Parameters: 987 + opt - option name 988 . text - short string that describes the option 989 - man - manual page with additional information on option 990 991 Output Parameter: 992 . set - `PETSC_TRUE` if found, else `PETSC_FALSE` 993 994 Level: intermediate 995 996 Notes: 997 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 998 999 Must follow a `PetscOptionsBoolGroupBegin()` and preceded a `PetscOptionsBoolGroupEnd()` 1000 1001 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1002 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1003 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1004 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1005 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1006 `PetscOptionsFList()`, `PetscOptionsEList()` 1007 M*/ 1008 #define PetscOptionsBoolGroup(opt, text, man, set) PetscOptionsBoolGroup_Private(PetscOptionsObject, opt, text, man, set) 1009 1010 /*MC 1011 PetscOptionsBoolGroupEnd - Last in a series of logical queries on the options database for 1012 which at most a single value can be true. 1013 1014 Synopsis: 1015 #include <petscoptions.h> 1016 PetscErrorCode PetscOptionsBoolGroupEnd(const char opt[], const char text[], const char man[], PetscBool *set) 1017 1018 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1019 1020 Input Parameters: 1021 + opt - option name 1022 . text - short string that describes the option 1023 - man - manual page with additional information on option 1024 1025 Output Parameter: 1026 . set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1027 1028 Level: intermediate 1029 1030 Notes: 1031 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1032 1033 Must follow a `PetscOptionsBoolGroupBegin()` 1034 1035 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1036 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1037 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1038 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1039 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1040 `PetscOptionsFList()`, `PetscOptionsEList()` 1041 M*/ 1042 #define PetscOptionsBoolGroupEnd(opt, text, man, set) PetscOptionsBoolGroupEnd_Private(PetscOptionsObject, opt, text, man, set) 1043 1044 /*MC 1045 PetscOptionsFList - Puts a list of option values that a single one may be selected from 1046 1047 Synopsis: 1048 #include <petscoptions.h> 1049 PetscErrorCode PetscOptionsFList(const char opt[], const char ltext[], const char man[], PetscFunctionList list, const char currentvalue[], char value[], size_t len, PetscBool *set) 1050 1051 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1052 1053 Input Parameters: 1054 + opt - option name 1055 . ltext - short string that describes the option 1056 . man - manual page with additional information on option 1057 . list - the possible choices 1058 . currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with 1059 .vb 1060 PetscOptionsFlist(..., obj->value,value,len,&set); 1061 if (set) { 1062 .ve 1063 - len - the length of the character array value 1064 1065 Output Parameters: 1066 + value - the value to return 1067 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1068 1069 Level: intermediate 1070 1071 Notes: 1072 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1073 1074 If the user does not supply the option at all `value` is NOT changed. Thus 1075 you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`. 1076 1077 The `currentvalue` passed into this routine does not get transferred to the output `value` variable automatically. 1078 1079 See `PetscOptionsEList()` for when the choices are given in a string array 1080 1081 To get a listing of all currently specified options, 1082 see `PetscOptionsView()` or `PetscOptionsGetAll()` 1083 1084 Developer Note: 1085 This cannot check for invalid selection because of things like `MATAIJ` that are not included in the list 1086 1087 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1088 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1089 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1090 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1091 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1092 `PetscOptionsFList()`, `PetscOptionsEList()`, `PetscOptionsEnum()` 1093 M*/ 1094 #define PetscOptionsFList(opt, ltext, man, list, currentvalue, value, len, set) PetscOptionsFList_Private(PetscOptionsObject, opt, ltext, man, list, currentvalue, value, len, set) 1095 1096 /*MC 1097 PetscOptionsEList - Puts a list of option values that a single one may be selected from 1098 1099 Synopsis: 1100 #include <petscoptions.h> 1101 PetscErrorCode PetscOptionsEList(const char opt[], const char ltext[], const char man[], const char *const *list, PetscInt ntext, const char currentvalue[], PetscInt *value, PetscBool *set) 1102 1103 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1104 1105 Input Parameters: 1106 + opt - option name 1107 . ltext - short string that describes the option 1108 . man - manual page with additional information on option 1109 . list - the possible choices (one of these must be selected, anything else is invalid) 1110 . ntext - number of choices 1111 - currentvalue - the current value; caller is responsible for setting this value correctly. Normally this is done with 1112 .vb 1113 PetscOptionsEList(..., obj->value,&value,&set); 1114 .ve if (set) { 1115 1116 Output Parameters: 1117 + value - the index of the value to return 1118 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1119 1120 Level: intermediate 1121 1122 Notes: 1123 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1124 1125 If the user does not supply the option at all `value` is NOT changed. Thus 1126 you should ALWAYS initialize `value` if you access it without first checking that the `set` flag is `PETSC_TRUE`. 1127 1128 See `PetscOptionsFList()` for when the choices are given in a `PetscFunctionList()` 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()`, `PetscOptionsEnum()` 1136 M*/ 1137 #define PetscOptionsEList(opt, ltext, man, list, ntext, currentvalue, value, set) PetscOptionsEList_Private(PetscOptionsObject, opt, ltext, man, list, ntext, currentvalue, value, set) 1138 1139 /*MC 1140 PetscOptionsRealArray - Gets an array of double values for a particular 1141 option in the database. The values must be separated with commas with 1142 no intervening spaces. 1143 1144 Synopsis: 1145 #include <petscoptions.h> 1146 PetscErrorCode PetscOptionsRealArray(const char opt[], const char text[], const char man[], PetscReal value[], PetscInt *n, PetscBool *set) 1147 1148 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1149 1150 Input Parameters: 1151 + opt - the option one is seeking 1152 . text - short string describing option 1153 . man - manual page for option 1154 - n - maximum number of values that value has room for 1155 1156 Output Parameters: 1157 + value - location to copy values 1158 . n - actual number of values found 1159 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1160 1161 Level: beginner 1162 1163 Note: 1164 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1165 1166 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1167 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1168 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1169 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1170 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1171 `PetscOptionsFList()`, `PetscOptionsEList()` 1172 M*/ 1173 #define PetscOptionsRealArray(opt, text, man, currentvalue, value, set) PetscOptionsRealArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set) 1174 1175 /*MC 1176 PetscOptionsScalarArray - Gets an array of `PetscScalar` values for a particular 1177 option in the database. The values must be separated with commas with 1178 no intervening spaces. 1179 1180 Synopsis: 1181 #include <petscoptions.h> 1182 PetscErrorCode PetscOptionsScalarArray(const char opt[], const char text[], const char man[], PetscScalar value[], PetscInt *n, PetscBool *set) 1183 1184 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1185 1186 Input Parameters: 1187 + opt - the option one is seeking 1188 . text - short string describing option 1189 . man - manual page for option 1190 - n - maximum number of values allowed in the value array 1191 1192 Output Parameters: 1193 + value - location to copy values 1194 . n - actual number of values found 1195 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1196 1197 Level: beginner 1198 1199 Note: 1200 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1201 1202 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1203 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1204 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1205 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1206 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1207 `PetscOptionsFList()`, `PetscOptionsEList()` 1208 M*/ 1209 #define PetscOptionsScalarArray(opt, text, man, currentvalue, value, set) PetscOptionsScalarArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set) 1210 1211 /*MC 1212 PetscOptionsIntArray - Gets an array of integers for a particular 1213 option in the database. 1214 1215 Synopsis: 1216 #include <petscoptions.h> 1217 PetscErrorCode PetscOptionsIntArray(const char opt[], const char text[], const char man[], PetscInt value[], PetscInt *n, PetscBool *set) 1218 1219 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1220 1221 Input Parameters: 1222 + opt - the option one is seeking 1223 . text - short string describing option 1224 . man - manual page for option 1225 - n - maximum number of values 1226 1227 Output Parameters: 1228 + value - location to copy values 1229 . n - actual number of values found 1230 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1231 1232 Level: beginner 1233 1234 Notes: 1235 The array can be passed as 1236 + a comma separated list - 0,1,2,3,4,5,6,7 1237 . a range (start\-end+1) - 0-8 1238 . a range with given increment (start\-end+1:inc) - 0-7:2 1239 - a combination of values and ranges separated by commas - 0,1-8,8-15:2 1240 1241 There must be no intervening spaces between the values. 1242 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 PetscOptionsIntArray(opt, text, man, currentvalue, value, set) PetscOptionsIntArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set) 1253 1254 /*MC 1255 PetscOptionsStringArray - Gets an array of string values for a particular 1256 option in the database. The values must be separated with commas with 1257 no intervening spaces. 1258 1259 Synopsis: 1260 #include <petscoptions.h> 1261 PetscErrorCode PetscOptionsStringArray(const char opt[], const char text[], const char man[], char *value[], PetscInt *nmax, PetscBool *set) 1262 1263 Logically Collective on the communicator passed in `PetscOptionsBegin()`; No Fortran Support 1264 1265 Input Parameters: 1266 + opt - the option one is seeking 1267 . text - short string describing option 1268 . man - manual page for option 1269 - nmax - maximum number of strings 1270 1271 Output Parameters: 1272 + value - location to copy strings 1273 . nmax - actual number of strings found 1274 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1275 1276 Level: beginner 1277 1278 Notes: 1279 The user should pass in an array of pointers to char, to hold all the 1280 strings returned by this function. 1281 1282 The user is responsible for deallocating the strings that are 1283 returned. 1284 1285 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1286 1287 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1288 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1289 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1290 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1291 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1292 `PetscOptionsFList()`, `PetscOptionsEList()` 1293 M*/ 1294 #define PetscOptionsStringArray(opt, text, man, currentvalue, value, set) PetscOptionsStringArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set) 1295 1296 /*MC 1297 PetscOptionsBoolArray - Gets an array of logical values (true or false) for a particular 1298 option in the database. The values must be separated with commas with 1299 no intervening spaces. 1300 1301 Synopsis: 1302 #include <petscoptions.h> 1303 PetscErrorCode PetscOptionsBoolArray(const char opt[], const char text[], const char man[], PetscBool value[], PetscInt *n, PetscBool *set) 1304 1305 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1306 1307 Input Parameters: 1308 + opt - the option one is seeking 1309 . text - short string describing option 1310 . man - manual page for option 1311 - n - maximum number of values allowed in the value array 1312 1313 Output Parameters: 1314 + value - location to copy values 1315 . n - actual number of values found 1316 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1317 1318 Level: beginner 1319 1320 Notes: 1321 The user should pass in an array of `PetscBool` 1322 1323 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1324 1325 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1326 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsBool()`, 1327 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1328 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1329 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1330 `PetscOptionsFList()`, `PetscOptionsEList()` 1331 M*/ 1332 #define PetscOptionsBoolArray(opt, text, man, currentvalue, value, set) PetscOptionsBoolArray_Private(PetscOptionsObject, opt, text, man, currentvalue, value, set) 1333 1334 /*MC 1335 PetscOptionsEnumArray - Gets an array of enum values for a particular 1336 option in the database. 1337 1338 Synopsis: 1339 #include <petscoptions.h> 1340 PetscErrorCode PetscOptionsEnumArray(const char opt[], const char text[], const char man[], const char *const *list, PetscEnum value[], PetscInt *n, PetscBool *set) 1341 1342 Logically Collective on the communicator passed in `PetscOptionsBegin()` 1343 1344 Input Parameters: 1345 + opt - the option one is seeking 1346 . text - short string describing option 1347 . man - manual page for option 1348 . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null 1349 - n - maximum number of values allowed in the value array 1350 1351 Output Parameters: 1352 + value - location to copy values 1353 . n - actual number of values found 1354 - set - `PETSC_TRUE` if found, else `PETSC_FALSE` 1355 1356 Level: beginner 1357 1358 Notes: 1359 The array must be passed as a comma separated list. 1360 1361 There must be no intervening spaces between the values. 1362 1363 Must be used between a `PetscOptionsBegin()` and a `PetscOptionsEnd()` 1364 1365 .seealso: `PetscOptionsGetInt()`, `PetscOptionsGetReal()`, 1366 `PetscOptionsHasName()`, `PetscOptionsGetIntArray()`, `PetscOptionsGetRealArray()`, `PetscOptionsGetBool()`, 1367 `PetscOptionsName()`, `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsHeadBegin()`, 1368 `PetscOptionsStringArray()`, `PetscOptionsRealArray()`, `PetscOptionsScalar()`, 1369 `PetscOptionsBoolGroupBegin()`, `PetscOptionsBoolGroup()`, `PetscOptionsBoolGroupEnd()`, 1370 `PetscOptionsFList()`, `PetscOptionsEList()` 1371 M*/ 1372 #define PetscOptionsEnumArray(opt, text, man, list, value, n, set) PetscOptionsEnumArray_Private(PetscOptionsObject, opt, text, man, list, value, n, set) 1373 1374 /*MC 1375 PetscOptionsDeprecated - mark an option as deprecated, optionally replacing it with `newname` 1376 1377 Prints a deprecation warning, unless an option is supplied to suppress. 1378 1379 Logically Collective 1380 1381 Input Parameters: 1382 + oldname - the old, deprecated option 1383 . newname - the new option, or `NULL` if option is purely removed 1384 . version - a string describing the version of first deprecation, e.g. "3.9" 1385 - info - additional information string, or `NULL`. 1386 1387 Options Database Key: 1388 . -options_suppress_deprecated_warnings - do not print deprecation warnings 1389 1390 Level: developer 1391 1392 Notes: 1393 If `newname` is provided then the options database will automatically check the database for `oldname`. 1394 1395 The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the 1396 new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call. 1397 See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails. 1398 1399 Must be called between `PetscOptionsBegin()` (or `PetscObjectOptionsBegin()`) and `PetscOptionsEnd()`. 1400 Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information 1401 If newname is provided, the old option is replaced. Otherwise, it remains in the options database. 1402 If an option is not replaced, the info argument should be used to advise the user on how to proceed. 1403 There is a limit on the length of the warning printed, so very long strings provided as info may be truncated. 1404 1405 .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()` 1406 M*/ 1407 #define PetscOptionsDeprecated(opt, text, man, info) PetscOptionsDeprecated_Private(PetscOptionsObject, opt, text, man, info) 1408 1409 /*MC 1410 PetscOptionsDeprecatedMoObject - mark an option as deprecated in the global PetscOptionsObject, optionally replacing it with `newname` 1411 1412 Prints a deprecation warning, unless an option is supplied to suppress. 1413 1414 Logically Collective 1415 1416 Input Parameters: 1417 + oldname - the old, deprecated option 1418 . newname - the new option, or `NULL` if option is purely removed 1419 . version - a string describing the version of first deprecation, e.g. "3.9" 1420 - info - additional information string, or `NULL`. 1421 1422 Options Database Key: 1423 . -options_suppress_deprecated_warnings - do not print deprecation warnings 1424 1425 Level: developer 1426 1427 Notes: 1428 If `newname` is provided then the options database will automatically check the database for `oldname`. 1429 1430 The old call `PetscOptionsXXX`(`oldname`) should be removed from the source code when both (1) the call to `PetscOptionsDeprecated()` occurs before the 1431 new call to `PetscOptionsXXX`(`newname`) and (2) the argument handling of the new call to `PetscOptionsXXX`(`newname`) is identical to the previous call. 1432 See `PTScotch_PartGraph_Seq()` for an example of when (1) fails and `SNESTestJacobian()` where an example of (2) fails. 1433 1434 Only the process of MPI rank zero that owns the `PetscOptionsItems` are argument (managed by `PetscOptionsBegin()` or `PetscObjectOptionsBegin()` prints the information 1435 If newname is provided, the old option is replaced. Otherwise, it remains in the options database. 1436 If an option is not replaced, the info argument should be used to advise the user on how to proceed. 1437 There is a limit on the length of the warning printed, so very long strings provided as info may be truncated. 1438 1439 .seealso: `PetscOptionsBegin()`, `PetscOptionsEnd()`, `PetscOptionsScalar()`, `PetscOptionsBool()`, `PetscOptionsString()`, `PetscOptionsSetValue()` 1440 M*/ 1441 #define PetscOptionsDeprecatedNoObject(opt, text, man, info) PetscOptionsDeprecated_Private(NULL, opt, text, man, info) 1442 #endif /* PETSC_CLANG_STATIC_ANALYZER */ 1443 1444 PETSC_EXTERN PetscErrorCode PetscOptionsEnum_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum, PetscEnum *, PetscBool *); 1445 PETSC_EXTERN PetscErrorCode PetscOptionsInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt, PetscInt *, PetscBool *, PetscInt, PetscInt); 1446 PETSC_EXTERN PetscErrorCode PetscOptionsMPIInt_Private(PetscOptionItems, const char[], const char[], const char[], PetscMPIInt, PetscMPIInt *, PetscBool *, PetscMPIInt, PetscMPIInt); 1447 PETSC_EXTERN PetscErrorCode PetscOptionsReal_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal, PetscReal *, PetscBool *, PetscReal, PetscReal); 1448 PETSC_EXTERN PetscErrorCode PetscOptionsScalar_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar, PetscScalar *, PetscBool *); 1449 PETSC_EXTERN PetscErrorCode PetscOptionsName_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *); 1450 PETSC_EXTERN PetscErrorCode PetscOptionsString_Private(PetscOptionItems, const char[], const char[], const char[], const char[], char *, size_t, PetscBool *); 1451 PETSC_EXTERN PetscErrorCode PetscOptionsBool_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool, PetscBool *, PetscBool *); 1452 PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupBegin_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *); 1453 PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroup_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *); 1454 PETSC_EXTERN PetscErrorCode PetscOptionsBoolGroupEnd_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool *); 1455 PETSC_EXTERN PetscErrorCode PetscOptionsFList_Private(PetscOptionItems, const char[], const char[], const char[], PetscFunctionList, const char[], char[], size_t, PetscBool *); 1456 PETSC_EXTERN PetscErrorCode PetscOptionsEList_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscInt, const char[], PetscInt *, PetscBool *); 1457 PETSC_EXTERN PetscErrorCode PetscOptionsRealArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscReal[], PetscInt *, PetscBool *); 1458 PETSC_EXTERN PetscErrorCode PetscOptionsScalarArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscScalar[], PetscInt *, PetscBool *); 1459 PETSC_EXTERN PetscErrorCode PetscOptionsIntArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscInt[], PetscInt *, PetscBool *); 1460 PETSC_EXTERN PetscErrorCode PetscOptionsStringArray_Private(PetscOptionItems, const char[], const char[], const char[], char *[], PetscInt *, PetscBool *); 1461 PETSC_EXTERN PetscErrorCode PetscOptionsBoolArray_Private(PetscOptionItems, const char[], const char[], const char[], PetscBool[], PetscInt *, PetscBool *); 1462 PETSC_EXTERN PetscErrorCode PetscOptionsEnumArray_Private(PetscOptionItems, const char[], const char[], const char[], const char *const *, PetscEnum[], PetscInt *, PetscBool *); 1463 PETSC_EXTERN PetscErrorCode PetscOptionsDeprecated_Private(PetscOptionItems, const char[], const char[], const char[], const char[]); 1464 1465 PETSC_EXTERN PetscErrorCode PetscObjectAddOptionsHandler(PetscObject, PetscErrorCode (*)(PetscObject, PetscOptionItems, void *), PetscErrorCode (*)(PetscObject, void *), void *); 1466 PETSC_EXTERN PetscErrorCode PetscObjectProcessOptionsHandlers(PetscObject, PetscOptionItems); 1467 PETSC_EXTERN PetscErrorCode PetscObjectDestroyOptionsHandlers(PetscObject); 1468 1469 PETSC_EXTERN PetscErrorCode PetscOptionsLeftError(void); 1470