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