Actual source code: options.c
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 <petscsys.h> /*I "petscsys.h" I*/
14: #include <ctype.h>
15: #if defined(PETSC_HAVE_STDLIB_H)
16: #include <stdlib.h>
17: #endif
18: #if defined(PETSC_HAVE_MALLOC_H)
19: #include <malloc.h>
20: #endif
21: #if defined(PETSC_HAVE_SYS_PARAM_H)
22: #include <sys/param.h>
23: #endif
24: #if defined(PETSC_HAVE_YAML)
25: #include <yaml.h>
26: #endif
28: /*
29: This table holds all the options set by the user. For simplicity, we use a static size database
30: */
31: #define MAXOPTIONS 512
32: #define MAXALIASES 25
33: #define MAXOPTIONSMONITORS 5
34: #define MAXPREFIXES 25
36: typedef struct {
37: int N,argc,Naliases;
38: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
39: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
40: PetscBool used[MAXOPTIONS];
41: PetscBool namegiven;
42: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
44: /* --------User (or default) routines (most return -1 on error) --------*/
45: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
46: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**); /* */
47: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
48: PetscInt numbermonitors; /* to, for instance, detect options being set */
50: /* Prefixes */
51: PetscInt prefixind,prefixstack[MAXPREFIXES];
52: char prefix[2048];
53: } PetscOptionsTable;
56: static PetscOptionsTable *options = 0;
59: /*
60: Options events monitor
61: */
62: #define PetscOptionsMonitor(name,value) \
63: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
64: for (_i=0; _i<_im; _i++) {\
65: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
66: } \
67: }
71: /*
72: PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
73: */
74: PetscErrorCode PetscOptionsStringToInt(const char name[],PetscInt *a)
75: {
77: size_t i,len;
78: PetscBool decide,tdefault,mouse;
81: PetscStrlen(name,&len);
82: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
84: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
85: if (!tdefault) {
86: PetscStrcasecmp(name,"DEFAULT",&tdefault);
87: }
88: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
89: if (!decide) {
90: PetscStrcasecmp(name,"DECIDE",&decide);
91: }
92: PetscStrcasecmp(name,"mouse",&mouse);
94: if (tdefault) {
95: *a = PETSC_DEFAULT;
96: } else if (decide) {
97: *a = PETSC_DECIDE;
98: } else if (mouse) {
99: *a = -1;
100: } else {
101: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
102: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
103: }
104: for (i=1; i<len; i++) {
105: if (name[i] < '0' || name[i] > '9') {
106: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
107: }
108: }
110: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
111: *a = atoll(name);
112: #else
113: *a = (PetscInt)atoi(name);
114: #endif
115: }
116: return(0);
117: }
121: /*
122: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
123: */
124: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
125: {
127: size_t len;
128: PetscBool decide,tdefault;
131: PetscStrlen(name,&len);
132: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
134: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
135: if (!tdefault) {
136: PetscStrcasecmp(name,"DEFAULT",&tdefault);
137: }
138: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
139: if (!decide) {
140: PetscStrcasecmp(name,"DECIDE",&decide);
141: }
143: if (tdefault) {
144: *a = PETSC_DEFAULT;
145: } else if (decide) {
146: *a = PETSC_DECIDE;
147: } else {
148: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
149: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
150: }
151: *a = atof(name);
152: }
153: return(0);
154: }
158: /*
159: PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
160: */
161: PetscErrorCode PetscOptionsStringToBool(const char value[], PetscBool *a)
162: {
163: PetscBool istrue, isfalse;
164: size_t len;
168: PetscStrlen(value, &len);
169: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
170: PetscStrcasecmp(value,"TRUE",&istrue);
171: if (istrue) {*a = PETSC_TRUE; return(0);}
172: PetscStrcasecmp(value,"YES",&istrue);
173: if (istrue) {*a = PETSC_TRUE; return(0);}
174: PetscStrcasecmp(value,"1",&istrue);
175: if (istrue) {*a = PETSC_TRUE; return(0);}
176: PetscStrcasecmp(value,"on",&istrue);
177: if (istrue) {*a = PETSC_TRUE; return(0);}
178: PetscStrcasecmp(value,"FALSE",&isfalse);
179: if (isfalse) {*a = PETSC_FALSE; return(0);}
180: PetscStrcasecmp(value,"NO",&isfalse);
181: if (isfalse) {*a = PETSC_FALSE; return(0);}
182: PetscStrcasecmp(value,"0",&isfalse);
183: if (isfalse) {*a = PETSC_FALSE; return(0);}
184: PetscStrcasecmp(value,"off",&isfalse);
185: if (isfalse) {*a = PETSC_FALSE; return(0);}
186: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
187: return(0);
188: }
192: /*@C
193: PetscGetProgramName - Gets the name of the running program.
195: Not Collective
197: Input Parameter:
198: . len - length of the string name
200: Output Parameter:
201: . name - the name of the running program
203: Level: advanced
205: Notes:
206: The name of the program is copied into the user-provided character
207: array of length len. On some machines the program name includes
208: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
209: @*/
210: PetscErrorCode PetscGetProgramName(char name[],size_t len)
211: {
215: if (!options) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
216: if (!options->namegiven) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Unable to determine program name");
217: PetscStrncpy(name,options->programname,len);
218: return(0);
219: }
223: PetscErrorCode PetscSetProgramName(const char name[])
224: {
228: options->namegiven = PETSC_TRUE;
229: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
230: return(0);
231: }
235: /*@
236: PetscOptionsValidKey - PETSc Options database keys must begin with a - followed by a letter.
238: Input Parameter:
239: . in_str - string to check if valid
241: Output Parameter:
242: . key - PETSC_TRUE if a valid key
244: Level: intermediate
246: @*/
247: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscBool *key)
248: {
250: *key = PETSC_FALSE;
251: if (!in_str) return(0);
252: if (in_str[0] != '-') return(0);
253: if (!(isalpha(in_str[1]))) return(0);
254: if ((!strncmp(in_str+1,"inf",3) || !strncmp(in_str+1,"INF",3)) && !(in_str[4] == '_' || isalnum(in_str[4]))) return(0);
255: *key = PETSC_TRUE;
256: return(0);
257: }
261: /*@C
262: PetscOptionsInsertString - Inserts options into the database from a string
264: Not collective: but only processes that call this routine will set the options
265: included in the string
267: Input Parameter:
268: . in_str - string that contains options separated by blanks
271: Level: intermediate
273: Contributed by Boyana Norris
275: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
276: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
277: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
278: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
279: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
280: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
282: @*/
283: PetscErrorCode PetscOptionsInsertString(const char in_str[])
284: {
285: char *first,*second;
287: PetscToken token;
288: PetscBool key,ispush,ispop;
291: PetscTokenCreate(in_str,' ',&token);
292: PetscTokenFind(token,&first);
293: while (first) {
294: PetscStrcasecmp(first,"-prefix_push",&ispush);
295: PetscStrcasecmp(first,"-prefix_pop",&ispop);
296: PetscOptionsValidKey(first,&key);
297: if (ispush) {
298: PetscTokenFind(token,&second);
299: PetscOptionsPrefixPush(second);
300: PetscTokenFind(token,&first);
301: } else if (ispop) {
302: PetscOptionsPrefixPop();
303: PetscTokenFind(token,&first);
304: } else if (key) {
305: PetscTokenFind(token,&second);
306: PetscOptionsValidKey(second,&key);
307: if (!key) {
308: PetscOptionsSetValue(first,second);
309: PetscTokenFind(token,&first);
310: } else {
311: PetscOptionsSetValue(first,PETSC_NULL);
312: first = second;
313: }
314: } else {
315: PetscTokenFind(token,&first);
316: }
317: }
318: PetscTokenDestroy(token);
319: return(0);
320: }
322: /*
323: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
324: */
325: static char *Petscgetline(FILE * f)
326: {
327: size_t size = 0;
328: size_t len = 0;
329: size_t last = 0;
330: char * buf = PETSC_NULL;
332: if (feof(f)) return 0;
333: do {
334: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
335: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
336: /* Actually do the read. Note that fgets puts a terminal '\0' on the
337: end of the string, so we make sure we overwrite this */
338: if (!fgets(buf+len,size,f)) buf[len]=0;
339: PetscStrlen(buf,&len);
340: last = len - 1;
341: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
342: if (len) return buf;
343: free(buf);
344: return 0;
345: }
350: /*@C
351: PetscOptionsInsertFile - Inserts options into the database from a file.
353: Collective on MPI_Comm
355: Input Parameter:
356: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
357: . file - name of file
358: - require - if PETSC_TRUE will generate an error if the file does not exist
361: Level: developer
363: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
364: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
365: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
366: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
367: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
368: PetscOptionsList(), PetscOptionsEList()
370: @*/
371: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
372: {
373: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
375: size_t i,len;
376: FILE *fd;
377: PetscToken token;
378: int err;
379: char cmt[3]={'#','!','%'},*cmatch;
380: PetscMPIInt rank,cnt=0,acnt=0;
383: MPI_Comm_rank(comm,&rank);
384: if (!rank) {
385: /* Warning: assume a maximum size for all options in a string */
386: PetscMalloc(128000*sizeof(char),&vstring);
387: vstring[0] = 0;
388: PetscMalloc(64000*sizeof(char),&astring);
389: astring[0] = 0;
390: cnt = 0;
391: acnt = 0;
393: PetscFixFilename(file,fname);
394: fd = fopen(fname,"r");
395: if (fd) {
396: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
397: PetscInfo1(0,"Opened options file %s\n",file);
398: while ((string = Petscgetline(fd))) {
399: /* eliminate comments from each line */
400: for (i=0; i<3; i++){
401: PetscStrchr(string,cmt[i],&cmatch);
402: if (cmatch) *cmatch = 0;
403: }
404: PetscStrlen(string,&len);
405: /* replace tabs, ^M, \n with " " */
406: for (i=0; i<len; i++) {
407: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
408: string[i] = ' ';
409: }
410: }
411: PetscTokenCreate(string,' ',&token);
412: free(string);
413: PetscTokenFind(token,&first);
414: if (!first) {
415: goto destroy;
416: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
417: PetscTokenFind(token,&first);
418: }
419: PetscTokenFind(token,&second);
420: if (!first) {
421: goto destroy;
422: } else if (first[0] == '-') {
423: /* warning: should be making sure we do not overfill vstring */
424: PetscStrcat(vstring,first);
425: PetscStrcat(vstring," ");
426: if (second) {
427: /* protect second with quotes in case it contains strings */
428: PetscStrcat(vstring,"\"");
429: PetscStrcat(vstring,second);
430: PetscStrcat(vstring,"\"");
431: }
432: PetscStrcat(vstring," ");
433: } else {
434: PetscBool match;
436: PetscStrcasecmp(first,"alias",&match);
437: if (match) {
438: PetscTokenFind(token,&third);
439: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
440: PetscStrcat(astring,second);
441: PetscStrcat(astring," ");
442: PetscStrcat(astring,third);
443: PetscStrcat(astring," ");
444: } else {
445: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
446: }
447: }
448: destroy:
449: PetscTokenDestroy(token);
450: }
451: err = fclose(fd);
452: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
453: PetscStrlen(astring,&len);
454: acnt = PetscMPIIntCast(len);
455: PetscStrlen(vstring,&len);
456: cnt = PetscMPIIntCast(len);
457: } else if (require) {
458: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
459: }
460: }
462: MPI_Bcast(&acnt,1,MPI_INT,0,comm);
463: if (acnt) {
464: PetscToken token;
465: char *first,*second;
467: if (rank) {
468: PetscMalloc((acnt+1)*sizeof(char),&astring);
469: }
470: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
471: astring[acnt] = 0;
472: PetscTokenCreate(astring,' ',&token);
473: PetscTokenFind(token,&first);
474: while (first) {
475: PetscTokenFind(token,&second);
476: PetscOptionsSetAlias(first,second);
477: PetscTokenFind(token,&first);
478: }
479: PetscTokenDestroy(token);
480: }
482: MPI_Bcast(&cnt,1,MPI_INT,0,comm);
483: if (cnt) {
484: if (rank) {
485: PetscMalloc((cnt+1)*sizeof(char),&vstring);
486: }
487: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
488: vstring[cnt] = 0;
489: PetscOptionsInsertString(vstring);
490: }
491: PetscFree(astring);
492: PetscFree(vstring);
493: return(0);
494: }
498: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
499: {
501: int left = argc - 1;
502: char **eargs = args + 1;
505: while (left) {
506: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank;
507: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
508: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
509: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
510: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
511: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
512: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
513: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
514: isp4 = (PetscBool) (isp4 || tisp4);
515: PetscStrcasecmp(eargs[0],"-np",&tisp4);
516: isp4 = (PetscBool) (isp4 || tisp4);
517: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
519: if (eargs[0][0] != '-') {
520: eargs++; left--;
521: } else if (isoptions_file) {
522: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
523: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
524: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
525: eargs += 2; left -= 2;
526: } else if (isprefixpush) {
527: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
528: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
529: PetscOptionsPrefixPush(eargs[1]);
530: eargs += 2; left -= 2;
531: } else if (isprefixpop) {
532: PetscOptionsPrefixPop();
533: eargs++; left--;
535: /*
536: These are "bad" options that MPICH, etc put on the command line
537: we strip them out here.
538: */
539: } else if (tisp4 || isp4rmrank) {
540: eargs += 1; left -= 1;
541: } else if (isp4 || isp4yourname) {
542: eargs += 2; left -= 2;
543: } else {
544: PetscBool nextiskey = PETSC_FALSE;
545: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
546: if (left < 2 || nextiskey) {
547: PetscOptionsSetValue(eargs[0],PETSC_NULL);
548: eargs++; left--;
549: } else {
550: PetscOptionsSetValue(eargs[0],eargs[1]);
551: eargs += 2; left -= 2;
552: }
553: }
554: }
555: return(0);
556: }
561: /*@C
562: PetscOptionsInsert - Inserts into the options database from the command line,
563: the environmental variable and a file.
565: Input Parameters:
566: + argc - count of number of command line arguments
567: . args - the command line arguments
568: - file - optional filename, defaults to ~username/.petscrc
570: Note:
571: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
572: the user does not typically need to call this routine. PetscOptionsInsert()
573: can be called several times, adding additional entries into the database.
575: Options Database Keys:
576: + -options_monitor <optional filename> - print options names and values as they are set
577: . -options_file <filename> - read options from a file
579: Level: advanced
581: Concepts: options database^adding
583: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
584: PetscInitialize()
585: @*/
586: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
587: {
589: PetscMPIInt rank;
590: char pfile[PETSC_MAX_PATH_LEN];
591: PetscBool flag = PETSC_FALSE;
594: if (!options) {
595: fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
596: MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
597: }
598: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
600: options->argc = (argc) ? *argc : 0;
601: options->args = (args) ? *args : PETSC_NULL;
603: if (file && file[0]) {
604: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
605: }
606: /*
607: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
608: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
609: */
610: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
611: PetscOptionsGetBool(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
612: if (!flag) {
613: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
614: /* warning: assumes all processes have a home directory or none, but nothing in between */
615: if (pfile[0]) {
616: PetscStrcat(pfile,"/.petscrc");
617: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
618: }
619: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
620: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
621: }
623: /* insert environmental options */
624: {
625: char *eoptions = 0;
626: size_t len = 0;
627: if (!rank) {
628: eoptions = (char*)getenv("PETSC_OPTIONS");
629: PetscStrlen(eoptions,&len);
630: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
631: } else {
632: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
633: if (len) {
634: PetscMalloc((len+1)*sizeof(char*),&eoptions);
635: }
636: }
637: if (len) {
638: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
639: if (rank) eoptions[len] = 0;
640: PetscOptionsInsertString(eoptions);
641: if (rank) {PetscFree(eoptions);}
642: }
643: }
645: #if defined(PETSC_HAVE_YAML)
646: char yaml_file[PETSC_MAX_PATH_LEN];
647: PetscBool yaml_flg = PETSC_FALSE;
648: PetscOptionsGetString(PETSC_NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
649: if (yaml_flg) PetscOptionsInsertFile_YAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
650: #endif
652: /* insert command line options again because they take precedence over arguments in petscrc/environment */
653: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
655: return(0);
656: }
660: /*@C
661: PetscOptionsView - Prints the options that have been loaded. This is
662: useful for debugging purposes.
664: Logically Collective on PetscViewer
666: Input Parameter:
667: . viewer - must be an PETSCVIEWERASCII viewer
669: Options Database Key:
670: . -optionstable - Activates PetscOptionsView() within PetscFinalize()
672: Level: advanced
674: Concepts: options database^printing
676: .seealso: PetscOptionsAllUsed()
677: @*/
678: PetscErrorCode PetscOptionsView(PetscViewer viewer)
679: {
681: PetscInt i;
682: PetscBool isascii;
685: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
686: PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
687: if (!isascii) SETERRQ(((PetscObject)viewer)->comm,PETSC_ERR_SUP,"Only supports ASCII viewer");
689: if (!options) {PetscOptionsInsert(0,0,0);}
690: if (options->N) {
691: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
692: } else {
693: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
694: }
695: for (i=0; i<options->N; i++) {
696: if (options->values[i]) {
697: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
698: } else {
699: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
700: }
701: }
702: if (options->N) {
703: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
704: }
705: return(0);
706: }
710: /*@C
711: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
713: Not Collective
715: Output Parameter:
716: . copts - pointer where string pointer is stored
718: Notes: the array and each entry in the array should be freed with PetscFree()
720: Level: advanced
722: Concepts: options database^listing
724: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
725: @*/
726: PetscErrorCode PetscOptionsGetAll(char *copts[])
727: {
729: PetscInt i;
730: size_t len = 1,lent;
731: char *coptions;
734: if (!options) {PetscOptionsInsert(0,0,0);}
736: /* count the length of the required string */
737: for (i=0; i<options->N; i++) {
738: PetscStrlen(options->names[i],&lent);
739: len += 2 + lent;
740: if (options->values[i]) {
741: PetscStrlen(options->values[i],&lent);
742: len += 1 + lent;
743: }
744: }
745: PetscMalloc(len*sizeof(char),&coptions);
746: coptions[0] = 0;
747: for (i=0; i<options->N; i++) {
748: PetscStrcat(coptions,"-");
749: PetscStrcat(coptions,options->names[i]);
750: PetscStrcat(coptions," ");
751: if (options->values[i]) {
752: PetscStrcat(coptions,options->values[i]);
753: PetscStrcat(coptions," ");
754: }
755: }
756: *copts = coptions;
757: return(0);
758: }
762: /*@
763: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
765: Not Collective, but prefix will only be applied on calling ranks
767: Input Parameter:
768: . prefix - The string to append to the existing prefix
770: Options Database Keys:
771: + -prefix_push <some_prefix_> - push the given prefix
772: - -prefix_pop - pop the last prefix
774: Notes:
775: It is common to use this in conjunction with -options_file as in
777: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
779: where the files no longer require all options to be prefixed with -system2_.
781: Level: advanced
783: .seealso: PetscOptionsPrefixPop()
784: @*/
785: PetscErrorCode PetscOptionsPrefixPush(const char prefix[])
786: {
788: size_t n;
789: PetscInt start;
790: char buf[2048];
791: PetscBool key;
795: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
796: buf[0] = '-';
797: PetscStrncpy(buf+1,prefix,sizeof buf - 1);
798: buf[sizeof buf - 1] = 0;
799: PetscOptionsValidKey(buf,&key);
800: 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);
802: if (!options) {PetscOptionsInsert(0,0,0);}
803: 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);
804: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
805: PetscStrlen(prefix,&n);
806: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
807: PetscMemcpy(options->prefix+start,prefix,n+1);
808: options->prefixstack[options->prefixind++] = start+n;
809: return(0);
810: }
814: /*@
815: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
817: Not Collective, but prefix will only be popped on calling ranks
819: Level: advanced
821: .seealso: PetscOptionsPrefixPush()
822: @*/
823: PetscErrorCode PetscOptionsPrefixPop(void)
824: {
825: PetscInt offset;
828: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
829: options->prefixind--;
830: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
831: options->prefix[offset] = 0;
832: return(0);
833: }
837: /*@C
838: PetscOptionsClear - Removes all options form the database leaving it empty.
840: Level: developer
842: .seealso: PetscOptionsInsert()
843: @*/
844: PetscErrorCode PetscOptionsClear(void)
845: {
846: PetscInt i;
849: if (!options) return(0);
850: for (i=0; i<options->N; i++) {
851: if (options->names[i]) free(options->names[i]);
852: if (options->values[i]) free(options->values[i]);
853: }
854: for (i=0; i<options->Naliases; i++) {
855: free(options->aliases1[i]);
856: free(options->aliases2[i]);
857: }
858: options->prefix[0] = 0;
859: options->prefixind = 0;
860: options->N = 0;
861: options->Naliases = 0;
862: return(0);
863: }
867: /*@C
868: PetscOptionsDestroy - Destroys the option database.
870: Note:
871: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
872: typically does not need to call this routine.
874: Level: developer
876: .seealso: PetscOptionsInsert()
877: @*/
878: PetscErrorCode PetscOptionsDestroy(void)
879: {
883: if (!options) return(0);
884: PetscOptionsClear();
885: free(options);
886: options = 0;
887: return(0);
888: }
892: /*@C
893: PetscOptionsSetValue - Sets an option name-value pair in the options
894: database, overriding whatever is already present.
896: Not collective, but setting values on certain processors could cause problems
897: for parallel objects looking for options.
899: Input Parameters:
900: + name - name of option, this SHOULD have the - prepended
901: - value - the option value (not used for all options)
903: Level: intermediate
905: Note:
906: Only some options have values associated with them, such as
907: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
909: Concepts: options database^adding option
911: .seealso: PetscOptionsInsert()
912: @*/
913: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
914: {
915: size_t len;
917: PetscInt N,n,i;
918: char **names;
919: char fullname[2048];
920: const char *name = iname;
921: PetscBool gt,match;
924: if (!options) {PetscOptionsInsert(0,0,0);}
926: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
927: PetscStrcasecmp(name,"-h",&match);
928: if (match) name = "-help";
930: name++; /* skip starting hyphen */
931: if (options->prefixind > 0) {
932: PetscStrncpy(fullname,options->prefix,sizeof fullname);
933: PetscStrncat(fullname,name,sizeof fullname);
934: name = fullname;
935: }
937: /* check against aliases */
938: N = options->Naliases;
939: for (i=0; i<N; i++) {
940: PetscStrcasecmp(options->aliases1[i],name,&match);
941: if (match) {
942: name = options->aliases2[i];
943: break;
944: }
945: }
947: N = options->N;
948: n = N;
949: names = options->names;
950:
951: for (i=0; i<N; i++) {
952: PetscStrcasecmp(names[i],name,&match);
953: PetscStrgrt(names[i],name,>);
954: if (match) {
955: if (options->values[i]) free(options->values[i]);
956: PetscStrlen(value,&len);
957: if (len) {
958: options->values[i] = (char*)malloc((len+1)*sizeof(char));
959: PetscStrcpy(options->values[i],value);
960: } else { options->values[i] = 0;}
961: PetscOptionsMonitor(name,value);
962: return(0);
963: } else if (gt) {
964: n = i;
965: break;
966: }
967: }
968: if (N >= MAXOPTIONS) {
969: 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);
970: }
971: /* shift remaining values down 1 */
972: for (i=N; i>n; i--) {
973: options->names[i] = options->names[i-1];
974: options->values[i] = options->values[i-1];
975: options->used[i] = options->used[i-1];
976: }
977: /* insert new name and value */
978: PetscStrlen(name,&len);
979: options->names[n] = (char*)malloc((len+1)*sizeof(char));
980: PetscStrcpy(options->names[n],name);
981: PetscStrlen(value,&len);
982: if (len) {
983: options->values[n] = (char*)malloc((len+1)*sizeof(char));
984: PetscStrcpy(options->values[n],value);
985: } else {options->values[n] = 0;}
986: options->used[n] = PETSC_FALSE;
987: options->N++;
988: PetscOptionsMonitor(name,value);
989: return(0);
990: }
994: /*@C
995: PetscOptionsClearValue - Clears an option name-value pair in the options
996: database, overriding whatever is already present.
998: Not Collective, but setting values on certain processors could cause problems
999: for parallel objects looking for options.
1001: Input Parameter:
1002: . name - name of option, this SHOULD have the - prepended
1004: Level: intermediate
1006: Concepts: options database^removing option
1007: .seealso: PetscOptionsInsert()
1008: @*/
1009: PetscErrorCode PetscOptionsClearValue(const char iname[])
1010: {
1012: PetscInt N,n,i;
1013: char **names,*name=(char*)iname;
1014: PetscBool gt,match;
1017: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1018: if (!options) {PetscOptionsInsert(0,0,0);}
1020: name++;
1022: N = options->N; n = 0;
1023: names = options->names;
1024:
1025: for (i=0; i<N; i++) {
1026: PetscStrcasecmp(names[i],name,&match);
1027: PetscStrgrt(names[i],name,>);
1028: if (match) {
1029: if (options->names[i]) free(options->names[i]);
1030: if (options->values[i]) free(options->values[i]);
1031: PetscOptionsMonitor(name,"");
1032: break;
1033: } else if (gt) {
1034: return(0); /* it was not listed */
1035: }
1036: n++;
1037: }
1038: if (n == N) return(0); /* it was not listed */
1040: /* shift remaining values down 1 */
1041: for (i=n; i<N-1; i++) {
1042: options->names[i] = options->names[i+1];
1043: options->values[i] = options->values[i+1];
1044: options->used[i] = options->used[i+1];
1045: }
1046: options->N--;
1047: return(0);
1048: }
1052: /*@C
1053: PetscOptionsSetAlias - Makes a key and alias for another key
1055: Not Collective, but setting values on certain processors could cause problems
1056: for parallel objects looking for options.
1058: Input Parameters:
1059: + inewname - the alias
1060: - ioldname - the name that alias will refer to
1062: Level: advanced
1064: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1065: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1066: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1067: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1068: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1069: PetscOptionsList(), PetscOptionsEList()
1070: @*/
1071: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
1072: {
1074: PetscInt n = options->Naliases;
1075: size_t len;
1076: char *newname = (char *)inewname,*oldname = (char*)ioldname;
1079: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1080: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1081: if (n >= MAXALIASES) {
1082: 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);
1083: }
1085: newname++; oldname++;
1086: PetscStrlen(newname,&len);
1087: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1088: PetscStrcpy(options->aliases1[n],newname);
1089: PetscStrlen(oldname,&len);
1090: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1091: PetscStrcpy(options->aliases2[n],oldname);
1092: options->Naliases++;
1093: return(0);
1094: }
1098: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool *flg)
1099: {
1101: PetscInt i,N;
1102: size_t len;
1103: char **names,tmp[256];
1104: PetscBool match;
1107: if (!options) {PetscOptionsInsert(0,0,0);}
1108: N = options->N;
1109: names = options->names;
1111: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1113: /* append prefix to name */
1114: if (pre) {
1115: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1116: PetscStrncpy(tmp,pre,256);
1117: PetscStrlen(tmp,&len);
1118: PetscStrncat(tmp,name+1,256-len-1);
1119: } else {
1120: PetscStrncpy(tmp,name+1,256);
1121: }
1123: /* slow search */
1124: *flg = PETSC_FALSE;
1125: for (i=0; i<N; i++) {
1126: PetscStrcasecmp(names[i],tmp,&match);
1127: if (match) {
1128: *value = options->values[i];
1129: options->used[i] = PETSC_TRUE;
1130: *flg = PETSC_TRUE;
1131: break;
1132: }
1133: }
1134: if (!*flg) {
1135: PetscInt j,cnt = 0,locs[16],loce[16];
1136: size_t n;
1137: PetscStrlen(tmp,&n);
1138: /* determine the location and number of all _%d_ in the key */
1139: for (i=0; i< (PetscInt)n; i++) {
1140: if (tmp[i] == '_') {
1141: for (j=i+1; j< (PetscInt)n; j++) {
1142: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1143: if (tmp[j] == '_' && j > i+1) { /* found a number */
1144: locs[cnt] = i+1;
1145: loce[cnt++] = j+1;
1146: }
1147: break;
1148: }
1149: }
1150: }
1151: if (cnt) {
1152: char tmp2[256];
1153: for (i=0; i<cnt; i++) {
1154: PetscStrcpy(tmp2,"-");
1155: PetscStrncat(tmp2,tmp,locs[i]);
1156: PetscStrcat(tmp2,tmp+loce[i]);
1157: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1158: if (*flg) break;
1159: }
1160: }
1161: }
1162: return(0);
1163: }
1167: /*@C
1168: PetscOptionsReject - Generates an error if a certain option is given.
1170: Not Collective, but setting values on certain processors could cause problems
1171: for parallel objects looking for options.
1173: Input Parameters:
1174: + name - the option one is seeking
1175: - mess - error message (may be PETSC_NULL)
1177: Level: advanced
1179: Concepts: options database^rejecting option
1181: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1182: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1183: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1184: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1185: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1186: PetscOptionsList(), PetscOptionsEList()
1187: @*/
1188: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1189: {
1191: PetscBool flag = PETSC_FALSE;
1194: PetscOptionsHasName(PETSC_NULL,name,&flag);
1195: if (flag) {
1196: if (mess) {
1197: SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1198: } else {
1199: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1200: }
1201: }
1202: return(0);
1203: }
1207: /*@C
1208: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1209: its value is set to false.
1211: Not Collective
1213: Input Parameters:
1214: + name - the option one is seeking
1215: - pre - string to prepend to the name or PETSC_NULL
1217: Output Parameters:
1218: . set - PETSC_TRUE if found else PETSC_FALSE.
1220: Level: beginner
1222: Concepts: options database^has option name
1224: Notes: Name cannot be simply -h
1226: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1228: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1229: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1230: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1231: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1232: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1233: PetscOptionsList(), PetscOptionsEList()
1234: @*/
1235: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscBool *set)
1236: {
1237: char *value;
1239: PetscBool flag;
1242: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1243: if (set) *set = flag;
1244: return(0);
1245: }
1249: /*@C
1250: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1252: Not Collective
1254: Input Parameters:
1255: + pre - the string to prepend to the name or PETSC_NULL
1256: - name - the option one is seeking
1258: Output Parameter:
1259: + ivalue - the integer value to return
1260: - set - PETSC_TRUE if found, else PETSC_FALSE
1262: Level: beginner
1264: Concepts: options database^has int
1266: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1267: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1268: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1269: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1270: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1271: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1272: PetscOptionsList(), PetscOptionsEList()
1273: @*/
1274: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1275: {
1276: char *value;
1278: PetscBool flag;
1283: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1284: if (flag) {
1285: if (!value) {if (set) *set = PETSC_FALSE;}
1286: else {
1287: if (set) *set = PETSC_TRUE;
1288: PetscOptionsStringToInt(value,ivalue);
1289: }
1290: } else {
1291: if (set) *set = PETSC_FALSE;
1292: }
1293: return(0);
1294: }
1298: /*@C
1299: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1301: Not Collective
1303: Input Parameters:
1304: + pre - the string to prepend to the name or PETSC_NULL
1305: . opt - option name
1306: . list - the possible choices
1307: . ntext - number of choices
1309: Output Parameter:
1310: + value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1311: - set - PETSC_TRUE if found, else PETSC_FALSE
1312:
1313: Level: intermediate
1315: See PetscOptionsList() for when the choices are given in a PetscFList()
1317: Concepts: options database^list
1319: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1320: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1321: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1322: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1323: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1324: PetscOptionsList(), PetscOptionsEList()
1325: @*/
1326: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscBool *set)
1327: {
1329: size_t alen,len = 0;
1330: char *svalue;
1331: PetscBool aset,flg = PETSC_FALSE;
1332: PetscInt i;
1335: for ( i=0; i<ntext; i++) {
1336: PetscStrlen(list[i],&alen);
1337: if (alen > len) len = alen;
1338: }
1339: len += 5; /* a little extra space for user mistypes */
1340: PetscMalloc(len*sizeof(char),&svalue);
1341: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1342: if (aset) {
1343: if (set) *set = PETSC_TRUE;
1344: for (i=0; i<ntext; i++) {
1345: PetscStrcasecmp(svalue,list[i],&flg);
1346: if (flg || !svalue[0]) {
1347: flg = PETSC_TRUE;
1348: *value = i;
1349: break;
1350: }
1351: }
1352: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1353: } else if (set) {
1354: *set = PETSC_FALSE;
1355: }
1356: PetscFree(svalue);
1357: return(0);
1358: }
1362: /*@C
1363: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1365: Not Collective
1367: Input Parameters:
1368: + pre - option prefix or PETSC_NULL
1369: . opt - option name
1370: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1371: - defaultv - the default (current) value
1373: Output Parameter:
1374: + value - the value to return
1375: - set - PETSC_TRUE if found, else PETSC_FALSE
1377: Level: beginner
1379: Concepts: options database
1381: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1383: list is usually something like PCASMTypes or some other predefined list of enum names
1385: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1386: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1387: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1388: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1389: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1390: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1391: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1392: @*/
1393: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscBool *set)
1394: {
1396: PetscInt ntext = 0,tval;
1397: PetscBool fset;
1400: while (list[ntext++]) {
1401: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1402: }
1403: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1404: ntext -= 3;
1405: PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1406: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1407: if (fset) *value = (PetscEnum)tval;
1408: if (set) *set = fset;
1409: return(0);
1410: }
1414: /*@C
1415: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1416: option in the database.
1418: Not Collective
1420: Input Parameters:
1421: + pre - the string to prepend to the name or PETSC_NULL
1422: - name - the option one is seeking
1424: Output Parameter:
1425: + ivalue - the logical value to return
1426: - set - PETSC_TRUE if found, else PETSC_FALSE
1428: Level: beginner
1430: Notes:
1431: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1432: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1434: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1435: you NEED TO ALWAYS initialize the ivalue.
1437: Concepts: options database^has logical
1439: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1440: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1441: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1442: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1443: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1444: PetscOptionsList(), PetscOptionsEList()
1445: @*/
1446: PetscErrorCode PetscOptionsGetBool(const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1447: {
1448: char *value;
1449: PetscBool flag;
1455: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1456: if (flag) {
1457: if (set) *set = PETSC_TRUE;
1458: if (!value) {
1459: *ivalue = PETSC_TRUE;
1460: } else {
1461: PetscOptionsStringToBool(value, ivalue);
1462: }
1463: } else {
1464: if (set) *set = PETSC_FALSE;
1465: }
1466: return(0);
1467: }
1471: /*@C
1472: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1473: option in the database. The values must be separated with commas with
1474: no intervening spaces.
1476: Not Collective
1478: Input Parameters:
1479: + pre - string to prepend to each name or PETSC_NULL
1480: . name - the option one is seeking
1481: - nmax - maximum number of values to retrieve
1483: Output Parameter:
1484: + dvalue - the integer values to return
1485: . nmax - actual number of values retreived
1486: - set - PETSC_TRUE if found, else PETSC_FALSE
1488: Level: beginner
1490: Concepts: options database^array of ints
1492: Notes:
1493: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1494: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1496: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1497: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1498: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1499: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1500: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1501: PetscOptionsList(), PetscOptionsEList()
1502: @*/
1503: PetscErrorCode PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1504: {
1505: char *value;
1507: PetscInt n = 0;
1508: PetscBool flag;
1509: PetscToken token;
1514: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1515: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1516: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1518: if (set) *set = PETSC_TRUE;
1520: PetscTokenCreate(value,',',&token);
1521: PetscTokenFind(token,&value);
1522: while (n < *nmax) {
1523: if (!value) break;
1524: PetscOptionsStringToBool(value,dvalue);
1525: PetscTokenFind(token,&value);
1526: dvalue++;
1527: n++;
1528: }
1529: PetscTokenDestroy(token);
1530: *nmax = n;
1531: return(0);
1532: }
1536: /*@C
1537: PetscOptionsGetReal - Gets the double precision value for a particular
1538: option in the database.
1540: Not Collective
1542: Input Parameters:
1543: + pre - string to prepend to each name or PETSC_NULL
1544: - name - the option one is seeking
1546: Output Parameter:
1547: + dvalue - the double value to return
1548: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1550: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1552: Level: beginner
1554: Concepts: options database^has double
1556: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1557: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1558: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1559: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1560: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1561: PetscOptionsList(), PetscOptionsEList()
1562: @*/
1563: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1564: {
1565: char *value;
1567: PetscBool flag;
1572: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1573: if (flag) {
1574: if (!value) {if (set) *set = PETSC_FALSE;}
1575: else {if (set) *set = PETSC_TRUE; PetscOptionsStringToReal(value,dvalue);}
1576: } else {
1577: if (set) *set = PETSC_FALSE;
1578: }
1579: return(0);
1580: }
1584: /*@C
1585: PetscOptionsGetScalar - Gets the scalar value for a particular
1586: option in the database.
1588: Not Collective
1590: Input Parameters:
1591: + pre - string to prepend to each name or PETSC_NULL
1592: - name - the option one is seeking
1594: Output Parameter:
1595: + dvalue - the double value to return
1596: - set - PETSC_TRUE if found, else PETSC_FALSE
1598: Level: beginner
1600: Usage:
1601: A complex number 2+3i can be specified as 2,3 at the command line.
1602: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1604: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1606: Concepts: options database^has scalar
1608: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1609: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1610: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1611: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1612: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1613: PetscOptionsList(), PetscOptionsEList()
1614: @*/
1615: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1616: {
1617: char *value;
1618: PetscBool flag;
1624: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1625: if (flag) {
1626: if (!value) {
1627: if (set) *set = PETSC_FALSE;
1628: } else {
1629: #if !defined(PETSC_USE_COMPLEX)
1630: PetscOptionsStringToReal(value,dvalue);
1631: #else
1632: PetscReal re=0.0,im=0.0;
1633: PetscToken token;
1634: char *tvalue = 0;
1636: PetscTokenCreate(value,',',&token);
1637: PetscTokenFind(token,&tvalue);
1638: if (!tvalue) { SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1639: PetscOptionsStringToReal(tvalue,&re);
1640: PetscTokenFind(token,&tvalue);
1641: if (!tvalue) { /* Unknown separator used. using only real value */
1642: *dvalue = re;
1643: } else {
1644: PetscOptionsStringToReal(tvalue,&im);
1645: *dvalue = re + PETSC_i*im;
1646: }
1647: PetscTokenDestroy(token);
1648: #endif
1649: if (set) *set = PETSC_TRUE;
1650: }
1651: } else { /* flag */
1652: if (set) *set = PETSC_FALSE;
1653: }
1654: return(0);
1655: }
1659: /*@C
1660: PetscOptionsGetRealArray - Gets an array of double precision values for a
1661: particular option in the database. The values must be separated with
1662: commas with no intervening spaces.
1664: Not Collective
1666: Input Parameters:
1667: + pre - string to prepend to each name or PETSC_NULL
1668: . name - the option one is seeking
1669: - nmax - maximum number of values to retrieve
1671: Output Parameters:
1672: + dvalue - the double value to return
1673: . nmax - actual number of values retreived
1674: - set - PETSC_TRUE if found, else PETSC_FALSE
1676: Level: beginner
1678: Concepts: options database^array of doubles
1680: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1681: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1682: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1683: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1684: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1685: PetscOptionsList(), PetscOptionsEList()
1686: @*/
1687: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
1688: {
1689: char *value;
1691: PetscInt n = 0;
1692: PetscBool flag;
1693: PetscToken token;
1698: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1699: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1700: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1702: if (set) *set = PETSC_TRUE;
1704: PetscTokenCreate(value,',',&token);
1705: PetscTokenFind(token,&value);
1706: while (n < *nmax) {
1707: if (!value) break;
1708: PetscOptionsStringToReal(value,dvalue++);
1709: PetscTokenFind(token,&value);
1710: n++;
1711: }
1712: PetscTokenDestroy(token);
1713: *nmax = n;
1714: return(0);
1715: }
1719: /*@C
1720: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1721: option in the database. The values must be separated with commas with
1722: no intervening spaces.
1724: Not Collective
1726: Input Parameters:
1727: + pre - string to prepend to each name or PETSC_NULL
1728: . name - the option one is seeking
1729: - nmax - maximum number of values to retrieve, can include d-D to indicate d,d+1,..,D-1
1731: Output Parameter:
1732: + dvalue - the integer values to return
1733: . nmax - actual number of values retreived
1734: - set - PETSC_TRUE if found, else PETSC_FALSE
1736: Level: beginner
1738: Concepts: options database^array of ints
1740: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1741: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1742: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1743: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1744: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1745: PetscOptionsList(), PetscOptionsEList()
1746: @*/
1747: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
1748: {
1749: char *value;
1751: PetscInt n = 0,i,start,end;
1752: size_t len;
1753: PetscBool flag,foundrange;
1754: PetscToken token;
1759: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1760: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1761: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1763: if (set) *set = PETSC_TRUE;
1765: PetscTokenCreate(value,',',&token);
1766: PetscTokenFind(token,&value);
1767: while (n < *nmax) {
1768: if (!value) break;
1769:
1770: /* look for form d-D where d and D are integers */
1771: foundrange = PETSC_FALSE;
1772: PetscStrlen(value,&len);
1773: if (value[0] == '-') i=2;
1774: else i=1;
1775: for (;i<(int)len; i++) {
1776: if (value[i] == '-') {
1777: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1778: value[i] = 0;
1779: PetscOptionsStringToInt(value,&start);
1780: PetscOptionsStringToInt(value+i+1,&end);
1781: 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);
1782: if (n + end - start - 1 >= *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space in left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
1783: for (;start<end; start++) {
1784: *dvalue = start; dvalue++;n++;
1785: }
1786: foundrange = PETSC_TRUE;
1787: break;
1788: }
1789: }
1790: if (!foundrange) {
1791: PetscOptionsStringToInt(value,dvalue);
1792: dvalue++;
1793: n++;
1794: }
1795: PetscTokenFind(token,&value);
1796: }
1797: PetscTokenDestroy(token);
1798: *nmax = n;
1799: return(0);
1800: }
1804: /*@C
1805: PetscOptionsGetString - Gets the string value for a particular option in
1806: the database.
1808: Not Collective
1810: Input Parameters:
1811: + pre - string to prepend to name or PETSC_NULL
1812: . name - the option one is seeking
1813: - len - maximum length of the string including null termination
1815: Output Parameters:
1816: + string - location to copy string
1817: - set - PETSC_TRUE if found, else PETSC_FALSE
1819: Level: beginner
1821: Fortran Note:
1822: The Fortran interface is slightly different from the C/C++
1823: interface (len is not used). Sample usage in Fortran follows
1824: .vb
1825: character *20 string
1826: integer flg, ierr
1827: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1828: .ve
1830: 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
1832: Concepts: options database^string
1834: Note:
1835: 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).
1837: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1838: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1839: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1840: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1841: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1842: PetscOptionsList(), PetscOptionsEList()
1843: @*/
1844: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool *set)
1845: {
1846: char *value;
1848: PetscBool flag;
1853: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1854: if (!flag) {
1855: if (set) *set = PETSC_FALSE;
1856: } else {
1857: if (set) *set = PETSC_TRUE;
1858: if (value) {
1859: PetscStrncpy(string,value,len);
1860: string[len-1] = 0; /* Ensure that the string is NULL terminated */
1861: } else {
1862: PetscMemzero(string,len);
1863: }
1864: }
1865: return(0);
1866: }
1870: char* PetscOptionsGetStringMatlab(const char pre[],const char name[])
1871: {
1872: char *value;
1874: PetscBool flag;
1877: PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
1878: if (flag) PetscFunctionReturn(value);
1879: else return(0);
1880: }
1885: /*@C
1886: PetscOptionsGetStringArray - Gets an array of string values for a particular
1887: option in the database. The values must be separated with commas with
1888: no intervening spaces.
1890: Not Collective
1892: Input Parameters:
1893: + pre - string to prepend to name or PETSC_NULL
1894: . name - the option one is seeking
1895: - nmax - maximum number of strings
1897: Output Parameter:
1898: + strings - location to copy strings
1899: - set - PETSC_TRUE if found, else PETSC_FALSE
1901: Level: beginner
1903: Notes:
1904: The user should pass in an array of pointers to char, to hold all the
1905: strings returned by this function.
1907: The user is responsible for deallocating the strings that are
1908: returned. The Fortran interface for this routine is not supported.
1910: Contributed by Matthew Knepley.
1912: Concepts: options database^array of strings
1914: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1915: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1916: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1917: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1918: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1919: PetscOptionsList(), PetscOptionsEList()
1920: @*/
1921: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
1922: {
1923: char *value;
1925: PetscInt n;
1926: PetscBool flag;
1927: PetscToken token;
1928:
1932: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1933: if (!flag) {*nmax = 0; if (set) *set = PETSC_FALSE; return(0);}
1934: if (!value) {*nmax = 0; if (set) *set = PETSC_FALSE;return(0);}
1935: if (!*nmax) {if (set) *set = PETSC_FALSE;return(0);}
1936: if (set) *set = PETSC_TRUE;
1938: PetscTokenCreate(value,',',&token);
1939: PetscTokenFind(token,&value);
1940: n = 0;
1941: while (n < *nmax) {
1942: if (!value) break;
1943: PetscStrallocpy(value,&strings[n]);
1944: PetscTokenFind(token,&value);
1945: n++;
1946: }
1947: PetscTokenDestroy(token);
1948: *nmax = n;
1949: return(0);
1950: }
1954: /*@C
1955: PetscOptionsAllUsed - Returns a count of the number of options in the
1956: database that have never been selected.
1958: Not Collective
1960: Output Parameter:
1961: . N - count of options not used
1963: Level: advanced
1965: .seealso: PetscOptionsView()
1966: @*/
1967: PetscErrorCode PetscOptionsAllUsed(PetscInt *N)
1968: {
1969: PetscInt i,n = 0;
1972: for (i=0; i<options->N; i++) {
1973: if (!options->used[i]) { n++; }
1974: }
1975: *N = n;
1976: return(0);
1977: }
1981: /*@
1982: PetscOptionsLeft - Prints to screen any options that were set and never used.
1984: Not collective
1986: Options Database Key:
1987: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1989: Level: advanced
1991: .seealso: PetscOptionsAllUsed()
1992: @*/
1993: PetscErrorCode PetscOptionsLeft(void)
1994: {
1996: PetscInt i;
1999: for (i=0; i<options->N; i++) {
2000: if (!options->used[i]) {
2001: if (options->values[i]) {
2002: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2003: } else {
2004: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
2005: }
2006: }
2007: }
2008: return(0);
2009: }
2014: /*
2015: PetscOptionsCreate - Creates the empty options database.
2017: */
2018: PetscErrorCode PetscOptionsCreate(void)
2019: {
2023: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
2024: PetscMemzero(options,sizeof(PetscOptionsTable));
2025: options->namegiven = PETSC_FALSE;
2026: options->N = 0;
2027: options->Naliases = 0;
2028: options->numbermonitors = 0;
2030: PetscOptionsObject.prefix = PETSC_NULL;
2031: PetscOptionsObject.title = PETSC_NULL;
2032:
2033: return(0);
2034: }
2038: /*@
2039: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
2041: Collective on PETSC_COMM_WORLD
2043: Options Database Keys:
2044: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2045: available for options set through a file, environment variable, or on
2046: the command line. Only options set after PetscInitialize completes will
2047: be monitored.
2048: . -options_monitor_cancel - cancel all options database monitors
2050: Notes:
2051: To see all options, run your program with the -help option or consult
2052: the <A href="../../docs/manual.pdf">users manual</A>..
2054: Level: intermediate
2056: .keywords: set, options, database
2057: @*/
2058: PetscErrorCode PetscOptionsSetFromOptions(void)
2059: {
2060: PetscBool flgc,flgm;
2061: PetscErrorCode ierr;
2062: char monfilename[PETSC_MAX_PATH_LEN];
2063: PetscViewer monviewer;
2066: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
2067: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2068: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",PETSC_FALSE,&flgc,PETSC_NULL);
2069: PetscOptionsEnd();
2070: if (flgm) {
2071: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2072: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2073: }
2074: if (flgc) { PetscOptionsMonitorCancel(); }
2075: return(0);
2076: }
2081: /*@C
2082: PetscOptionsMonitorDefault - Print all options set value events.
2084: Logically Collective on PETSC_COMM_WORLD
2086: Input Parameters:
2087: + name - option name string
2088: . value - option value string
2089: - dummy - unused monitor context
2091: Level: intermediate
2093: .keywords: PetscOptions, default, monitor
2095: .seealso: PetscOptionsMonitorSet()
2096: @*/
2097: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2098: {
2100: PetscViewer viewer = (PetscViewer) dummy;
2103: if (!viewer) {
2104: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
2105: }
2106: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2107: return(0);
2108: }
2112: /*@C
2113: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2114: modified the PETSc options database.
2115:
2116: Not collective
2118: Input Parameters:
2119: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
2120: . mctx - [optional] context for private data for the
2121: monitor routine (use PETSC_NULL if no context is desired)
2122: - monitordestroy - [optional] routine that frees monitor context
2123: (may be PETSC_NULL)
2125: Calling Sequence of monitor:
2126: $ monitor (const char name[], const char value[], void *mctx)
2128: + name - option name string
2129: . value - option value string
2130: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2132: Options Database Keys:
2133: + -options_monitor - sets PetscOptionsMonitorDefault()
2134: - -options_monitor_cancel - cancels all monitors that have
2135: been hardwired into a code by
2136: calls to PetscOptionsMonitorSet(), but
2137: does not cancel those set via
2138: the options database.
2140: Notes:
2141: The default is to do nothing. To print the name and value of options
2142: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2143: with a null monitoring context.
2145: Several different monitoring routines may be set by calling
2146: PetscOptionsMonitorSet() multiple times; all will be called in the
2147: order in which they were set.
2149: Level: beginner
2151: .keywords: PetscOptions, set, monitor
2153: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2154: @*/
2155: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2156: {
2158: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2159: options->monitor[options->numbermonitors] = monitor;
2160: options->monitordestroy[options->numbermonitors] = monitordestroy;
2161: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2162: return(0);
2163: }
2167: /*@
2168: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2170: Not collective
2172: Options Database Key:
2173: . -options_monitor_cancel - Cancels all monitors that have
2174: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2175: but does not cancel those set via the options database.
2177: Level: intermediate
2179: .keywords: PetscOptions, set, monitor
2181: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2182: @*/
2183: PetscErrorCode PetscOptionsMonitorCancel(void)
2184: {
2186: PetscInt i;
2189: for (i=0; i<options->numbermonitors; i++) {
2190: if (options->monitordestroy[i]) {
2191: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2192: }
2193: }
2194: options->numbermonitors = 0;
2195: return(0);
2196: }