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