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