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