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