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