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