1 2 /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */ 3 #define PETSC_DESIRE_FEATURE_TEST_MACROS 4 5 /* 6 These routines simplify the use of command line, file options, etc., and are used to manipulate the options database. 7 This provides the low-level interface, the high level interface is in aoptions.c 8 9 Some routines use regular malloc and free because it cannot know what malloc is requested with the 10 options database until it has already processed the input. 11 */ 12 13 #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/ 14 #include <petscviewer.h> 15 #include <ctype.h> 16 #if defined(PETSC_HAVE_MALLOC_H) 17 #include <malloc.h> 18 #endif 19 #if defined(PETSC_HAVE_STRING_H) 20 #include <string.h> /* strstr */ 21 #endif 22 #if defined(PETSC_HAVE_STRINGS_H) 23 # include <strings.h> /* strcasecmp */ 24 #endif 25 #if defined(PETSC_HAVE_YAML) 26 #include <yaml.h> 27 #endif 28 29 /* 30 This table holds all the options set by the user. For simplicity, we use a static size database 31 */ 32 #define MAXOPTIONS 512 33 #define MAXALIASES 25 34 #define MAXOPTIONSMONITORS 5 35 #define MAXPREFIXES 25 36 37 struct _n_PetscOptions { 38 int N,argc,Naliases; 39 char **args,*names[MAXOPTIONS],*values[MAXOPTIONS]; 40 char *aliases1[MAXALIASES],*aliases2[MAXALIASES]; 41 PetscBool used[MAXOPTIONS]; 42 PetscBool namegiven; 43 char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */ 44 45 /* --------User (or default) routines (most return -1 on error) --------*/ 46 PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */ 47 PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**); /* */ 48 void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */ 49 PetscInt numbermonitors; /* to, for instance, detect options being set */ 50 51 /* Prefixes */ 52 PetscInt prefixind,prefixstack[MAXPREFIXES]; 53 char prefix[2048]; 54 }; 55 56 57 static PetscOptions defaultoptions = NULL; 58 59 /* 60 Options events monitor 61 */ 62 #define PetscOptionsMonitor(name,value) \ 63 { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \ 64 for (_i=0; _i<_im; _i++) { \ 65 _ierr = (*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \ 66 } \ 67 } 68 69 /* 70 PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide" 71 */ 72 PetscErrorCode PetscOptionsStringToInt(const char name[],PetscInt *a) 73 { 74 PetscErrorCode ierr; 75 size_t len; 76 PetscBool decide,tdefault,mouse; 77 78 PetscFunctionBegin; 79 ierr = PetscStrlen(name,&len);CHKERRQ(ierr); 80 if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value"); 81 82 ierr = PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);CHKERRQ(ierr); 83 if (!tdefault) { 84 ierr = PetscStrcasecmp(name,"DEFAULT",&tdefault);CHKERRQ(ierr); 85 } 86 ierr = PetscStrcasecmp(name,"PETSC_DECIDE",&decide);CHKERRQ(ierr); 87 if (!decide) { 88 ierr = PetscStrcasecmp(name,"DECIDE",&decide);CHKERRQ(ierr); 89 } 90 ierr = PetscStrcasecmp(name,"mouse",&mouse);CHKERRQ(ierr); 91 92 if (tdefault) *a = PETSC_DEFAULT; 93 else if (decide) *a = PETSC_DECIDE; 94 else if (mouse) *a = -1; 95 else { 96 char *endptr; 97 long strtolval; 98 99 strtolval = strtol(name,&endptr,10); 100 if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name); 101 102 #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL) 103 *a = atoll(name); 104 #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64) 105 *a = _atoi64(name); 106 #else 107 *a = (PetscInt)strtolval; 108 #endif 109 } 110 PetscFunctionReturn(0); 111 } 112 113 #if defined(PETSC_USE_REAL___FLOAT128) 114 #include <quadmath.h> 115 #endif 116 117 static PetscErrorCode PetscStrtod(const char name[],PetscReal *a,char **endptr) 118 { 119 PetscFunctionBegin; 120 #if defined(PETSC_USE_REAL___FLOAT128) 121 *a = strtoflt128(name,endptr); 122 #else 123 *a = (PetscReal)strtod(name,endptr); 124 #endif 125 PetscFunctionReturn(0); 126 } 127 128 static PetscErrorCode PetscStrtoz(const char name[],PetscScalar *a,char **endptr,PetscBool *isImaginary) 129 { 130 PetscBool hasi = PETSC_FALSE; 131 char *ptr; 132 PetscReal strtoval; 133 PetscErrorCode ierr; 134 135 PetscFunctionBegin; 136 ierr = PetscStrtod(name,&strtoval,&ptr);CHKERRQ(ierr); 137 if (ptr == name) { 138 strtoval = 1.; 139 hasi = PETSC_TRUE; 140 if (name[0] == 'i') { 141 ptr++; 142 } else if (name[0] == '+' && name[1] == 'i') { 143 ptr += 2; 144 } else if (name[0] == '-' && name[1] == 'i') { 145 strtoval = -1.; 146 ptr += 2; 147 } 148 } else if (*ptr == 'i') { 149 hasi = PETSC_TRUE; 150 ptr++; 151 } 152 *endptr = ptr; 153 *isImaginary = hasi; 154 if (hasi) { 155 #if !defined(PETSC_USE_COMPLEX) 156 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s contains imaginary but complex not supported ",name); 157 #else 158 *a = PetscCMPLX(0.,strtoval); 159 #endif 160 } else { 161 *a = strtoval; 162 } 163 PetscFunctionReturn(0); 164 } 165 166 /* 167 Converts a string to PetscReal value. Handles special cases like "default" and "decide" 168 */ 169 PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a) 170 { 171 PetscErrorCode ierr; 172 size_t len; 173 PetscBool decide,tdefault; 174 175 PetscFunctionBegin; 176 ierr = PetscStrlen(name,&len);CHKERRQ(ierr); 177 if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value"); 178 179 ierr = PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);CHKERRQ(ierr); 180 if (!tdefault) { 181 ierr = PetscStrcasecmp(name,"DEFAULT",&tdefault);CHKERRQ(ierr); 182 } 183 ierr = PetscStrcasecmp(name,"PETSC_DECIDE",&decide);CHKERRQ(ierr); 184 if (!decide) { 185 ierr = PetscStrcasecmp(name,"DECIDE",&decide);CHKERRQ(ierr); 186 } 187 188 if (tdefault) *a = PETSC_DEFAULT; 189 else if (decide) *a = PETSC_DECIDE; 190 else { 191 char *endptr; 192 193 ierr = PetscStrtod(name,a,&endptr);CHKERRQ(ierr); 194 if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name); 195 } 196 PetscFunctionReturn(0); 197 } 198 199 PetscErrorCode PetscOptionsStringToScalar(const char name[],PetscScalar *a) 200 { 201 PetscBool imag1; 202 size_t len; 203 PetscScalar val; 204 char *ptr; 205 PetscErrorCode ierr; 206 207 PetscFunctionBegin; 208 ierr = PetscStrlen(name,&len);CHKERRQ(ierr); 209 if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value"); 210 ierr = PetscStrtoz(name,&val,&ptr,&imag1);CHKERRQ(ierr); 211 #if defined(PETSC_USE_COMPLEX) 212 if ((size_t) (ptr - name) < len) { 213 PetscBool imag2; 214 PetscScalar val2; 215 216 ierr = PetscStrtoz(ptr,&val2,&ptr,&imag2);CHKERRQ(ierr); 217 if (imag1 || !imag2) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s: must specify imaginary component second",name); 218 val = PetscCMPLX(PetscRealPart(val),PetscImaginaryPart(val2)); 219 } 220 #endif 221 if ((size_t) (ptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name); 222 *a = val; 223 PetscFunctionReturn(0); 224 } 225 226 /* 227 PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1" 228 */ 229 PetscErrorCode PetscOptionsStringToBool(const char value[], PetscBool *a) 230 { 231 PetscBool istrue, isfalse; 232 size_t len; 233 PetscErrorCode ierr; 234 235 PetscFunctionBegin; 236 ierr = PetscStrlen(value, &len);CHKERRQ(ierr); 237 if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value"); 238 ierr = PetscStrcasecmp(value,"TRUE",&istrue);CHKERRQ(ierr); 239 if (istrue) {*a = PETSC_TRUE; PetscFunctionReturn(0);} 240 ierr = PetscStrcasecmp(value,"YES",&istrue);CHKERRQ(ierr); 241 if (istrue) {*a = PETSC_TRUE; PetscFunctionReturn(0);} 242 ierr = PetscStrcasecmp(value,"1",&istrue);CHKERRQ(ierr); 243 if (istrue) {*a = PETSC_TRUE; PetscFunctionReturn(0);} 244 ierr = PetscStrcasecmp(value,"on",&istrue);CHKERRQ(ierr); 245 if (istrue) {*a = PETSC_TRUE; PetscFunctionReturn(0);} 246 ierr = PetscStrcasecmp(value,"FALSE",&isfalse);CHKERRQ(ierr); 247 if (isfalse) {*a = PETSC_FALSE; PetscFunctionReturn(0);} 248 ierr = PetscStrcasecmp(value,"NO",&isfalse);CHKERRQ(ierr); 249 if (isfalse) {*a = PETSC_FALSE; PetscFunctionReturn(0);} 250 ierr = PetscStrcasecmp(value,"0",&isfalse);CHKERRQ(ierr); 251 if (isfalse) {*a = PETSC_FALSE; PetscFunctionReturn(0);} 252 ierr = PetscStrcasecmp(value,"off",&isfalse);CHKERRQ(ierr); 253 if (isfalse) {*a = PETSC_FALSE; PetscFunctionReturn(0);} 254 SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value); 255 } 256 257 /*@C 258 PetscGetProgramName - Gets the name of the running program. 259 260 Not Collective 261 262 Input Parameter: 263 . len - length of the string name 264 265 Output Parameter: 266 . name - the name of the running program 267 268 Level: advanced 269 270 Notes: 271 The name of the program is copied into the user-provided character 272 array of length len. On some machines the program name includes 273 its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN. 274 @*/ 275 PetscErrorCode PetscGetProgramName(char name[],size_t len) 276 { 277 PetscErrorCode ierr; 278 279 PetscFunctionBegin; 280 ierr = PetscStrncpy(name,defaultoptions->programname,len);CHKERRQ(ierr); 281 PetscFunctionReturn(0); 282 } 283 284 PetscErrorCode PetscSetProgramName(const char name[]) 285 { 286 PetscErrorCode ierr; 287 288 PetscFunctionBegin; 289 ierr = PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);CHKERRQ(ierr); 290 PetscFunctionReturn(0); 291 } 292 293 /*@ 294 PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter. 295 296 Input Parameter: 297 . in_str - string to check if valid 298 299 Output Parameter: 300 . key - PETSC_TRUE if a valid key 301 302 Level: intermediate 303 304 @*/ 305 PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscBool *key) 306 { 307 char *ptr; 308 309 PetscFunctionBegin; 310 *key = PETSC_FALSE; 311 if (!in_str) PetscFunctionReturn(0); 312 if (in_str[0] != '-') PetscFunctionReturn(0); 313 if (in_str[1] == '-') in_str++; 314 if (!isalpha((int)(in_str[1]))) PetscFunctionReturn(0); 315 (double) strtod(in_str,&ptr); 316 if (ptr != in_str && !(*ptr == '_' || isalnum((int)*ptr))) PetscFunctionReturn(0); 317 *key = PETSC_TRUE; 318 PetscFunctionReturn(0); 319 } 320 321 /*@C 322 PetscOptionsInsertString - Inserts options into the database from a string 323 324 Not collective: but only processes that call this routine will set the options 325 included in the string 326 327 Input Parameter: 328 . in_str - string that contains options separated by blanks 329 330 331 Level: intermediate 332 333 Contributed by Boyana Norris 334 335 .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(), 336 PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(), 337 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 338 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 339 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 340 PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile() 341 342 @*/ 343 PetscErrorCode PetscOptionsInsertString(PetscOptions options,const char in_str[]) 344 { 345 char *first,*second; 346 PetscErrorCode ierr; 347 PetscToken token; 348 PetscBool key,ispush,ispop; 349 350 PetscFunctionBegin; 351 options = options ? options : defaultoptions; 352 ierr = PetscTokenCreate(in_str,' ',&token);CHKERRQ(ierr); 353 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 354 while (first) { 355 ierr = PetscStrcasecmp(first,"-prefix_push",&ispush);CHKERRQ(ierr); 356 ierr = PetscStrcasecmp(first,"-prefix_pop",&ispop);CHKERRQ(ierr); 357 ierr = PetscOptionsValidKey(first,&key);CHKERRQ(ierr); 358 if (ispush) { 359 ierr = PetscTokenFind(token,&second);CHKERRQ(ierr); 360 ierr = PetscOptionsPrefixPush(options,second);CHKERRQ(ierr); 361 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 362 } else if (ispop) { 363 ierr = PetscOptionsPrefixPop(options);CHKERRQ(ierr); 364 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 365 } else if (key) { 366 ierr = PetscTokenFind(token,&second);CHKERRQ(ierr); 367 ierr = PetscOptionsValidKey(second,&key);CHKERRQ(ierr); 368 if (!key) { 369 ierr = PetscOptionsSetValue(options,first,second);CHKERRQ(ierr); 370 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 371 } else { 372 ierr = PetscOptionsSetValue(options,first,NULL);CHKERRQ(ierr); 373 first = second; 374 } 375 } else { 376 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 377 } 378 } 379 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 380 PetscFunctionReturn(0); 381 } 382 383 /* 384 Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free() 385 */ 386 static char *Petscgetline(FILE * f) 387 { 388 size_t size = 0; 389 size_t len = 0; 390 size_t last = 0; 391 char *buf = NULL; 392 393 if (feof(f)) return 0; 394 do { 395 size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */ 396 buf = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */ 397 /* Actually do the read. Note that fgets puts a terminal '\0' on the 398 end of the string, so we make sure we overwrite this */ 399 if (!fgets(buf+len,size,f)) buf[len]=0; 400 PetscStrlen(buf,&len); 401 last = len - 1; 402 } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r'); 403 if (len) return buf; 404 free(buf); 405 return 0; 406 } 407 408 409 /*@C 410 PetscOptionsInsertFile - Inserts options into the database from a file. 411 412 Collective on MPI_Comm 413 414 Input Parameter: 415 + comm - the processes that will share the options (usually PETSC_COMM_WORLD) 416 . options - options database, use NULL for default global database 417 . file - name of file 418 - require - if PETSC_TRUE will generate an error if the file does not exist 419 420 421 Notes: Use # for lines that are comments and which should be ignored. 422 423 Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options 424 such as -log_summary or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later 425 calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize(). 426 427 Level: developer 428 429 .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(), 430 PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(), 431 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 432 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 433 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 434 PetscOptionsFList(), PetscOptionsEList() 435 436 @*/ 437 PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require) 438 { 439 char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0; 440 PetscErrorCode ierr; 441 size_t i,len,bytes; 442 FILE *fd; 443 PetscToken token; 444 int err; 445 char cmt[1]={'#'},*cmatch; 446 PetscMPIInt rank,cnt=0,acnt=0,counts[2]; 447 448 PetscFunctionBegin; 449 options = options ? options : defaultoptions; 450 ierr = MPI_Comm_rank(comm,&rank);CHKERRQ(ierr); 451 if (!rank) { 452 cnt = 0; 453 acnt = 0; 454 455 ierr = PetscFixFilename(file,fname);CHKERRQ(ierr); 456 fd = fopen(fname,"r"); 457 if (fd) { 458 PetscSegBuffer vseg,aseg; 459 ierr = PetscSegBufferCreate(1,4000,&vseg);CHKERRQ(ierr); 460 ierr = PetscSegBufferCreate(1,2000,&aseg);CHKERRQ(ierr); 461 462 /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */ 463 ierr = PetscInfo1(0,"Opened options file %s\n",file);CHKERRQ(ierr); 464 465 while ((string = Petscgetline(fd))) { 466 /* eliminate comments from each line */ 467 for (i=0; i<1; i++) { 468 ierr = PetscStrchr(string,cmt[i],&cmatch);CHKERRQ(ierr); 469 if (cmatch) *cmatch = 0; 470 } 471 ierr = PetscStrlen(string,&len);CHKERRQ(ierr); 472 /* replace tabs, ^M, \n with " " */ 473 for (i=0; i<len; i++) { 474 if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') { 475 string[i] = ' '; 476 } 477 } 478 ierr = PetscTokenCreate(string,' ',&token);CHKERRQ(ierr); 479 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 480 if (!first) { 481 goto destroy; 482 } else if (!first[0]) { /* if first token is empty spaces, redo first token */ 483 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 484 } 485 ierr = PetscTokenFind(token,&second);CHKERRQ(ierr); 486 if (!first) { 487 goto destroy; 488 } else if (first[0] == '-') { 489 ierr = PetscStrlen(first,&len);CHKERRQ(ierr); 490 ierr = PetscSegBufferGet(vseg,len+1,&vstring);CHKERRQ(ierr); 491 ierr = PetscMemcpy(vstring,first,len);CHKERRQ(ierr); 492 vstring[len] = ' '; 493 if (second) { 494 ierr = PetscStrlen(second,&len);CHKERRQ(ierr); 495 ierr = PetscSegBufferGet(vseg,len+3,&vstring);CHKERRQ(ierr); 496 vstring[0] = '"'; 497 ierr = PetscMemcpy(vstring+1,second,len);CHKERRQ(ierr); 498 vstring[len+1] = '"'; 499 vstring[len+2] = ' '; 500 } 501 } else { 502 PetscBool match; 503 504 ierr = PetscStrcasecmp(first,"alias",&match);CHKERRQ(ierr); 505 if (match) { 506 ierr = PetscTokenFind(token,&third);CHKERRQ(ierr); 507 if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second); 508 ierr = PetscStrlen(second,&len);CHKERRQ(ierr); 509 ierr = PetscSegBufferGet(aseg,len+1,&astring);CHKERRQ(ierr); 510 ierr = PetscMemcpy(astring,second,len);CHKERRQ(ierr); 511 astring[len] = ' '; 512 513 ierr = PetscStrlen(third,&len);CHKERRQ(ierr); 514 ierr = PetscSegBufferGet(aseg,len+1,&astring);CHKERRQ(ierr); 515 ierr = PetscMemcpy(astring,third,len);CHKERRQ(ierr); 516 astring[len] = ' '; 517 } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string); 518 } 519 destroy: 520 free(string); 521 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 522 } 523 err = fclose(fd); 524 if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file"); 525 ierr = PetscSegBufferGetSize(aseg,&bytes);CHKERRQ(ierr); /* size without null termination */ 526 ierr = PetscMPIIntCast(bytes,&acnt);CHKERRQ(ierr); 527 ierr = PetscSegBufferGet(aseg,1,&astring);CHKERRQ(ierr); 528 astring[0] = 0; 529 ierr = PetscSegBufferGetSize(vseg,&bytes);CHKERRQ(ierr); /* size without null termination */ 530 ierr = PetscMPIIntCast(bytes,&cnt);CHKERRQ(ierr); 531 ierr = PetscSegBufferGet(vseg,1,&vstring);CHKERRQ(ierr); 532 vstring[0] = 0; 533 ierr = PetscMalloc1(2+acnt+cnt,&packed);CHKERRQ(ierr); 534 ierr = PetscSegBufferExtractTo(aseg,packed);CHKERRQ(ierr); 535 ierr = PetscSegBufferExtractTo(vseg,packed+acnt+1);CHKERRQ(ierr); 536 ierr = PetscSegBufferDestroy(&aseg);CHKERRQ(ierr); 537 ierr = PetscSegBufferDestroy(&vseg);CHKERRQ(ierr); 538 } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname); 539 } 540 541 counts[0] = acnt; 542 counts[1] = cnt; 543 ierr = MPI_Bcast(counts,2,MPI_INT,0,comm);CHKERRQ(ierr); 544 acnt = counts[0]; 545 cnt = counts[1]; 546 if (rank) { 547 ierr = PetscMalloc1(2+acnt+cnt,&packed);CHKERRQ(ierr); 548 } 549 if (acnt || cnt) { 550 ierr = MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);CHKERRQ(ierr); 551 astring = packed; 552 vstring = packed + acnt + 1; 553 } 554 555 if (acnt) { 556 PetscToken token; 557 char *first,*second; 558 559 ierr = PetscTokenCreate(astring,' ',&token);CHKERRQ(ierr); 560 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 561 while (first) { 562 ierr = PetscTokenFind(token,&second);CHKERRQ(ierr); 563 ierr = PetscOptionsSetAlias(options,first,second);CHKERRQ(ierr); 564 ierr = PetscTokenFind(token,&first);CHKERRQ(ierr); 565 } 566 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 567 } 568 569 if (cnt) { 570 ierr = PetscOptionsInsertString(options,vstring);CHKERRQ(ierr); 571 } 572 ierr = PetscFree(packed);CHKERRQ(ierr); 573 PetscFunctionReturn(0); 574 } 575 576 static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[]) 577 { 578 PetscErrorCode ierr; 579 int left = argc - 1; 580 char **eargs = args + 1; 581 582 PetscFunctionBegin; 583 options = options ? options : defaultoptions; 584 while (left) { 585 PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key; 586 ierr = PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);CHKERRQ(ierr); 587 ierr = PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);CHKERRQ(ierr); 588 ierr = PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);CHKERRQ(ierr); 589 ierr = PetscStrcasecmp(eargs[0],"-p4pg",&isp4);CHKERRQ(ierr); 590 ierr = PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);CHKERRQ(ierr); 591 ierr = PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);CHKERRQ(ierr); 592 ierr = PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);CHKERRQ(ierr); 593 isp4 = (PetscBool) (isp4 || tisp4); 594 ierr = PetscStrcasecmp(eargs[0],"-np",&tisp4);CHKERRQ(ierr); 595 isp4 = (PetscBool) (isp4 || tisp4); 596 ierr = PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);CHKERRQ(ierr); 597 ierr = PetscOptionsValidKey(eargs[0],&key);CHKERRQ(ierr); 598 599 if (!key) { 600 eargs++; left--; 601 } else if (isoptions_file) { 602 if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option"); 603 if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option"); 604 ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);CHKERRQ(ierr); 605 eargs += 2; left -= 2; 606 } else if (isprefixpush) { 607 if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option"); 608 if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')"); 609 ierr = PetscOptionsPrefixPush(options,eargs[1]);CHKERRQ(ierr); 610 eargs += 2; left -= 2; 611 } else if (isprefixpop) { 612 ierr = PetscOptionsPrefixPop(options);CHKERRQ(ierr); 613 eargs++; left--; 614 615 /* 616 These are "bad" options that MPICH, etc put on the command line 617 we strip them out here. 618 */ 619 } else if (tisp4 || isp4rmrank) { 620 eargs += 1; left -= 1; 621 } else if (isp4 || isp4yourname) { 622 eargs += 2; left -= 2; 623 } else { 624 PetscBool nextiskey = PETSC_FALSE; 625 if (left >= 2) {ierr = PetscOptionsValidKey(eargs[1],&nextiskey);CHKERRQ(ierr);} 626 if (left < 2 || nextiskey) { 627 ierr = PetscOptionsSetValue(options,eargs[0],NULL);CHKERRQ(ierr); 628 eargs++; left--; 629 } else { 630 ierr = PetscOptionsSetValue(options,eargs[0],eargs[1]);CHKERRQ(ierr); 631 eargs += 2; left -= 2; 632 } 633 } 634 } 635 PetscFunctionReturn(0); 636 } 637 638 639 /*@C 640 PetscOptionsInsert - Inserts into the options database from the command line, 641 the environmental variable and a file. 642 643 Input Parameters: 644 + options - options database or NULL for the default global database 645 . argc - count of number of command line arguments 646 . args - the command line arguments 647 - file - optional filename, defaults to ~username/.petscrc 648 649 Note: 650 Since PetscOptionsInsert() is automatically called by PetscInitialize(), 651 the user does not typically need to call this routine. PetscOptionsInsert() 652 can be called several times, adding additional entries into the database. 653 654 Options Database Keys: 655 + -options_monitor <optional filename> - print options names and values as they are set 656 . -options_file <filename> - read options from a file 657 658 Level: advanced 659 660 Concepts: options database^adding 661 662 .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(), 663 PetscInitialize() 664 @*/ 665 PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[]) 666 { 667 PetscErrorCode ierr; 668 PetscMPIInt rank; 669 char pfile[PETSC_MAX_PATH_LEN]; 670 PetscBool flag = PETSC_FALSE; 671 672 673 PetscFunctionBegin; 674 if (!options) { 675 if (!defaultoptions) { 676 ierr = PetscOptionsCreateDefault();CHKERRQ(ierr); 677 } 678 options = defaultoptions; 679 } 680 ierr = MPI_Comm_rank(PETSC_COMM_WORLD,&rank);CHKERRQ(ierr); 681 682 options->argc = (argc) ? *argc : 0; 683 options->args = (args) ? *args : NULL; 684 685 if (file && file[0]) { 686 char fullpath[PETSC_MAX_PATH_LEN]; 687 688 ierr = PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);CHKERRQ(ierr); 689 ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);CHKERRQ(ierr); 690 } 691 /* 692 We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line 693 should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc. 694 */ 695 if (argc && args && *argc) {ierr = PetscOptionsInsertArgs_Private(options,*argc,*args);CHKERRQ(ierr);} 696 ierr = PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);CHKERRQ(ierr); 697 if (!flag) { 698 ierr = PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);CHKERRQ(ierr); 699 /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */ 700 if (pfile[0]) { ierr = PetscStrcat(pfile,"/.petscrc");CHKERRQ(ierr); } 701 ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);CHKERRQ(ierr); 702 ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);CHKERRQ(ierr); 703 ierr = PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);CHKERRQ(ierr); 704 } 705 706 /* insert environmental options */ 707 { 708 char *eoptions = 0; 709 size_t len = 0; 710 if (!rank) { 711 eoptions = (char*)getenv("PETSC_OPTIONS"); 712 ierr = PetscStrlen(eoptions,&len);CHKERRQ(ierr); 713 ierr = MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);CHKERRQ(ierr); 714 } else { 715 ierr = MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);CHKERRQ(ierr); 716 if (len) { 717 ierr = PetscMalloc1(len+1,&eoptions);CHKERRQ(ierr); 718 } 719 } 720 if (len) { 721 ierr = MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);CHKERRQ(ierr); 722 if (rank) eoptions[len] = 0; 723 ierr = PetscOptionsInsertString(options,eoptions);CHKERRQ(ierr); 724 if (rank) {ierr = PetscFree(eoptions);CHKERRQ(ierr);} 725 } 726 } 727 728 #if defined(PETSC_HAVE_YAML) 729 { 730 char yaml_file[PETSC_MAX_PATH_LEN]; 731 PetscBool yaml_flg; 732 ierr = PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);CHKERRQ(ierr); 733 if (yaml_flg) { 734 ierr = PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);CHKERRQ(ierr); 735 } 736 } 737 #endif 738 739 /* insert command line options again because they take precedence over arguments in petscrc/environment */ 740 if (argc && args && *argc) {ierr = PetscOptionsInsertArgs_Private(options,*argc,*args);CHKERRQ(ierr);} 741 PetscFunctionReturn(0); 742 } 743 744 /*@C 745 PetscOptionsView - Prints the options that have been loaded. This is 746 useful for debugging purposes. 747 748 Logically Collective on PetscViewer 749 750 Input Parameter: 751 . viewer - must be an PETSCVIEWERASCII viewer 752 753 Options Database Key: 754 . -options_table - Activates PetscOptionsView() within PetscFinalize() 755 756 Level: advanced 757 758 Concepts: options database^printing 759 760 .seealso: PetscOptionsAllUsed() 761 @*/ 762 PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer) 763 { 764 PetscErrorCode ierr; 765 PetscInt i; 766 PetscBool isascii; 767 768 PetscFunctionBegin; 769 options = options ? options : defaultoptions; 770 if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD; 771 ierr = PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);CHKERRQ(ierr); 772 if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer"); 773 774 if (options->N) { 775 ierr = PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");CHKERRQ(ierr); 776 } else { 777 ierr = PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");CHKERRQ(ierr); 778 } 779 for (i=0; i<options->N; i++) { 780 if (options->values[i]) { 781 ierr = PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);CHKERRQ(ierr); 782 } else { 783 ierr = PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);CHKERRQ(ierr); 784 } 785 } 786 if (options->N) { 787 ierr = PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");CHKERRQ(ierr); 788 } 789 PetscFunctionReturn(0); 790 } 791 792 /* 793 Called by error handlers to print options used in run 794 */ 795 PetscErrorCode PetscOptionsViewError(void) 796 { 797 PetscInt i; 798 PetscOptions options = defaultoptions; 799 800 PetscFunctionBegin; 801 if (options->N) { 802 (*PetscErrorPrintf)("PETSc Option Table entries:\n"); 803 } else { 804 (*PetscErrorPrintf)("No PETSc Option Table entries\n"); 805 } 806 for (i=0; i<options->N; i++) { 807 if (options->values[i]) { 808 (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]); 809 } else { 810 (*PetscErrorPrintf)("-%s\n",options->names[i]); 811 } 812 } 813 PetscFunctionReturn(0); 814 } 815 816 /*@C 817 PetscOptionsGetAll - Lists all the options the program was run with in a single string. 818 819 Not Collective 820 821 Input Paramter: 822 . options - the options database, use NULL for the default global database 823 824 Output Parameter: 825 . copts - pointer where string pointer is stored 826 827 Notes: the array and each entry in the array should be freed with PetscFree() 828 829 Level: advanced 830 831 Concepts: options database^listing 832 833 .seealso: PetscOptionsAllUsed(), PetscOptionsView() 834 @*/ 835 PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[]) 836 { 837 PetscErrorCode ierr; 838 PetscInt i; 839 size_t len = 1,lent = 0; 840 char *coptions = NULL; 841 842 PetscFunctionBegin; 843 options = options ? options : defaultoptions; 844 845 /* count the length of the required string */ 846 for (i=0; i<options->N; i++) { 847 ierr = PetscStrlen(options->names[i],&lent);CHKERRQ(ierr); 848 len += 2 + lent; 849 if (options->values[i]) { 850 ierr = PetscStrlen(options->values[i],&lent);CHKERRQ(ierr); 851 len += 1 + lent; 852 } 853 } 854 ierr = PetscMalloc1(len,&coptions);CHKERRQ(ierr); 855 coptions[0] = 0; 856 for (i=0; i<options->N; i++) { 857 ierr = PetscStrcat(coptions,"-");CHKERRQ(ierr); 858 ierr = PetscStrcat(coptions,options->names[i]);CHKERRQ(ierr); 859 ierr = PetscStrcat(coptions," ");CHKERRQ(ierr); 860 if (options->values[i]) { 861 ierr = PetscStrcat(coptions,options->values[i]);CHKERRQ(ierr); 862 ierr = PetscStrcat(coptions," ");CHKERRQ(ierr); 863 } 864 } 865 *copts = coptions; 866 PetscFunctionReturn(0); 867 } 868 869 /*@C 870 PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow. 871 872 Not Collective, but prefix will only be applied on calling ranks 873 874 Input Parameter: 875 + options - options database, or NULL for the default global database 876 - prefix - The string to append to the existing prefix 877 878 Options Database Keys: 879 + -prefix_push <some_prefix_> - push the given prefix 880 - -prefix_pop - pop the last prefix 881 882 Notes: 883 It is common to use this in conjunction with -options_file as in 884 885 $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop 886 887 where the files no longer require all options to be prefixed with -system2_. 888 889 Level: advanced 890 891 .seealso: PetscOptionsPrefixPop() 892 @*/ 893 PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[]) 894 { 895 PetscErrorCode ierr; 896 size_t n; 897 PetscInt start; 898 char buf[2048]; 899 PetscBool key; 900 901 PetscFunctionBegin; 902 PetscValidCharPointer(prefix,1); 903 options = options ? options : defaultoptions; 904 /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */ 905 buf[0] = '-'; 906 ierr = PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);CHKERRQ(ierr); 907 buf[sizeof(buf) - 1] = 0; 908 ierr = PetscOptionsValidKey(buf,&key);CHKERRQ(ierr); 909 if (!key) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Given prefix \"%s\" not valid (the first character must be a letter, do not include leading '-')",prefix); 910 911 if (!options) { 912 ierr = PetscOptionsInsert(NULL,0,0,0);CHKERRQ(ierr); 913 options = defaultoptions; 914 } 915 if (options->prefixind >= MAXPREFIXES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum depth of prefix stack %d exceeded, recompile \n src/sys/objects/options.c with larger value for MAXPREFIXES",MAXPREFIXES); 916 start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0; 917 ierr = PetscStrlen(prefix,&n);CHKERRQ(ierr); 918 if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix)); 919 ierr = PetscMemcpy(options->prefix+start,prefix,n+1);CHKERRQ(ierr); 920 options->prefixstack[options->prefixind++] = start+n; 921 PetscFunctionReturn(0); 922 } 923 924 /*@C 925 PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details 926 927 Not Collective, but prefix will only be popped on calling ranks 928 929 Input Parameters: 930 . options - options database, or NULL for the default global database 931 932 Level: advanced 933 934 .seealso: PetscOptionsPrefixPush() 935 @*/ 936 PetscErrorCode PetscOptionsPrefixPop(PetscOptions options) 937 { 938 PetscInt offset; 939 940 PetscFunctionBegin; 941 options = options ? options : defaultoptions; 942 if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed"); 943 options->prefixind--; 944 offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0; 945 options->prefix[offset] = 0; 946 PetscFunctionReturn(0); 947 } 948 949 /*@C 950 PetscOptionsClear - Removes all options form the database leaving it empty. 951 952 Input Parameters: 953 . options - options database, use NULL for the default global database 954 955 Level: developer 956 957 .seealso: PetscOptionsInsert() 958 @*/ 959 PetscErrorCode PetscOptionsClear(PetscOptions options) 960 { 961 PetscInt i; 962 963 PetscFunctionBegin; 964 options = options ? options : defaultoptions; 965 for (i=0; i<options->N; i++) { 966 if (options->names[i]) free(options->names[i]); 967 if (options->values[i]) free(options->values[i]); 968 } 969 for (i=0; i<options->Naliases; i++) { 970 free(options->aliases1[i]); 971 free(options->aliases2[i]); 972 } 973 options->prefix[0] = 0; 974 options->prefixind = 0; 975 options->N = 0; 976 options->Naliases = 0; 977 PetscFunctionReturn(0); 978 } 979 980 /*@ 981 PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options 982 983 Input Parameters: 984 . obj - the PetscObject 985 986 Level: developer 987 988 Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by 989 PCBJACOBI from all printing the same help messages to the screen 990 991 .seealso: PetscOptionsInsert() 992 @*/ 993 PetscErrorCode PetscObjectSetPrintedOptions(PetscObject obj) 994 { 995 PetscFunctionBegin; 996 obj->optionsprinted = PETSC_TRUE; 997 PetscFunctionReturn(0); 998 } 999 1000 /*@ 1001 PetscObjectInheritPrintedOptions - If the child object is not on the rank 0 process of the parent object and the child is sequential then the child gets it set. 1002 1003 Input Parameters: 1004 + pobj - the parent object 1005 - obj - the PetscObject 1006 1007 Level: developer 1008 1009 Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by 1010 PCBJACOBI from all printing the same help messages to the screen 1011 1012 This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap 1013 1014 .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions() 1015 @*/ 1016 PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj) 1017 { 1018 PetscErrorCode ierr; 1019 PetscMPIInt prank,size; 1020 1021 PetscFunctionBegin; 1022 ierr = MPI_Comm_rank(pobj->comm,&prank);CHKERRQ(ierr); 1023 ierr = MPI_Comm_size(obj->comm,&size);CHKERRQ(ierr); 1024 if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE; 1025 PetscFunctionReturn(0); 1026 } 1027 1028 /*@ 1029 PetscOptionsDestroy - Destroys an option database. 1030 1031 Input Parameter: 1032 . options - the PetscOptions object 1033 1034 Level: developer 1035 1036 .seealso: PetscOptionsInsert() 1037 @*/ 1038 PetscErrorCode PetscOptionsDestroy(PetscOptions *options) 1039 { 1040 PetscErrorCode ierr; 1041 1042 PetscFunctionBegin; 1043 ierr = PetscOptionsClear(*options);CHKERRQ(ierr); 1044 free(*options); 1045 *options = NULL; 1046 PetscFunctionReturn(0); 1047 } 1048 1049 PetscErrorCode PetscOptionsDestroyDefault(void) 1050 { 1051 PetscErrorCode ierr; 1052 1053 ierr = PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr; 1054 return 0; 1055 } 1056 1057 1058 /*@C 1059 PetscOptionsSetValue - Sets an option name-value pair in the options 1060 database, overriding whatever is already present. 1061 1062 Not collective, but setting values on certain processors could cause problems 1063 for parallel objects looking for options. 1064 1065 Input Parameters: 1066 + options - options database, use NULL for the default global database 1067 . name - name of option, this SHOULD have the - prepended 1068 - value - the option value (not used for all options) 1069 1070 Level: intermediate 1071 1072 Note: 1073 This function can be called BEFORE PetscInitialize() 1074 1075 Only some options have values associated with them, such as 1076 -ksp_rtol tol. Other options stand alone, such as -ksp_monitor. 1077 1078 Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized 1079 1080 Concepts: options database^adding option 1081 1082 .seealso: PetscOptionsInsert() 1083 @*/ 1084 PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[]) 1085 { 1086 size_t len; 1087 PetscErrorCode ierr; 1088 PetscInt N,n,i; 1089 char **names; 1090 char fullname[2048]; 1091 const char *name = iname; 1092 int match; 1093 1094 if (!options) { 1095 if (!defaultoptions) { 1096 ierr = PetscOptionsCreateDefault(); 1097 if (ierr) return ierr; 1098 } 1099 options = defaultoptions; 1100 } 1101 1102 /* this is so that -h and -help are equivalent (p4 does not like -help)*/ 1103 match = strcmp(name,"-h"); 1104 if (!match) name = "-help"; 1105 1106 name++; /* skip starting hyphen */ 1107 if (options->prefixind > 0) { 1108 strncpy(fullname,options->prefix,sizeof(fullname)); 1109 strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1); 1110 name = fullname; 1111 } 1112 1113 /* check against aliases */ 1114 N = options->Naliases; 1115 for (i=0; i<N; i++) { 1116 #if defined(PETSC_HAVE_STRCASECMP) 1117 match = strcasecmp(options->aliases1[i],name); 1118 #elif defined(PETSC_HAVE_STRICMP) 1119 match = stricmp(options->aliases1[i],name); 1120 #else 1121 Error 1122 #endif 1123 if (!match) { 1124 name = options->aliases2[i]; 1125 break; 1126 } 1127 } 1128 1129 N = options->N; 1130 n = N; 1131 names = options->names; 1132 1133 for (i=0; i<N; i++) { 1134 #if defined(PETSC_HAVE_STRCASECMP) 1135 match = strcasecmp(names[i],name); 1136 #elif defined(PETSC_HAVE_STRICMP) 1137 match = stricmp(names[i],name); 1138 #else 1139 Error 1140 #endif 1141 if (!match) { 1142 if (options->values[i]) free(options->values[i]); 1143 len = value ? strlen(value) : 0; 1144 if (len) { 1145 options->values[i] = (char*)malloc((len+1)*sizeof(char)); 1146 if (!options->values[i]) return PETSC_ERR_MEM; 1147 strcpy(options->values[i],value); 1148 } else options->values[i] = 0; 1149 return 0; 1150 } else if (strcmp(names[i],name) > 0) { 1151 n = i; 1152 break; 1153 } 1154 } 1155 if (N >= MAXOPTIONS) abort(); 1156 1157 /* shift remaining values down 1 */ 1158 for (i=N; i>n; i--) { 1159 options->names[i] = options->names[i-1]; 1160 options->values[i] = options->values[i-1]; 1161 options->used[i] = options->used[i-1]; 1162 } 1163 /* insert new name and value */ 1164 len = strlen(name); 1165 options->names[n] = (char*)malloc((len+1)*sizeof(char)); 1166 if (!options->names[n]) return PETSC_ERR_MEM; 1167 strcpy(options->names[n],name); 1168 len = value ? strlen(value) : 0; 1169 if (len) { 1170 options->values[n] = (char*)malloc((len+1)*sizeof(char)); 1171 if (!options->values[n]) return PETSC_ERR_MEM; 1172 strcpy(options->values[n],value); 1173 } else options->values[n] = NULL; 1174 options->used[n] = PETSC_FALSE; 1175 options->N++; 1176 return 0; 1177 } 1178 1179 /*@C 1180 PetscOptionsClearValue - Clears an option name-value pair in the options 1181 database, overriding whatever is already present. 1182 1183 Not Collective, but setting values on certain processors could cause problems 1184 for parallel objects looking for options. 1185 1186 Input Parameter: 1187 + options - options database, use NULL for the default global database 1188 . name - name of option, this SHOULD have the - prepended 1189 1190 Level: intermediate 1191 1192 Concepts: options database^removing option 1193 .seealso: PetscOptionsInsert() 1194 @*/ 1195 PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char iname[]) 1196 { 1197 PetscErrorCode ierr; 1198 PetscInt N,n,i; 1199 char **names,*name=(char*)iname; 1200 PetscBool gt,match; 1201 1202 PetscFunctionBegin; 1203 options = options ? options : defaultoptions; 1204 if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name); 1205 name++; 1206 1207 N = options->N; n = 0; 1208 names = options->names; 1209 1210 for (i=0; i<N; i++) { 1211 ierr = PetscStrcasecmp(names[i],name,&match);CHKERRQ(ierr); 1212 ierr = PetscStrgrt(names[i],name,>);CHKERRQ(ierr); 1213 if (match) { 1214 if (options->names[i]) free(options->names[i]); 1215 if (options->values[i]) free(options->values[i]); 1216 PetscOptionsMonitor(name,""); 1217 break; 1218 } else if (gt) PetscFunctionReturn(0); /* it was not listed */ 1219 1220 n++; 1221 } 1222 if (n == N) PetscFunctionReturn(0); /* it was not listed */ 1223 1224 /* shift remaining values down 1 */ 1225 for (i=n; i<N-1; i++) { 1226 options->names[i] = options->names[i+1]; 1227 options->values[i] = options->values[i+1]; 1228 options->used[i] = options->used[i+1]; 1229 } 1230 options->N--; 1231 PetscFunctionReturn(0); 1232 } 1233 1234 /*@C 1235 PetscOptionsSetAlias - Makes a key and alias for another key 1236 1237 Not Collective, but setting values on certain processors could cause problems 1238 for parallel objects looking for options. 1239 1240 Input Parameters: 1241 + options - options database or NULL for default global database 1242 . inewname - the alias 1243 - ioldname - the name that alias will refer to 1244 1245 Level: advanced 1246 1247 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(), 1248 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(), 1249 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1250 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1251 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1252 PetscOptionsFList(), PetscOptionsEList() 1253 @*/ 1254 PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[]) 1255 { 1256 PetscErrorCode ierr; 1257 PetscInt n = options->Naliases; 1258 size_t len; 1259 char *newname = (char*)inewname,*oldname = (char*)ioldname; 1260 1261 PetscFunctionBegin; 1262 options = options ? options : defaultoptions; 1263 if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname); 1264 if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname); 1265 if (n >= MAXALIASES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n src/sys/objects/options.c with larger value for MAXALIASES",MAXALIASES); 1266 1267 newname++; oldname++; 1268 ierr = PetscStrlen(newname,&len);CHKERRQ(ierr); 1269 options->aliases1[n] = (char*)malloc((len+1)*sizeof(char)); 1270 ierr = PetscStrcpy(options->aliases1[n],newname);CHKERRQ(ierr); 1271 ierr = PetscStrlen(oldname,&len);CHKERRQ(ierr); 1272 options->aliases2[n] = (char*)malloc((len+1)*sizeof(char)); 1273 ierr = PetscStrcpy(options->aliases2[n],oldname);CHKERRQ(ierr); 1274 options->Naliases++; 1275 PetscFunctionReturn(0); 1276 } 1277 1278 PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool *flg) 1279 { 1280 PetscErrorCode ierr; 1281 PetscInt i,N; 1282 size_t len; 1283 char **names,tmp[256]; 1284 PetscBool match; 1285 1286 PetscFunctionBegin; 1287 options = options ? options : defaultoptions; 1288 N = options->N; 1289 names = options->names; 1290 1291 if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name); 1292 1293 /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */ 1294 if (pre) { 1295 char *ptr = tmp; 1296 const char *namep = name; 1297 if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -"); 1298 if (name[1] == '-') { 1299 *ptr++ = '-'; 1300 namep++; 1301 } 1302 ierr = PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);CHKERRQ(ierr); 1303 tmp[sizeof(tmp)-1] = 0; 1304 ierr = PetscStrlen(tmp,&len);CHKERRQ(ierr); 1305 ierr = PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);CHKERRQ(ierr); 1306 } else { 1307 ierr = PetscStrncpy(tmp,name+1,sizeof(tmp));CHKERRQ(ierr); 1308 tmp[sizeof(tmp)-1] = 0; 1309 } 1310 #if defined(PETSC_USE_DEBUG) 1311 { 1312 PetscBool valid; 1313 char key[sizeof(tmp)+1] = "-"; 1314 1315 ierr = PetscMemcpy(key+1,tmp,sizeof(tmp));CHKERRQ(ierr); 1316 ierr = PetscOptionsValidKey(key,&valid);CHKERRQ(ierr); 1317 if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name); 1318 } 1319 #endif 1320 1321 /* slow search */ 1322 *flg = PETSC_FALSE; 1323 for (i=0; i<N; i++) { 1324 ierr = PetscStrcasecmp(names[i],tmp,&match);CHKERRQ(ierr); 1325 if (match) { 1326 *value = options->values[i]; 1327 options->used[i] = PETSC_TRUE; 1328 *flg = PETSC_TRUE; 1329 break; 1330 } 1331 } 1332 if (!*flg) { 1333 PetscInt j,cnt = 0,locs[16],loce[16]; 1334 size_t n; 1335 ierr = PetscStrlen(tmp,&n);CHKERRQ(ierr); 1336 /* determine the location and number of all _%d_ in the key */ 1337 for (i=0; i< (PetscInt)n; i++) { 1338 if (tmp[i] == '_') { 1339 for (j=i+1; j< (PetscInt)n; j++) { 1340 if (tmp[j] >= '0' && tmp[j] <= '9') continue; 1341 if (tmp[j] == '_' && j > i+1) { /* found a number */ 1342 locs[cnt] = i+1; 1343 loce[cnt++] = j+1; 1344 } 1345 break; 1346 } 1347 } 1348 } 1349 if (cnt) { 1350 char tmp2[256]; 1351 for (i=0; i<cnt; i++) { 1352 ierr = PetscStrcpy(tmp2,"-");CHKERRQ(ierr); 1353 ierr = PetscStrncat(tmp2,tmp,locs[i]);CHKERRQ(ierr); 1354 ierr = PetscStrcat(tmp2,tmp+loce[i]);CHKERRQ(ierr); 1355 ierr = PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);CHKERRQ(ierr); 1356 if (*flg) break; 1357 } 1358 } 1359 } 1360 PetscFunctionReturn(0); 1361 } 1362 1363 PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg) 1364 { 1365 PetscErrorCode ierr; 1366 PetscInt i,N; 1367 size_t len; 1368 char **names,tmp[256]; 1369 PetscBool match; 1370 1371 PetscFunctionBegin; 1372 options = options ? options : defaultoptions; 1373 N = options->N; 1374 names = options->names; 1375 1376 if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name); 1377 1378 /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */ 1379 if (pre) { 1380 char *ptr = tmp; 1381 const char *namep = name; 1382 if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -"); 1383 if (name[1] == '-') { 1384 *ptr++ = '-'; 1385 namep++; 1386 } 1387 ierr = PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);CHKERRQ(ierr); 1388 tmp[sizeof(tmp)-1] = 0; 1389 ierr = PetscStrlen(tmp,&len);CHKERRQ(ierr); 1390 ierr = PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);CHKERRQ(ierr); 1391 } else { 1392 ierr = PetscStrncpy(tmp,name+1,sizeof(tmp));CHKERRQ(ierr); 1393 tmp[sizeof(tmp)-1] = 0; 1394 } 1395 #if defined(PETSC_USE_DEBUG) 1396 { 1397 PetscBool valid; 1398 char key[sizeof(tmp)+1] = "-"; 1399 1400 ierr = PetscMemcpy(key+1,tmp,sizeof(tmp));CHKERRQ(ierr); 1401 ierr = PetscOptionsValidKey(key,&valid);CHKERRQ(ierr); 1402 if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name); 1403 } 1404 #endif 1405 1406 /* slow search */ 1407 *flg = PETSC_FALSE; 1408 ierr = PetscStrlen(tmp,&len);CHKERRQ(ierr); 1409 for (i = 0; i < N; ++i) { 1410 ierr = PetscStrncmp(names[i], tmp, len, &match);CHKERRQ(ierr); 1411 if (match) { 1412 if (value) *value = options->values[i]; 1413 options->used[i] = PETSC_TRUE; 1414 if (flg) *flg = PETSC_TRUE; 1415 break; 1416 } 1417 } 1418 PetscFunctionReturn(0); 1419 } 1420 1421 /*@C 1422 PetscOptionsReject - Generates an error if a certain option is given. 1423 1424 Not Collective, but setting values on certain processors could cause problems 1425 for parallel objects looking for options. 1426 1427 Input Parameters: 1428 + options - options database use NULL for default global database 1429 . name - the option one is seeking 1430 - mess - error message (may be NULL) 1431 1432 Level: advanced 1433 1434 Concepts: options database^rejecting option 1435 1436 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(), 1437 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 1438 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1439 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1440 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1441 PetscOptionsFList(), PetscOptionsEList() 1442 @*/ 1443 PetscErrorCode PetscOptionsReject(PetscOptions options,const char name[],const char mess[]) 1444 { 1445 PetscErrorCode ierr; 1446 PetscBool flag = PETSC_FALSE; 1447 1448 PetscFunctionBegin; 1449 options = options ? options : defaultoptions; 1450 ierr = PetscOptionsHasName(options,NULL,name,&flag);CHKERRQ(ierr); 1451 if (flag) { 1452 if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess); 1453 else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name); 1454 } 1455 PetscFunctionReturn(0); 1456 } 1457 1458 /*@C 1459 PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even 1460 its value is set to false. 1461 1462 Not Collective 1463 1464 Input Parameters: 1465 + options - options database use NULL for default global database 1466 . name - the option one is seeking 1467 - pre - string to prepend to the name or NULL 1468 1469 Output Parameters: 1470 . set - PETSC_TRUE if found else PETSC_FALSE. 1471 1472 Level: beginner 1473 1474 Concepts: options database^has option name 1475 1476 Notes: Name cannot be simply -h 1477 1478 In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values. 1479 1480 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(), 1481 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 1482 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1483 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1484 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1485 PetscOptionsFList(), PetscOptionsEList() 1486 @*/ 1487 PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set) 1488 { 1489 char *value; 1490 PetscErrorCode ierr; 1491 PetscBool flag; 1492 1493 PetscFunctionBegin; 1494 options = options ? options : defaultoptions; 1495 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1496 if (set) *set = flag; 1497 PetscFunctionReturn(0); 1498 } 1499 1500 /*@C 1501 PetscOptionsGetInt - Gets the integer value for a particular option in the database. 1502 1503 Not Collective 1504 1505 Input Parameters: 1506 + options - options database use NULL for default global database 1507 . pre - the string to prepend to the name or NULL 1508 - name - the option one is seeking 1509 1510 Output Parameter: 1511 + ivalue - the integer value to return 1512 - set - PETSC_TRUE if found, else PETSC_FALSE 1513 1514 Level: beginner 1515 1516 Concepts: options database^has int 1517 1518 .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), 1519 PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool() 1520 PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), 1521 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1522 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1523 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1524 PetscOptionsFList(), PetscOptionsEList() 1525 @*/ 1526 PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set) 1527 { 1528 char *value; 1529 PetscErrorCode ierr; 1530 PetscBool flag; 1531 1532 PetscFunctionBegin; 1533 PetscValidCharPointer(name,2); 1534 PetscValidIntPointer(ivalue,3); 1535 options = options ? options : defaultoptions; 1536 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1537 if (flag) { 1538 if (!value) { 1539 if (set) *set = PETSC_FALSE; 1540 } else { 1541 if (set) *set = PETSC_TRUE; 1542 ierr = PetscOptionsStringToInt(value,ivalue);CHKERRQ(ierr); 1543 } 1544 } else { 1545 if (set) *set = PETSC_FALSE; 1546 } 1547 PetscFunctionReturn(0); 1548 } 1549 1550 /*@C 1551 PetscOptionsGetEList - Puts a list of option values that a single one may be selected from 1552 1553 Not Collective 1554 1555 Input Parameters: 1556 + options - options database use NULL for default global database 1557 . pre - the string to prepend to the name or NULL 1558 . opt - option name 1559 . list - the possible choices (one of these must be selected, anything else is invalid) 1560 . ntext - number of choices 1561 1562 Output Parameter: 1563 + value - the index of the value to return (defaults to zero if the option name is given but choice is listed) 1564 - set - PETSC_TRUE if found, else PETSC_FALSE 1565 1566 Level: intermediate 1567 1568 See PetscOptionsFList() for when the choices are given in a PetscFunctionList() 1569 1570 Concepts: options database^list 1571 1572 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(), 1573 PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 1574 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1575 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1576 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1577 PetscOptionsFList(), PetscOptionsEList() 1578 @*/ 1579 PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set) 1580 { 1581 PetscErrorCode ierr; 1582 size_t alen,len = 0; 1583 char *svalue; 1584 PetscBool aset,flg = PETSC_FALSE; 1585 PetscInt i; 1586 1587 PetscFunctionBegin; 1588 options = options ? options : defaultoptions; 1589 for (i=0; i<ntext; i++) { 1590 ierr = PetscStrlen(list[i],&alen);CHKERRQ(ierr); 1591 if (alen > len) len = alen; 1592 } 1593 len += 5; /* a little extra space for user mistypes */ 1594 ierr = PetscMalloc1(len,&svalue);CHKERRQ(ierr); 1595 ierr = PetscOptionsGetString(options,pre,opt,svalue,len,&aset);CHKERRQ(ierr); 1596 if (aset) { 1597 ierr = PetscEListFind(ntext,list,svalue,value,&flg);CHKERRQ(ierr); 1598 if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1); 1599 if (set) *set = PETSC_TRUE; 1600 } else if (set) *set = PETSC_FALSE; 1601 ierr = PetscFree(svalue);CHKERRQ(ierr); 1602 PetscFunctionReturn(0); 1603 } 1604 1605 /*@C 1606 PetscOptionsGetEnum - Gets the enum value for a particular option in the database. 1607 1608 Not Collective 1609 1610 Input Parameters: 1611 + options - options database use NULL for default global database 1612 . pre - option prefix or NULL 1613 . opt - option name 1614 . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null 1615 - defaultv - the default (current) value 1616 1617 Output Parameter: 1618 + value - the value to return 1619 - set - PETSC_TRUE if found, else PETSC_FALSE 1620 1621 Level: beginner 1622 1623 Concepts: options database 1624 1625 Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd() 1626 1627 list is usually something like PCASMTypes or some other predefined list of enum names 1628 1629 .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(), 1630 PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool() 1631 PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), 1632 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1633 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1634 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1635 PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum() 1636 @*/ 1637 PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set) 1638 { 1639 PetscErrorCode ierr; 1640 PetscInt ntext = 0,tval; 1641 PetscBool fset; 1642 1643 PetscFunctionBegin; 1644 options = options ? options : defaultoptions; 1645 while (list[ntext++]) { 1646 if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries"); 1647 } 1648 if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix"); 1649 ntext -= 3; 1650 ierr = PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);CHKERRQ(ierr); 1651 /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */ 1652 if (fset) *value = (PetscEnum)tval; 1653 if (set) *set = fset; 1654 PetscFunctionReturn(0); 1655 } 1656 1657 /*@C 1658 PetscOptionsGetBool - Gets the Logical (true or false) value for a particular 1659 option in the database. 1660 1661 Not Collective 1662 1663 Input Parameters: 1664 + options - options database use NULL for default global database 1665 . pre - the string to prepend to the name or NULL 1666 - name - the option one is seeking 1667 1668 Output Parameter: 1669 + ivalue - the logical value to return 1670 - set - PETSC_TRUE if found, else PETSC_FALSE 1671 1672 Level: beginner 1673 1674 Notes: 1675 TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE 1676 FALSE, false, NO, no, and 0 all translate to PETSC_FALSE 1677 1678 If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus 1679 you NEED TO ALWAYS initialize the ivalue. 1680 1681 Concepts: options database^has logical 1682 1683 .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), 1684 PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(), 1685 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1686 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1687 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1688 PetscOptionsFList(), PetscOptionsEList() 1689 @*/ 1690 PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set) 1691 { 1692 char *value; 1693 PetscBool flag; 1694 PetscErrorCode ierr; 1695 1696 PetscFunctionBegin; 1697 PetscValidCharPointer(name,2); 1698 if (ivalue) PetscValidIntPointer(ivalue,3); 1699 options = options ? options : defaultoptions; 1700 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1701 if (flag) { 1702 if (set) *set = PETSC_TRUE; 1703 if (!value) { 1704 if (ivalue) *ivalue = PETSC_TRUE; 1705 } else { 1706 ierr = PetscOptionsStringToBool(value, ivalue);CHKERRQ(ierr); 1707 } 1708 } else { 1709 if (set) *set = PETSC_FALSE; 1710 } 1711 PetscFunctionReturn(0); 1712 } 1713 1714 /*@C 1715 PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular 1716 option in the database. The values must be separated with commas with 1717 no intervening spaces. 1718 1719 Not Collective 1720 1721 Input Parameters: 1722 + options - options database use NULL for default global database 1723 . pre - string to prepend to each name or NULL 1724 . name - the option one is seeking 1725 - nmax - maximum number of values to retrieve 1726 1727 Output Parameter: 1728 + dvalue - the integer values to return 1729 . nmax - actual number of values retreived 1730 - set - PETSC_TRUE if found, else PETSC_FALSE 1731 1732 Level: beginner 1733 1734 Concepts: options database^array of ints 1735 1736 Notes: 1737 TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE 1738 FALSE, false, NO, no, and 0 all translate to PETSC_FALSE 1739 1740 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 1741 PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(), 1742 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1743 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1744 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1745 PetscOptionsFList(), PetscOptionsEList() 1746 @*/ 1747 PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set) 1748 { 1749 char *value; 1750 PetscErrorCode ierr; 1751 PetscInt n = 0; 1752 PetscBool flag; 1753 PetscToken token; 1754 1755 PetscFunctionBegin; 1756 PetscValidCharPointer(name,2); 1757 PetscValidIntPointer(dvalue,3); 1758 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1759 if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; PetscFunctionReturn(0);} 1760 if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; PetscFunctionReturn(0);} 1761 1762 if (set) *set = PETSC_TRUE; 1763 1764 ierr = PetscTokenCreate(value,',',&token);CHKERRQ(ierr); 1765 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 1766 while (n < *nmax) { 1767 if (!value) break; 1768 ierr = PetscOptionsStringToBool(value,dvalue);CHKERRQ(ierr); 1769 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 1770 dvalue++; 1771 n++; 1772 } 1773 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 1774 *nmax = n; 1775 PetscFunctionReturn(0); 1776 } 1777 1778 /*@C 1779 PetscOptionsGetReal - Gets the double precision value for a particular 1780 option in the database. 1781 1782 Not Collective 1783 1784 Input Parameters: 1785 + options - options database use NULL for default global database 1786 . pre - string to prepend to each name or NULL 1787 - name - the option one is seeking 1788 1789 Output Parameter: 1790 + dvalue - the double value to return 1791 - set - PETSC_TRUE if found, PETSC_FALSE if not found 1792 1793 Note: if the option is given but no value is provided then set is given the value PETSC_FALSE 1794 1795 Level: beginner 1796 1797 Concepts: options database^has double 1798 1799 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 1800 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(), 1801 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1802 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1803 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1804 PetscOptionsFList(), PetscOptionsEList() 1805 @*/ 1806 PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set) 1807 { 1808 char *value; 1809 PetscErrorCode ierr; 1810 PetscBool flag; 1811 1812 PetscFunctionBegin; 1813 PetscValidCharPointer(name,2); 1814 PetscValidRealPointer(dvalue,3); 1815 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1816 if (flag) { 1817 if (!value) { 1818 if (set) *set = PETSC_FALSE; 1819 } else { 1820 if (set) *set = PETSC_TRUE; 1821 ierr = PetscOptionsStringToReal(value,dvalue);CHKERRQ(ierr); 1822 } 1823 } else { 1824 if (set) *set = PETSC_FALSE; 1825 } 1826 PetscFunctionReturn(0); 1827 } 1828 1829 /*@C 1830 PetscOptionsGetScalar - Gets the scalar value for a particular 1831 option in the database. 1832 1833 Not Collective 1834 1835 Input Parameters: 1836 + options - options database use NULL for default global database 1837 . pre - string to prepend to each name or NULL 1838 - name - the option one is seeking 1839 1840 Output Parameter: 1841 + dvalue - the double value to return 1842 - set - PETSC_TRUE if found, else PETSC_FALSE 1843 1844 Level: beginner 1845 1846 Usage: 1847 A complex number 2+3i must be specified with NO spaces 1848 1849 Note: if the option is given but no value is provided then set is given the value PETSC_FALSE 1850 1851 Concepts: options database^has scalar 1852 1853 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 1854 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 1855 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1856 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1857 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1858 PetscOptionsFList(), PetscOptionsEList() 1859 @*/ 1860 PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set) 1861 { 1862 char *value; 1863 PetscBool flag; 1864 PetscErrorCode ierr; 1865 1866 PetscFunctionBegin; 1867 PetscValidCharPointer(name,2); 1868 PetscValidScalarPointer(dvalue,3); 1869 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1870 if (flag) { 1871 if (!value) { 1872 if (set) *set = PETSC_FALSE; 1873 } else { 1874 #if !defined(PETSC_USE_COMPLEX) 1875 ierr = PetscOptionsStringToReal(value,dvalue);CHKERRQ(ierr); 1876 #else 1877 ierr = PetscOptionsStringToScalar(value,dvalue);CHKERRQ(ierr); 1878 #endif 1879 if (set) *set = PETSC_TRUE; 1880 } 1881 } else { /* flag */ 1882 if (set) *set = PETSC_FALSE; 1883 } 1884 PetscFunctionReturn(0); 1885 } 1886 1887 /*@C 1888 PetscOptionsGetRealArray - Gets an array of double precision values for a 1889 particular option in the database. The values must be separated with 1890 commas with no intervening spaces. 1891 1892 Not Collective 1893 1894 Input Parameters: 1895 + options - options database use NULL for default global database 1896 . pre - string to prepend to each name or NULL 1897 . name - the option one is seeking 1898 - nmax - maximum number of values to retrieve 1899 1900 Output Parameters: 1901 + dvalue - the double values to return 1902 . nmax - actual number of values retreived 1903 - set - PETSC_TRUE if found, else PETSC_FALSE 1904 1905 Level: beginner 1906 1907 Concepts: options database^array of doubles 1908 1909 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 1910 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(), 1911 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1912 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1913 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1914 PetscOptionsFList(), PetscOptionsEList() 1915 @*/ 1916 PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set) 1917 { 1918 char *value; 1919 PetscErrorCode ierr; 1920 PetscInt n = 0; 1921 PetscBool flag; 1922 PetscToken token; 1923 1924 PetscFunctionBegin; 1925 PetscValidCharPointer(name,2); 1926 PetscValidRealPointer(dvalue,3); 1927 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1928 if (!flag) { 1929 if (set) *set = PETSC_FALSE; 1930 *nmax = 0; 1931 PetscFunctionReturn(0); 1932 } 1933 if (!value) { 1934 if (set) *set = PETSC_TRUE; 1935 *nmax = 0; 1936 PetscFunctionReturn(0); 1937 } 1938 1939 if (set) *set = PETSC_TRUE; 1940 1941 ierr = PetscTokenCreate(value,',',&token);CHKERRQ(ierr); 1942 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 1943 while (n < *nmax) { 1944 if (!value) break; 1945 ierr = PetscOptionsStringToReal(value,dvalue++);CHKERRQ(ierr); 1946 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 1947 n++; 1948 } 1949 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 1950 *nmax = n; 1951 PetscFunctionReturn(0); 1952 } 1953 1954 /*@C 1955 PetscOptionsGetScalarArray - Gets an array of scalars for a 1956 particular option in the database. The values must be separated with 1957 commas with no intervening spaces. 1958 1959 Not Collective 1960 1961 Input Parameters: 1962 + options - options database use NULL for default global database 1963 . pre - string to prepend to each name or NULL 1964 . name - the option one is seeking 1965 - nmax - maximum number of values to retrieve 1966 1967 Output Parameters: 1968 + dvalue - the scalar values to return 1969 . nmax - actual number of values retreived 1970 - set - PETSC_TRUE if found, else PETSC_FALSE 1971 1972 Level: beginner 1973 1974 Concepts: options database^array of doubles 1975 1976 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 1977 PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(), 1978 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 1979 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 1980 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 1981 PetscOptionsFList(), PetscOptionsEList() 1982 @*/ 1983 PetscErrorCode PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool *set) 1984 { 1985 char *value; 1986 PetscErrorCode ierr; 1987 PetscInt n = 0; 1988 PetscBool flag; 1989 PetscToken token; 1990 1991 PetscFunctionBegin; 1992 PetscValidCharPointer(name,2); 1993 PetscValidRealPointer(dvalue,3); 1994 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 1995 if (!flag) { 1996 if (set) *set = PETSC_FALSE; 1997 *nmax = 0; 1998 PetscFunctionReturn(0); 1999 } 2000 if (!value) { 2001 if (set) *set = PETSC_TRUE; 2002 *nmax = 0; 2003 PetscFunctionReturn(0); 2004 } 2005 2006 if (set) *set = PETSC_TRUE; 2007 2008 ierr = PetscTokenCreate(value,',',&token);CHKERRQ(ierr); 2009 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2010 while (n < *nmax) { 2011 if (!value) break; 2012 ierr = PetscOptionsStringToScalar(value,dvalue++);CHKERRQ(ierr); 2013 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2014 n++; 2015 } 2016 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 2017 *nmax = n; 2018 PetscFunctionReturn(0); 2019 } 2020 2021 /*@C 2022 PetscOptionsGetIntArray - Gets an array of integer values for a particular 2023 option in the database. 2024 2025 Not Collective 2026 2027 Input Parameters: 2028 + options - options database use NULL for default global database 2029 . pre - string to prepend to each name or NULL 2030 . name - the option one is seeking 2031 - nmax - maximum number of values to retrieve 2032 2033 Output Parameter: 2034 + dvalue - the integer values to return 2035 . nmax - actual number of values retreived 2036 - set - PETSC_TRUE if found, else PETSC_FALSE 2037 2038 Level: beginner 2039 2040 Notes: 2041 The array can be passed as 2042 a comma separated list: 0,1,2,3,4,5,6,7 2043 a range (start-end+1): 0-8 2044 a range with given increment (start-end+1:inc): 0-7:2 2045 a combination of values and ranges separated by commas: 0,1-8,8-15:2 2046 2047 There must be no intervening spaces between the values. 2048 2049 Concepts: options database^array of ints 2050 2051 .seealso: PetscOptionsGetInt(), PetscOptionsHasName(), 2052 PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(), 2053 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 2054 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 2055 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 2056 PetscOptionsFList(), PetscOptionsEList() 2057 @*/ 2058 PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set) 2059 { 2060 char *value; 2061 PetscErrorCode ierr; 2062 PetscInt n = 0,i,j,start,end,inc,nvalues; 2063 size_t len; 2064 PetscBool flag,foundrange; 2065 PetscToken token; 2066 2067 PetscFunctionBegin; 2068 PetscValidCharPointer(name,2); 2069 PetscValidIntPointer(dvalue,3); 2070 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 2071 if (!flag) { 2072 if (set) *set = PETSC_FALSE; 2073 *nmax = 0; 2074 PetscFunctionReturn(0); 2075 } 2076 if (!value) { 2077 if (set) *set = PETSC_TRUE; 2078 *nmax = 0; 2079 PetscFunctionReturn(0); 2080 } 2081 2082 if (set) *set = PETSC_TRUE; 2083 2084 ierr = PetscTokenCreate(value,',',&token);CHKERRQ(ierr); 2085 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2086 while (n < *nmax) { 2087 if (!value) break; 2088 2089 /* look for form d-D where d and D are integers */ 2090 foundrange = PETSC_FALSE; 2091 ierr = PetscStrlen(value,&len);CHKERRQ(ierr); 2092 if (value[0] == '-') i=2; 2093 else i=1; 2094 for (;i<(int)len; i++) { 2095 if (value[i] == '-') { 2096 if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value); 2097 value[i] = 0; 2098 2099 ierr = PetscOptionsStringToInt(value,&start);CHKERRQ(ierr); 2100 inc = 1; 2101 j = i+1; 2102 for (;j<(int)len; j++) { 2103 if (value[j] == ':') { 2104 value[j] = 0; 2105 2106 ierr = PetscOptionsStringToInt(value+j+1,&inc);CHKERRQ(ierr); 2107 if (inc <= 0) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry,%s cannot have negative increment",n,value+j+1);CHKERRQ(ierr); 2108 break; 2109 } 2110 } 2111 ierr = PetscOptionsStringToInt(value+i+1,&end);CHKERRQ(ierr); 2112 if (end <= start) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, %s-%s cannot have decreasing list",n,value,value+i+1); 2113 nvalues = (end-start)/inc + (end-start)%inc; 2114 if (n + nvalues > *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end); 2115 for (;start<end; start+=inc) { 2116 *dvalue = start; dvalue++;n++; 2117 } 2118 foundrange = PETSC_TRUE; 2119 break; 2120 } 2121 } 2122 if (!foundrange) { 2123 ierr = PetscOptionsStringToInt(value,dvalue);CHKERRQ(ierr); 2124 dvalue++; 2125 n++; 2126 } 2127 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2128 } 2129 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 2130 *nmax = n; 2131 PetscFunctionReturn(0); 2132 } 2133 2134 /*@C 2135 PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database. 2136 2137 Not Collective 2138 2139 Input Parameters: 2140 + options - options database use NULL for default global database 2141 . pre - option prefix or NULL 2142 . name - option name 2143 . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null 2144 - nmax - maximum number of values to retrieve 2145 2146 Output Parameters: 2147 + dvalue - the enum values to return 2148 . nmax - actual number of values retreived 2149 - set - PETSC_TRUE if found, else PETSC_FALSE 2150 2151 Level: beginner 2152 2153 Concepts: options database 2154 2155 Notes: 2156 The array must be passed as a comma separated list. 2157 2158 There must be no intervening spaces between the values. 2159 2160 list is usually something like PCASMTypes or some other predefined list of enum names. 2161 2162 .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(), 2163 PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool() 2164 PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(), 2165 PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(), 2166 PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 2167 PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum() 2168 @*/ 2169 PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set) 2170 { 2171 char *svalue; 2172 PetscInt n = 0; 2173 PetscEnum evalue; 2174 PetscBool flag; 2175 PetscToken token; 2176 PetscErrorCode ierr; 2177 2178 PetscFunctionBegin; 2179 PetscValidCharPointer(name,2); 2180 PetscValidPointer(list,3); 2181 PetscValidPointer(dvalue,4); 2182 PetscValidIntPointer(nmax,5); 2183 2184 ierr = PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);CHKERRQ(ierr); 2185 if (!flag) { 2186 if (set) *set = PETSC_FALSE; 2187 *nmax = 0; 2188 PetscFunctionReturn(0); 2189 } 2190 if (!svalue) { 2191 if (set) *set = PETSC_TRUE; 2192 *nmax = 0; 2193 PetscFunctionReturn(0); 2194 } 2195 if (set) *set = PETSC_TRUE; 2196 2197 ierr = PetscTokenCreate(svalue,',',&token);CHKERRQ(ierr); 2198 ierr = PetscTokenFind(token,&svalue);CHKERRQ(ierr); 2199 while (svalue && n < *nmax) { 2200 ierr = PetscEnumFind(list,svalue,&evalue,&flag);CHKERRQ(ierr); 2201 if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1); 2202 dvalue[n++] = evalue; 2203 ierr = PetscTokenFind(token,&svalue);CHKERRQ(ierr); 2204 } 2205 *nmax = n; 2206 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 2207 PetscFunctionReturn(0); 2208 } 2209 2210 /*@C 2211 PetscOptionsGetString - Gets the string value for a particular option in 2212 the database. 2213 2214 Not Collective 2215 2216 Input Parameters: 2217 + options - options database use NULL for default global database 2218 . pre - string to prepend to name or NULL 2219 . name - the option one is seeking 2220 - len - maximum length of the string including null termination 2221 2222 Output Parameters: 2223 + string - location to copy string 2224 - set - PETSC_TRUE if found, else PETSC_FALSE 2225 2226 Level: beginner 2227 2228 Fortran Note: 2229 The Fortran interface is slightly different from the C/C++ 2230 interface (len is not used). Sample usage in Fortran follows 2231 .vb 2232 character *20 string 2233 PetscErrorCode ierr 2234 PetscBool set 2235 call PetscOptionsGetString(PETSC_NULL_OPTIONS,PETSC_NULL_CHARACTER,'-s',string,set,ierr) 2236 .ve 2237 2238 Notes: if the option is given but no string is provided then an empty string is returned and set is given the value of PETSC_TRUE 2239 2240 Concepts: options database^string 2241 2242 Note: 2243 Even if the user provided no string (for example -optionname -someotheroption) the flag is set to PETSC_TRUE (and the string is fulled with nulls). 2244 2245 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(), 2246 PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 2247 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 2248 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 2249 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 2250 PetscOptionsFList(), PetscOptionsEList() 2251 @*/ 2252 PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set) 2253 { 2254 char *value; 2255 PetscErrorCode ierr; 2256 PetscBool flag; 2257 2258 PetscFunctionBegin; 2259 PetscValidCharPointer(name,2); 2260 PetscValidCharPointer(string,3); 2261 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 2262 if (!flag) { 2263 if (set) *set = PETSC_FALSE; 2264 } else { 2265 if (set) *set = PETSC_TRUE; 2266 if (value) { 2267 ierr = PetscStrncpy(string,value,len);CHKERRQ(ierr); 2268 string[len-1] = 0; /* Ensure that the string is NULL terminated */ 2269 } else { 2270 ierr = PetscMemzero(string,len);CHKERRQ(ierr); 2271 } 2272 } 2273 PetscFunctionReturn(0); 2274 } 2275 2276 char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[]) 2277 { 2278 char *value; 2279 PetscErrorCode ierr; 2280 PetscBool flag; 2281 2282 PetscFunctionBegin; 2283 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) PetscFunctionReturn(0); 2284 if (flag) PetscFunctionReturn(value); 2285 else PetscFunctionReturn(0); 2286 } 2287 2288 2289 /*@C 2290 PetscOptionsGetStringArray - Gets an array of string values for a particular 2291 option in the database. The values must be separated with commas with 2292 no intervening spaces. 2293 2294 Not Collective 2295 2296 Input Parameters: 2297 + options - options database use NULL for default global database 2298 . pre - string to prepend to name or NULL 2299 . name - the option one is seeking 2300 - nmax - maximum number of strings 2301 2302 Output Parameter: 2303 + strings - location to copy strings 2304 - set - PETSC_TRUE if found, else PETSC_FALSE 2305 2306 Level: beginner 2307 2308 Notes: 2309 The user should pass in an array of pointers to char, to hold all the 2310 strings returned by this function. 2311 2312 The user is responsible for deallocating the strings that are 2313 returned. The Fortran interface for this routine is not supported. 2314 2315 Contributed by Matthew Knepley. 2316 2317 Concepts: options database^array of strings 2318 2319 .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(), 2320 PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(), 2321 PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), 2322 PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(), 2323 PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(), 2324 PetscOptionsFList(), PetscOptionsEList() 2325 @*/ 2326 PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set) 2327 { 2328 char *value; 2329 PetscErrorCode ierr; 2330 PetscInt n; 2331 PetscBool flag; 2332 PetscToken token; 2333 2334 PetscFunctionBegin; 2335 PetscValidCharPointer(name,2); 2336 PetscValidPointer(strings,3); 2337 ierr = PetscOptionsFindPair_Private(options,pre,name,&value,&flag);CHKERRQ(ierr); 2338 if (!flag) { 2339 *nmax = 0; 2340 if (set) *set = PETSC_FALSE; 2341 PetscFunctionReturn(0); 2342 } 2343 if (!value) { 2344 *nmax = 0; 2345 if (set) *set = PETSC_FALSE; 2346 PetscFunctionReturn(0); 2347 } 2348 if (!*nmax) { 2349 if (set) *set = PETSC_FALSE; 2350 PetscFunctionReturn(0); 2351 } 2352 if (set) *set = PETSC_TRUE; 2353 2354 ierr = PetscTokenCreate(value,',',&token);CHKERRQ(ierr); 2355 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2356 n = 0; 2357 while (n < *nmax) { 2358 if (!value) break; 2359 ierr = PetscStrallocpy(value,&strings[n]);CHKERRQ(ierr); 2360 ierr = PetscTokenFind(token,&value);CHKERRQ(ierr); 2361 n++; 2362 } 2363 ierr = PetscTokenDestroy(&token);CHKERRQ(ierr); 2364 *nmax = n; 2365 PetscFunctionReturn(0); 2366 } 2367 2368 /*@C 2369 PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database 2370 2371 Not Collective 2372 2373 Input Parameter: 2374 + options - options database use NULL for default global database 2375 - option - string name of option 2376 2377 Output Parameter: 2378 . used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database 2379 2380 Level: advanced 2381 2382 .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed() 2383 @*/ 2384 PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used) 2385 { 2386 PetscInt i; 2387 PetscErrorCode ierr; 2388 2389 PetscFunctionBegin; 2390 options = options ? options : defaultoptions; 2391 *used = PETSC_FALSE; 2392 for (i=0; i<options->N; i++) { 2393 ierr = PetscStrcmp(options->names[i],option,used);CHKERRQ(ierr); 2394 if (*used) { 2395 *used = options->used[i]; 2396 break; 2397 } 2398 } 2399 PetscFunctionReturn(0); 2400 } 2401 2402 /*@C 2403 PetscOptionsAllUsed - Returns a count of the number of options in the 2404 database that have never been selected. 2405 2406 Not Collective 2407 2408 Input Parameter: 2409 . options - options database use NULL for default global database 2410 2411 Output Parameter: 2412 . N - count of options not used 2413 2414 Level: advanced 2415 2416 .seealso: PetscOptionsView() 2417 @*/ 2418 PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N) 2419 { 2420 PetscInt i,n = 0; 2421 2422 PetscFunctionBegin; 2423 options = options ? options : defaultoptions; 2424 for (i=0; i<options->N; i++) { 2425 if (!options->used[i]) n++; 2426 } 2427 *N = n; 2428 PetscFunctionReturn(0); 2429 } 2430 2431 /*@C 2432 PetscOptionsLeft - Prints to screen any options that were set and never used. 2433 2434 Not collective 2435 2436 Input Parameter: 2437 . options - options database use NULL for default global database 2438 2439 Options Database Key: 2440 . -options_left - Activates OptionsAllUsed() within PetscFinalize() 2441 2442 Level: advanced 2443 2444 .seealso: PetscOptionsAllUsed() 2445 @*/ 2446 PetscErrorCode PetscOptionsLeft(PetscOptions options) 2447 { 2448 PetscErrorCode ierr; 2449 PetscInt i; 2450 2451 PetscFunctionBegin; 2452 options = options ? options : defaultoptions; 2453 for (i=0; i<options->N; i++) { 2454 if (!options->used[i]) { 2455 if (options->values[i]) { 2456 ierr = PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);CHKERRQ(ierr); 2457 } else { 2458 ierr = PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);CHKERRQ(ierr); 2459 } 2460 } 2461 } 2462 PetscFunctionReturn(0); 2463 } 2464 2465 /*@ 2466 PetscOptionsCreate - Creates the empty options database. 2467 2468 Output Parameter: 2469 . options - Options database object 2470 2471 Level: advanced 2472 2473 @*/ 2474 PetscErrorCode PetscOptionsCreate(PetscOptions *options) 2475 { 2476 *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions)); 2477 if (!options) return PETSC_ERR_MEM; 2478 (*options)->namegiven = PETSC_FALSE; 2479 (*options)->N = 0; 2480 (*options)->Naliases = 0; 2481 (*options)->numbermonitors = 0; 2482 return 0; 2483 } 2484 2485 /* 2486 PetscOptionsCreateDefault - Creates the default global options database 2487 2488 */ 2489 PetscErrorCode PetscOptionsCreateDefault(void) 2490 { 2491 PetscErrorCode ierr; 2492 2493 if (!defaultoptions) { 2494 ierr = PetscOptionsCreate(&defaultoptions);if (ierr) return ierr; 2495 } 2496 return 0; 2497 } 2498 2499 /*@C 2500 PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc 2501 2502 Collective on PETSC_COMM_WORLD 2503 2504 Input Parameter: 2505 . options - options database use NULL for default global database 2506 2507 Options Database Keys: 2508 + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not 2509 available for options set through a file, environment variable, or on 2510 the command line. Only options set after PetscInitialize() completes will 2511 be monitored. 2512 . -options_monitor_cancel - cancel all options database monitors 2513 2514 Notes: 2515 To see all options, run your program with the -help option or consult Users-Manual: sec_gettingstarted 2516 2517 Level: intermediate 2518 2519 .keywords: set, options, database 2520 @*/ 2521 PetscErrorCode PetscOptionsSetFromOptions(PetscOptions options) 2522 { 2523 PetscBool flgc = PETSC_FALSE,flgm; 2524 PetscErrorCode ierr; 2525 char monfilename[PETSC_MAX_PATH_LEN]; 2526 PetscViewer monviewer; 2527 2528 PetscFunctionBegin; 2529 /* 2530 The options argument is currently ignored since we currently maintain only a single options database 2531 2532 options = options ? options : defaultoptions; 2533 */ 2534 ierr = PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");CHKERRQ(ierr); 2535 ierr = PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);CHKERRQ(ierr); 2536 ierr = PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);CHKERRQ(ierr); 2537 ierr = PetscOptionsEnd();CHKERRQ(ierr); 2538 if (flgm) { 2539 ierr = PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);CHKERRQ(ierr); 2540 ierr = PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);CHKERRQ(ierr); 2541 } 2542 if (flgc) { ierr = PetscOptionsMonitorCancel();CHKERRQ(ierr); } 2543 PetscFunctionReturn(0); 2544 } 2545 2546 2547 /*@C 2548 PetscOptionsMonitorDefault - Print all options set value events. 2549 2550 Logically Collective on PETSC_COMM_WORLD 2551 2552 Input Parameters: 2553 + name - option name string 2554 . value - option value string 2555 - dummy - an ASCII viewer 2556 2557 Level: intermediate 2558 2559 .keywords: PetscOptions, default, monitor 2560 2561 .seealso: PetscOptionsMonitorSet() 2562 @*/ 2563 PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy) 2564 { 2565 PetscErrorCode ierr; 2566 PetscViewer viewer = (PetscViewer) dummy; 2567 2568 PetscFunctionBegin; 2569 ierr = PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);CHKERRQ(ierr); 2570 PetscFunctionReturn(0); 2571 } 2572 2573 /*@C 2574 PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that 2575 modified the PETSc options database. 2576 2577 Not collective 2578 2579 Input Parameters: 2580 + monitor - pointer to function (if this is NULL, it turns off monitoring 2581 . mctx - [optional] context for private data for the 2582 monitor routine (use NULL if no context is desired) 2583 - monitordestroy - [optional] routine that frees monitor context 2584 (may be NULL) 2585 2586 Calling Sequence of monitor: 2587 $ monitor (const char name[], const char value[], void *mctx) 2588 2589 + name - option name string 2590 . value - option value string 2591 - mctx - optional monitoring context, as set by PetscOptionsMonitorSet() 2592 2593 Options Database Keys: 2594 + -options_monitor - sets PetscOptionsMonitorDefault() 2595 - -options_monitor_cancel - cancels all monitors that have 2596 been hardwired into a code by 2597 calls to PetscOptionsMonitorSet(), but 2598 does not cancel those set via 2599 the options database. 2600 2601 Notes: 2602 The default is to do nothing. To print the name and value of options 2603 being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine, 2604 with a null monitoring context. 2605 2606 Several different monitoring routines may be set by calling 2607 PetscOptionsMonitorSet() multiple times; all will be called in the 2608 order in which they were set. 2609 2610 Level: beginner 2611 2612 .keywords: PetscOptions, set, monitor 2613 2614 .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel() 2615 @*/ 2616 PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**)) 2617 { 2618 PetscOptions options = defaultoptions; 2619 2620 PetscFunctionBegin; 2621 if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set"); 2622 options->monitor[options->numbermonitors] = monitor; 2623 options->monitordestroy[options->numbermonitors] = monitordestroy; 2624 options->monitorcontext[options->numbermonitors++] = (void*)mctx; 2625 PetscFunctionReturn(0); 2626 } 2627 2628 /*@ 2629 PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object. 2630 2631 Not collective 2632 2633 Options Database Key: 2634 . -options_monitor_cancel - Cancels all monitors that have 2635 been hardwired into a code by calls to PetscOptionsMonitorSet(), 2636 but does not cancel those set via the options database. 2637 2638 Level: intermediate 2639 2640 .keywords: PetscOptions, set, monitor 2641 2642 .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet() 2643 @*/ 2644 PetscErrorCode PetscOptionsMonitorCancel(void) 2645 { 2646 PetscErrorCode ierr; 2647 PetscInt i; 2648 PetscOptions options = defaultoptions; 2649 2650 PetscFunctionBegin; 2651 for (i=0; i<options->numbermonitors; i++) { 2652 if (options->monitordestroy[i]) { 2653 ierr = (*options->monitordestroy[i])(&options->monitorcontext[i]);CHKERRQ(ierr); 2654 } 2655 } 2656 options->numbermonitors = 0; 2657 PetscFunctionReturn(0); 2658 } 2659 2660 #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; CHKERRQ(ierr);} 2661 2662 /*@C 2663 PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed. 2664 2665 Collective on PetscObject 2666 2667 Input Parameters: 2668 + obj - the object 2669 . bobj - optional other object that provides prefix (if NULL then the prefix in obj is used) 2670 - optionname - option to activate viewing 2671 2672 Level: intermediate 2673 2674 @*/ 2675 PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[]) 2676 { 2677 PetscErrorCode ierr; 2678 PetscViewer viewer; 2679 PetscBool flg; 2680 static PetscBool incall = PETSC_FALSE; 2681 PetscViewerFormat format; 2682 char *prefix; 2683 2684 PetscFunctionBegin; 2685 if (incall) PetscFunctionReturn(0); 2686 incall = PETSC_TRUE; 2687 prefix = bobj ? bobj->prefix : obj->prefix; 2688 ierr = PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr); 2689 if (flg) { 2690 ierr = PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr); 2691 ierr = PetscObjectView(obj,viewer);CHKERRQI(incall,ierr); 2692 ierr = PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr); 2693 ierr = PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr); 2694 } 2695 incall = PETSC_FALSE; 2696 PetscFunctionReturn(0); 2697 } 2698