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;
57: extern PetscOptionsObjectType PetscOptionsObject;
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___INT64)
111: *a = _atoi64(name);
112: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
113: *a = atoll(name);
114: #else
115: *a = (PetscInt)atoi(name);
116: #endif
117: }
118: return(0);
119: }
123: /*
124: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
125: */
126: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
127: {
129: size_t len;
130: PetscBool decide,tdefault;
133: PetscStrlen(name,&len);
134: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
136: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
137: if (!tdefault) {
138: PetscStrcasecmp(name,"DEFAULT",&tdefault);
139: }
140: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
141: if (!decide) {
142: PetscStrcasecmp(name,"DECIDE",&decide);
143: }
145: if (tdefault) {
146: *a = PETSC_DEFAULT;
147: } else if (decide) {
148: *a = PETSC_DECIDE;
149: } else {
150: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
151: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
152: }
153: *a = atof(name);
154: }
155: return(0);
156: }
160: /*
161: PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
162: */
163: PetscErrorCode PetscOptionsStringToBool(const char value[], PetscBool *a)
164: {
165: PetscBool istrue, isfalse;
166: size_t len;
170: PetscStrlen(value, &len);
171: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
172: PetscStrcasecmp(value,"TRUE",&istrue);
173: if (istrue) {*a = PETSC_TRUE; return(0);}
174: PetscStrcasecmp(value,"YES",&istrue);
175: if (istrue) {*a = PETSC_TRUE; return(0);}
176: PetscStrcasecmp(value,"1",&istrue);
177: if (istrue) {*a = PETSC_TRUE; return(0);}
178: PetscStrcasecmp(value,"on",&istrue);
179: if (istrue) {*a = PETSC_TRUE; return(0);}
180: PetscStrcasecmp(value,"FALSE",&isfalse);
181: if (isfalse) {*a = PETSC_FALSE; return(0);}
182: PetscStrcasecmp(value,"NO",&isfalse);
183: if (isfalse) {*a = PETSC_FALSE; return(0);}
184: PetscStrcasecmp(value,"0",&isfalse);
185: if (isfalse) {*a = PETSC_FALSE; return(0);}
186: PetscStrcasecmp(value,"off",&isfalse);
187: if (isfalse) {*a = PETSC_FALSE; return(0);}
188: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
189: return(0);
190: }
194: /*@C
195: PetscGetProgramName - Gets the name of the running program.
197: Not Collective
199: Input Parameter:
200: . len - length of the string name
202: Output Parameter:
203: . name - the name of the running program
205: Level: advanced
207: Notes:
208: The name of the program is copied into the user-provided character
209: array of length len. On some machines the program name includes
210: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
211: @*/
212: PetscErrorCode PetscGetProgramName(char name[],size_t len)
213: {
217: if (!options) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
218: if (!options->namegiven) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Unable to determine program name");
219: PetscStrncpy(name,options->programname,len);
220: return(0);
221: }
225: PetscErrorCode PetscSetProgramName(const char name[])
226: {
230: options->namegiven = PETSC_TRUE;
231: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
232: return(0);
233: }
237: /*@
238: PetscOptionsValidKey - PETSc Options database keys must begin with a - followed by a letter.
240: Input Parameter:
241: . in_str - string to check if valid
243: Output Parameter:
244: . key - PETSC_TRUE if a valid key
246: Level: intermediate
248: @*/
249: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscBool *key)
250: {
252: *key = PETSC_FALSE;
253: if (!in_str) return(0);
254: if (in_str[0] != '-') return(0);
255: if (!(isalpha(in_str[1]))) return(0);
256: if ((!strncmp(in_str+1,"inf",3) || !strncmp(in_str+1,"INF",3)) && !(in_str[4] == '_' || isalnum(in_str[4]))) return(0);
257: *key = PETSC_TRUE;
258: return(0);
259: }
263: /*@C
264: PetscOptionsInsertString - Inserts options into the database from a string
266: Not collective: but only processes that call this routine will set the options
267: included in the string
269: Input Parameter:
270: . in_str - string that contains options separated by blanks
273: Level: intermediate
275: Contributed by Boyana Norris
277: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
278: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
279: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
280: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
281: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
282: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
284: @*/
285: PetscErrorCode PetscOptionsInsertString(const char in_str[])
286: {
287: char *first,*second;
289: PetscToken token;
290: PetscBool key,ispush,ispop;
293: PetscTokenCreate(in_str,' ',&token);
294: PetscTokenFind(token,&first);
295: while (first) {
296: PetscStrcasecmp(first,"-prefix_push",&ispush);
297: PetscStrcasecmp(first,"-prefix_pop",&ispop);
298: PetscOptionsValidKey(first,&key);
299: if (ispush) {
300: PetscTokenFind(token,&second);
301: PetscOptionsPrefixPush(second);
302: PetscTokenFind(token,&first);
303: } else if (ispop) {
304: PetscOptionsPrefixPop();
305: PetscTokenFind(token,&first);
306: } else if (key) {
307: PetscTokenFind(token,&second);
308: PetscOptionsValidKey(second,&key);
309: if (!key) {
310: PetscOptionsSetValue(first,second);
311: PetscTokenFind(token,&first);
312: } else {
313: PetscOptionsSetValue(first,PETSC_NULL);
314: first = second;
315: }
316: } else {
317: PetscTokenFind(token,&first);
318: }
319: }
320: PetscTokenDestroy(token);
321: return(0);
322: }
324: /*
325: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
326: */
327: static char *Petscgetline(FILE * f)
328: {
329: size_t size = 0;
330: size_t len = 0;
331: size_t last = 0;
332: char * buf = PETSC_NULL;
334: if (feof(f)) return 0;
335: do {
336: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
337: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
338: /* Actually do the read. Note that fgets puts a terminal '\0' on the
339: end of the string, so we make sure we overwrite this */
340: if (!fgets(buf+len,size,f)) buf[len]=0;
341: PetscStrlen(buf,&len);
342: last = len - 1;
343: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
344: if (len) return buf;
345: free(buf);
346: return 0;
347: }
352: /*@C
353: PetscOptionsInsertFile - Inserts options into the database from a file.
355: Collective on MPI_Comm
357: Input Parameter:
358: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
359: . file - name of file
360: - require - if PETSC_TRUE will generate an error if the file does not exist
363: Level: developer
365: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
366: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
367: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
368: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
369: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
370: PetscOptionsList(), PetscOptionsEList()
372: @*/
373: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
374: {
375: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
377: size_t i,len;
378: FILE *fd;
379: PetscToken token;
380: int err;
381: char cmt[3]={'#','!','%'},*cmatch;
382: PetscMPIInt rank,cnt=0,acnt=0;
385: MPI_Comm_rank(comm,&rank);
386: if (!rank) {
387: /* Warning: assume a maximum size for all options in a string */
388: PetscMalloc(128000*sizeof(char),&vstring);
389: vstring[0] = 0;
390: PetscMalloc(64000*sizeof(char),&astring);
391: astring[0] = 0;
392: cnt = 0;
393: acnt = 0;
395: PetscFixFilename(file,fname);
396: fd = fopen(fname,"r");
397: if (fd) {
398: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
399: PetscInfo1(0,"Opened options file %s\n",file);
400: while ((string = Petscgetline(fd))) {
401: /* eliminate comments from each line */
402: for (i=0; i<3; i++){
403: PetscStrchr(string,cmt[i],&cmatch);
404: if (cmatch) *cmatch = 0;
405: }
406: PetscStrlen(string,&len);
407: /* replace tabs, ^M, \n with " " */
408: for (i=0; i<len; i++) {
409: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
410: string[i] = ' ';
411: }
412: }
413: PetscTokenCreate(string,' ',&token);
414: free(string);
415: PetscTokenFind(token,&first);
416: if (!first) {
417: goto destroy;
418: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
419: PetscTokenFind(token,&first);
420: }
421: PetscTokenFind(token,&second);
422: if (!first) {
423: goto destroy;
424: } else if (first[0] == '-') {
425: /* warning: should be making sure we do not overfill vstring */
426: PetscStrcat(vstring,first);
427: PetscStrcat(vstring," ");
428: if (second) {
429: /* protect second with quotes in case it contains strings */
430: PetscStrcat(vstring,"\"");
431: PetscStrcat(vstring,second);
432: PetscStrcat(vstring,"\"");
433: }
434: PetscStrcat(vstring," ");
435: } else {
436: PetscBool match;
438: PetscStrcasecmp(first,"alias",&match);
439: if (match) {
440: PetscTokenFind(token,&third);
441: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
442: PetscStrcat(astring,second);
443: PetscStrcat(astring," ");
444: PetscStrcat(astring,third);
445: PetscStrcat(astring," ");
446: } else {
447: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
448: }
449: }
450: destroy:
451: PetscTokenDestroy(token);
452: }
453: err = fclose(fd);
454: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
455: PetscStrlen(astring,&len);
456: acnt = PetscMPIIntCast(len);
457: PetscStrlen(vstring,&len);
458: cnt = PetscMPIIntCast(len);
459: } else if (require) {
460: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
461: }
462: }
464: MPI_Bcast(&acnt,1,MPI_INT,0,comm);
465: if (acnt) {
466: PetscToken token;
467: char *first,*second;
469: if (rank) {
470: PetscMalloc((acnt+1)*sizeof(char),&astring);
471: }
472: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
473: astring[acnt] = 0;
474: PetscTokenCreate(astring,' ',&token);
475: PetscTokenFind(token,&first);
476: while (first) {
477: PetscTokenFind(token,&second);
478: PetscOptionsSetAlias(first,second);
479: PetscTokenFind(token,&first);
480: }
481: PetscTokenDestroy(token);
482: }
484: MPI_Bcast(&cnt,1,MPI_INT,0,comm);
485: if (cnt) {
486: if (rank) {
487: PetscMalloc((cnt+1)*sizeof(char),&vstring);
488: }
489: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
490: vstring[cnt] = 0;
491: PetscOptionsInsertString(vstring);
492: }
493: PetscFree(astring);
494: PetscFree(vstring);
495: return(0);
496: }
500: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
501: {
503: int left = argc - 1;
504: char **eargs = args + 1;
507: while (left) {
508: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank;
509: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
510: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
511: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
512: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
513: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
514: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
515: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
516: isp4 = (PetscBool) (isp4 || tisp4);
517: PetscStrcasecmp(eargs[0],"-np",&tisp4);
518: isp4 = (PetscBool) (isp4 || tisp4);
519: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
521: if (eargs[0][0] != '-') {
522: eargs++; left--;
523: } else if (isoptions_file) {
524: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
525: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
526: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
527: eargs += 2; left -= 2;
528: } else if (isprefixpush) {
529: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
530: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
531: PetscOptionsPrefixPush(eargs[1]);
532: eargs += 2; left -= 2;
533: } else if (isprefixpop) {
534: PetscOptionsPrefixPop();
535: eargs++; left--;
537: /*
538: These are "bad" options that MPICH, etc put on the command line
539: we strip them out here.
540: */
541: } else if (tisp4 || isp4rmrank) {
542: eargs += 1; left -= 1;
543: } else if (isp4 || isp4yourname) {
544: eargs += 2; left -= 2;
545: } else {
546: PetscBool nextiskey = PETSC_FALSE;
547: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
548: if (left < 2 || nextiskey) {
549: PetscOptionsSetValue(eargs[0],PETSC_NULL);
550: eargs++; left--;
551: } else {
552: PetscOptionsSetValue(eargs[0],eargs[1]);
553: eargs += 2; left -= 2;
554: }
555: }
556: }
557: return(0);
558: }
563: /*@C
564: PetscOptionsInsert - Inserts into the options database from the command line,
565: the environmental variable and a file.
567: Input Parameters:
568: + argc - count of number of command line arguments
569: . args - the command line arguments
570: - file - optional filename, defaults to ~username/.petscrc
572: Note:
573: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
574: the user does not typically need to call this routine. PetscOptionsInsert()
575: can be called several times, adding additional entries into the database.
577: Options Database Keys:
578: + -options_monitor <optional filename> - print options names and values as they are set
579: . -options_file <filename> - read options from a file
581: Level: advanced
583: Concepts: options database^adding
585: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
586: PetscInitialize()
587: @*/
588: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
589: {
591: PetscMPIInt rank;
592: char pfile[PETSC_MAX_PATH_LEN];
593: PetscBool flag = PETSC_FALSE;
596: if (!options) {
597: fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
598: MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
599: }
600: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
602: options->argc = (argc) ? *argc : 0;
603: options->args = (args) ? *args : PETSC_NULL;
605: if (file && file[0]) {
606: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
607: }
608: /*
609: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
610: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
611: */
612: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
613: PetscOptionsGetBool(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
614: if (!flag) {
615: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
616: /* warning: assumes all processes have a home directory or none, but nothing in between */
617: if (pfile[0]) {
618: PetscStrcat(pfile,"/.petscrc");
619: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
620: }
621: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
622: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
623: }
625: /* insert environmental options */
626: {
627: char *eoptions = 0;
628: size_t len = 0;
629: if (!rank) {
630: eoptions = (char*)getenv("PETSC_OPTIONS");
631: PetscStrlen(eoptions,&len);
632: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
633: } else {
634: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
635: if (len) {
636: PetscMalloc((len+1)*sizeof(char*),&eoptions);
637: }
638: }
639: if (len) {
640: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
641: if (rank) eoptions[len] = 0;
642: PetscOptionsInsertString(eoptions);
643: if (rank) {PetscFree(eoptions);}
644: }
645: }
647: #if defined(PETSC_HAVE_YAML)
648: char yaml_file[PETSC_MAX_PATH_LEN];
649: PetscBool yaml_flg = PETSC_FALSE;
650: PetscOptionsGetString(PETSC_NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
651: if (yaml_flg) PetscOptionsInsertFile_YAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
652: #endif
654: /* insert command line options again because they take precedence over arguments in petscrc/environment */
655: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
657: return(0);
658: }
662: /*@C
663: PetscOptionsView - Prints the options that have been loaded. This is
664: useful for debugging purposes.
666: Logically Collective on PetscViewer
668: Input Parameter:
669: . viewer - must be an PETSCVIEWERASCII viewer
671: Options Database Key:
672: . -optionstable - Activates PetscOptionsView() within PetscFinalize()
674: Level: advanced
676: Concepts: options database^printing
678: .seealso: PetscOptionsAllUsed()
679: @*/
680: PetscErrorCode PetscOptionsView(PetscViewer viewer)
681: {
683: PetscInt i;
684: PetscBool isascii;
687: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
688: PetscTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
689: if (!isascii) SETERRQ(((PetscObject)viewer)->comm,PETSC_ERR_SUP,"Only supports ASCII viewer");
691: if (!options) {PetscOptionsInsert(0,0,0);}
692: if (options->N) {
693: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
694: } else {
695: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
696: }
697: for (i=0; i<options->N; i++) {
698: if (options->values[i]) {
699: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
700: } else {
701: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
702: }
703: }
704: if (options->N) {
705: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
706: }
707: return(0);
708: }
712: /*@C
713: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
715: Not Collective
717: Output Parameter:
718: . copts - pointer where string pointer is stored
720: Notes: the array and each entry in the array should be freed with PetscFree()
722: Level: advanced
724: Concepts: options database^listing
726: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
727: @*/
728: PetscErrorCode PetscOptionsGetAll(char *copts[])
729: {
731: PetscInt i;
732: size_t len = 1,lent;
733: char *coptions;
736: if (!options) {PetscOptionsInsert(0,0,0);}
738: /* count the length of the required string */
739: for (i=0; i<options->N; i++) {
740: PetscStrlen(options->names[i],&lent);
741: len += 2 + lent;
742: if (options->values[i]) {
743: PetscStrlen(options->values[i],&lent);
744: len += 1 + lent;
745: }
746: }
747: PetscMalloc(len*sizeof(char),&coptions);
748: coptions[0] = 0;
749: for (i=0; i<options->N; i++) {
750: PetscStrcat(coptions,"-");
751: PetscStrcat(coptions,options->names[i]);
752: PetscStrcat(coptions," ");
753: if (options->values[i]) {
754: PetscStrcat(coptions,options->values[i]);
755: PetscStrcat(coptions," ");
756: }
757: }
758: *copts = coptions;
759: return(0);
760: }
764: /*@
765: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
767: Not Collective, but prefix will only be applied on calling ranks
769: Input Parameter:
770: . prefix - The string to append to the existing prefix
772: Options Database Keys:
773: + -prefix_push <some_prefix_> - push the given prefix
774: - -prefix_pop - pop the last prefix
776: Notes:
777: It is common to use this in conjunction with -options_file as in
779: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
781: where the files no longer require all options to be prefixed with -system2_.
783: Level: advanced
785: .seealso: PetscOptionsPrefixPop()
786: @*/
787: PetscErrorCode PetscOptionsPrefixPush(const char prefix[])
788: {
790: size_t n;
791: PetscInt start;
792: char buf[2048];
793: PetscBool key;
797: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
798: buf[0] = '-';
799: PetscStrncpy(buf+1,prefix,sizeof buf - 1);
800: buf[sizeof buf - 1] = 0;
801: PetscOptionsValidKey(buf,&key);
802: 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);
804: if (!options) {PetscOptionsInsert(0,0,0);}
805: 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);
806: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
807: PetscStrlen(prefix,&n);
808: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
809: PetscMemcpy(options->prefix+start,prefix,n+1);
810: options->prefixstack[options->prefixind++] = start+n;
811: return(0);
812: }
816: /*@
817: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
819: Not Collective, but prefix will only be popped on calling ranks
821: Level: advanced
823: .seealso: PetscOptionsPrefixPush()
824: @*/
825: PetscErrorCode PetscOptionsPrefixPop(void)
826: {
827: PetscInt offset;
830: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
831: options->prefixind--;
832: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
833: options->prefix[offset] = 0;
834: return(0);
835: }
839: /*@C
840: PetscOptionsClear - Removes all options form the database leaving it empty.
842: Level: developer
844: .seealso: PetscOptionsInsert()
845: @*/
846: PetscErrorCode PetscOptionsClear(void)
847: {
848: PetscInt i;
851: if (!options) return(0);
852: for (i=0; i<options->N; i++) {
853: if (options->names[i]) free(options->names[i]);
854: if (options->values[i]) free(options->values[i]);
855: }
856: for (i=0; i<options->Naliases; i++) {
857: free(options->aliases1[i]);
858: free(options->aliases2[i]);
859: }
860: options->prefix[0] = 0;
861: options->prefixind = 0;
862: options->N = 0;
863: options->Naliases = 0;
864: return(0);
865: }
869: /*@C
870: PetscOptionsDestroy - Destroys the option database.
872: Note:
873: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
874: typically does not need to call this routine.
876: Level: developer
878: .seealso: PetscOptionsInsert()
879: @*/
880: PetscErrorCode PetscOptionsDestroy(void)
881: {
885: if (!options) return(0);
886: PetscOptionsClear();
887: free(options);
888: options = 0;
889: return(0);
890: }
894: /*@C
895: PetscOptionsSetValue - Sets an option name-value pair in the options
896: database, overriding whatever is already present.
898: Not collective, but setting values on certain processors could cause problems
899: for parallel objects looking for options.
901: Input Parameters:
902: + name - name of option, this SHOULD have the - prepended
903: - value - the option value (not used for all options)
905: Level: intermediate
907: Note:
908: Only some options have values associated with them, such as
909: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
911: Concepts: options database^adding option
913: .seealso: PetscOptionsInsert()
914: @*/
915: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
916: {
917: size_t len;
919: PetscInt N,n,i;
920: char **names;
921: char fullname[2048];
922: const char *name = iname;
923: PetscBool gt,match;
926: if (!options) {PetscOptionsInsert(0,0,0);}
928: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
929: PetscStrcasecmp(name,"-h",&match);
930: if (match) name = "-help";
932: name++; /* skip starting hyphen */
933: if (options->prefixind > 0) {
934: PetscStrncpy(fullname,options->prefix,sizeof fullname);
935: PetscStrncat(fullname,name,sizeof fullname);
936: name = fullname;
937: }
939: /* check against aliases */
940: N = options->Naliases;
941: for (i=0; i<N; i++) {
942: PetscStrcasecmp(options->aliases1[i],name,&match);
943: if (match) {
944: name = options->aliases2[i];
945: break;
946: }
947: }
949: N = options->N;
950: n = N;
951: names = options->names;
952:
953: for (i=0; i<N; i++) {
954: PetscStrcasecmp(names[i],name,&match);
955: PetscStrgrt(names[i],name,>);
956: if (match) {
957: if (options->values[i]) free(options->values[i]);
958: PetscStrlen(value,&len);
959: if (len) {
960: options->values[i] = (char*)malloc((len+1)*sizeof(char));
961: PetscStrcpy(options->values[i],value);
962: } else { options->values[i] = 0;}
963: PetscOptionsMonitor(name,value);
964: return(0);
965: } else if (gt) {
966: n = i;
967: break;
968: }
969: }
970: if (N >= MAXOPTIONS) {
971: 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);
972: }
973: /* shift remaining values down 1 */
974: for (i=N; i>n; i--) {
975: options->names[i] = options->names[i-1];
976: options->values[i] = options->values[i-1];
977: options->used[i] = options->used[i-1];
978: }
979: /* insert new name and value */
980: PetscStrlen(name,&len);
981: options->names[n] = (char*)malloc((len+1)*sizeof(char));
982: PetscStrcpy(options->names[n],name);
983: PetscStrlen(value,&len);
984: if (len) {
985: options->values[n] = (char*)malloc((len+1)*sizeof(char));
986: PetscStrcpy(options->values[n],value);
987: } else {options->values[n] = 0;}
988: options->used[n] = PETSC_FALSE;
989: options->N++;
990: PetscOptionsMonitor(name,value);
991: return(0);
992: }
996: /*@C
997: PetscOptionsClearValue - Clears an option name-value pair in the options
998: database, overriding whatever is already present.
1000: Not Collective, but setting values on certain processors could cause problems
1001: for parallel objects looking for options.
1003: Input Parameter:
1004: . name - name of option, this SHOULD have the - prepended
1006: Level: intermediate
1008: Concepts: options database^removing option
1009: .seealso: PetscOptionsInsert()
1010: @*/
1011: PetscErrorCode PetscOptionsClearValue(const char iname[])
1012: {
1014: PetscInt N,n,i;
1015: char **names,*name=(char*)iname;
1016: PetscBool gt,match;
1019: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1020: if (!options) {PetscOptionsInsert(0,0,0);}
1022: name++;
1024: N = options->N; n = 0;
1025: names = options->names;
1026:
1027: for (i=0; i<N; i++) {
1028: PetscStrcasecmp(names[i],name,&match);
1029: PetscStrgrt(names[i],name,>);
1030: if (match) {
1031: if (options->names[i]) free(options->names[i]);
1032: if (options->values[i]) free(options->values[i]);
1033: PetscOptionsMonitor(name,"");
1034: break;
1035: } else if (gt) {
1036: return(0); /* it was not listed */
1037: }
1038: n++;
1039: }
1040: if (n == N) return(0); /* it was not listed */
1042: /* shift remaining values down 1 */
1043: for (i=n; i<N-1; i++) {
1044: options->names[i] = options->names[i+1];
1045: options->values[i] = options->values[i+1];
1046: options->used[i] = options->used[i+1];
1047: }
1048: options->N--;
1049: return(0);
1050: }
1054: /*@C
1055: PetscOptionsSetAlias - Makes a key and alias for another key
1057: Not Collective, but setting values on certain processors could cause problems
1058: for parallel objects looking for options.
1060: Input Parameters:
1061: + inewname - the alias
1062: - ioldname - the name that alias will refer to
1064: Level: advanced
1066: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1067: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1068: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1069: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1070: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1071: PetscOptionsList(), PetscOptionsEList()
1072: @*/
1073: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
1074: {
1076: PetscInt n = options->Naliases;
1077: size_t len;
1078: char *newname = (char *)inewname,*oldname = (char*)ioldname;
1081: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1082: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1083: if (n >= MAXALIASES) {
1084: 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);
1085: }
1087: newname++; oldname++;
1088: PetscStrlen(newname,&len);
1089: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1090: PetscStrcpy(options->aliases1[n],newname);
1091: PetscStrlen(oldname,&len);
1092: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1093: PetscStrcpy(options->aliases2[n],oldname);
1094: options->Naliases++;
1095: return(0);
1096: }
1100: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool *flg)
1101: {
1103: PetscInt i,N;
1104: size_t len;
1105: char **names,tmp[256];
1106: PetscBool match;
1109: if (!options) {PetscOptionsInsert(0,0,0);}
1110: N = options->N;
1111: names = options->names;
1113: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1115: /* append prefix to name */
1116: if (pre) {
1117: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1118: PetscStrncpy(tmp,pre,256);
1119: PetscStrlen(tmp,&len);
1120: PetscStrncat(tmp,name+1,256-len-1);
1121: } else {
1122: PetscStrncpy(tmp,name+1,256);
1123: }
1125: /* slow search */
1126: *flg = PETSC_FALSE;
1127: for (i=0; i<N; i++) {
1128: PetscStrcasecmp(names[i],tmp,&match);
1129: if (match) {
1130: *value = options->values[i];
1131: options->used[i] = PETSC_TRUE;
1132: *flg = PETSC_TRUE;
1133: break;
1134: }
1135: }
1136: if (!*flg) {
1137: PetscInt j,cnt = 0,locs[16],loce[16];
1138: size_t n;
1139: PetscStrlen(tmp,&n);
1140: /* determine the location and number of all _%d_ in the key */
1141: for (i=0; i< (PetscInt)n; i++) {
1142: if (tmp[i] == '_') {
1143: for (j=i+1; j< (PetscInt)n; j++) {
1144: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1145: if (tmp[j] == '_' && j > i+1) { /* found a number */
1146: locs[cnt] = i+1;
1147: loce[cnt++] = j+1;
1148: }
1149: break;
1150: }
1151: }
1152: }
1153: if (cnt) {
1154: char tmp2[256];
1155: for (i=0; i<cnt; i++) {
1156: PetscStrcpy(tmp2,"-");
1157: PetscStrncat(tmp2,tmp,locs[i]);
1158: PetscStrcat(tmp2,tmp+loce[i]);
1159: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1160: if (*flg) break;
1161: }
1162: }
1163: }
1164: return(0);
1165: }
1169: /*@C
1170: PetscOptionsReject - Generates an error if a certain option is given.
1172: Not Collective, but setting values on certain processors could cause problems
1173: for parallel objects looking for options.
1175: Input Parameters:
1176: + name - the option one is seeking
1177: - mess - error message (may be PETSC_NULL)
1179: Level: advanced
1181: Concepts: options database^rejecting option
1183: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1184: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1185: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1186: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1187: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1188: PetscOptionsList(), PetscOptionsEList()
1189: @*/
1190: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1191: {
1193: PetscBool flag = PETSC_FALSE;
1196: PetscOptionsHasName(PETSC_NULL,name,&flag);
1197: if (flag) {
1198: if (mess) {
1199: SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1200: } else {
1201: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1202: }
1203: }
1204: return(0);
1205: }
1209: /*@C
1210: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1211: its value is set to false.
1213: Not Collective
1215: Input Parameters:
1216: + name - the option one is seeking
1217: - pre - string to prepend to the name or PETSC_NULL
1219: Output Parameters:
1220: . set - PETSC_TRUE if found else PETSC_FALSE.
1222: Level: beginner
1224: Concepts: options database^has option name
1226: Notes: Name cannot be simply -h
1228: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1230: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1231: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1232: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1233: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1234: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1235: PetscOptionsList(), PetscOptionsEList()
1236: @*/
1237: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscBool *set)
1238: {
1239: char *value;
1241: PetscBool flag;
1244: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1245: if (set) *set = flag;
1246: return(0);
1247: }
1251: /*@C
1252: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1254: Not Collective
1256: Input Parameters:
1257: + pre - the string to prepend to the name or PETSC_NULL
1258: - name - the option one is seeking
1260: Output Parameter:
1261: + ivalue - the integer value to return
1262: - set - PETSC_TRUE if found, else PETSC_FALSE
1264: Level: beginner
1266: Concepts: options database^has int
1268: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1269: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1270: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1271: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1272: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1273: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1274: PetscOptionsList(), PetscOptionsEList()
1275: @*/
1276: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1277: {
1278: char *value;
1280: PetscBool flag;
1285: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1286: if (flag) {
1287: if (!value) {if (set) *set = PETSC_FALSE;}
1288: else {
1289: if (set) *set = PETSC_TRUE;
1290: PetscOptionsStringToInt(value,ivalue);
1291: }
1292: } else {
1293: if (set) *set = PETSC_FALSE;
1294: }
1295: return(0);
1296: }
1300: /*@C
1301: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1303: Not Collective
1305: Input Parameters:
1306: + pre - the string to prepend to the name or PETSC_NULL
1307: . opt - option name
1308: . list - the possible choices
1309: . ntext - number of choices
1311: Output Parameter:
1312: + value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1313: - set - PETSC_TRUE if found, else PETSC_FALSE
1314:
1315: Level: intermediate
1317: See PetscOptionsList() for when the choices are given in a PetscFList()
1319: Concepts: options database^list
1321: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1322: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1323: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1324: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1325: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1326: PetscOptionsList(), PetscOptionsEList()
1327: @*/
1328: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscBool *set)
1329: {
1331: size_t alen,len = 0;
1332: char *svalue;
1333: PetscBool aset,flg = PETSC_FALSE;
1334: PetscInt i;
1337: for ( i=0; i<ntext; i++) {
1338: PetscStrlen(list[i],&alen);
1339: if (alen > len) len = alen;
1340: }
1341: len += 5; /* a little extra space for user mistypes */
1342: PetscMalloc(len*sizeof(char),&svalue);
1343: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1344: if (aset) {
1345: if (set) *set = PETSC_TRUE;
1346: for (i=0; i<ntext; i++) {
1347: PetscStrcasecmp(svalue,list[i],&flg);
1348: if (flg || !svalue[0]) {
1349: flg = PETSC_TRUE;
1350: *value = i;
1351: break;
1352: }
1353: }
1354: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1355: } else if (set) {
1356: *set = PETSC_FALSE;
1357: }
1358: PetscFree(svalue);
1359: return(0);
1360: }
1364: /*@C
1365: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1367: Not Collective
1369: Input Parameters:
1370: + pre - option prefix or PETSC_NULL
1371: . opt - option name
1372: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1373: - defaultv - the default (current) value
1375: Output Parameter:
1376: + value - the value to return
1377: - set - PETSC_TRUE if found, else PETSC_FALSE
1379: Level: beginner
1381: Concepts: options database
1383: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1385: list is usually something like PCASMTypes or some other predefined list of enum names
1387: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1388: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1389: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1390: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1391: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1392: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1393: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1394: @*/
1395: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscBool *set)
1396: {
1398: PetscInt ntext = 0,tval;
1399: PetscBool fset;
1402: while (list[ntext++]) {
1403: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1404: }
1405: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1406: ntext -= 3;
1407: PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1408: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1409: if (fset) *value = (PetscEnum)tval;
1410: if (set) *set = fset;
1411: return(0);
1412: }
1416: /*@C
1417: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1418: option in the database.
1420: Not Collective
1422: Input Parameters:
1423: + pre - the string to prepend to the name or PETSC_NULL
1424: - name - the option one is seeking
1426: Output Parameter:
1427: + ivalue - the logical value to return
1428: - set - PETSC_TRUE if found, else PETSC_FALSE
1430: Level: beginner
1432: Notes:
1433: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1434: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1436: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1437: you NEED TO ALWAYS initialize the ivalue.
1439: Concepts: options database^has logical
1441: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1442: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1443: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1444: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1445: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1446: PetscOptionsList(), PetscOptionsEList()
1447: @*/
1448: PetscErrorCode PetscOptionsGetBool(const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1449: {
1450: char *value;
1451: PetscBool flag;
1457: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1458: if (flag) {
1459: if (set) *set = PETSC_TRUE;
1460: if (!value) {
1461: *ivalue = PETSC_TRUE;
1462: } else {
1463: PetscOptionsStringToBool(value, ivalue);
1464: }
1465: } else {
1466: if (set) *set = PETSC_FALSE;
1467: }
1468: return(0);
1469: }
1473: /*@C
1474: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1475: option in the database. The values must be separated with commas with
1476: no intervening spaces.
1478: Not Collective
1480: Input Parameters:
1481: + pre - string to prepend to each name or PETSC_NULL
1482: . name - the option one is seeking
1483: - nmax - maximum number of values to retrieve
1485: Output Parameter:
1486: + dvalue - the integer values to return
1487: . nmax - actual number of values retreived
1488: - set - PETSC_TRUE if found, else PETSC_FALSE
1490: Level: beginner
1492: Concepts: options database^array of ints
1494: Notes:
1495: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1496: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1498: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1499: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1500: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1501: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1502: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1503: PetscOptionsList(), PetscOptionsEList()
1504: @*/
1505: PetscErrorCode PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1506: {
1507: char *value;
1509: PetscInt n = 0;
1510: PetscBool flag;
1511: PetscToken token;
1516: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1517: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1518: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1520: if (set) *set = PETSC_TRUE;
1522: PetscTokenCreate(value,',',&token);
1523: PetscTokenFind(token,&value);
1524: while (n < *nmax) {
1525: if (!value) break;
1526: PetscOptionsStringToBool(value,dvalue);
1527: PetscTokenFind(token,&value);
1528: dvalue++;
1529: n++;
1530: }
1531: PetscTokenDestroy(token);
1532: *nmax = n;
1533: return(0);
1534: }
1538: /*@C
1539: PetscOptionsGetReal - Gets the double precision value for a particular
1540: option in the database.
1542: Not Collective
1544: Input Parameters:
1545: + pre - string to prepend to each name or PETSC_NULL
1546: - name - the option one is seeking
1548: Output Parameter:
1549: + dvalue - the double value to return
1550: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1552: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1554: Level: beginner
1556: Concepts: options database^has double
1558: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1559: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1560: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1561: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1562: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1563: PetscOptionsList(), PetscOptionsEList()
1564: @*/
1565: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1566: {
1567: char *value;
1569: PetscBool flag;
1574: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1575: if (flag) {
1576: if (!value) {if (set) *set = PETSC_FALSE;}
1577: else {if (set) *set = PETSC_TRUE; PetscOptionsStringToReal(value,dvalue);}
1578: } else {
1579: if (set) *set = PETSC_FALSE;
1580: }
1581: return(0);
1582: }
1586: /*@C
1587: PetscOptionsGetScalar - Gets the scalar value for a particular
1588: option in the database.
1590: Not Collective
1592: Input Parameters:
1593: + pre - string to prepend to each name or PETSC_NULL
1594: - name - the option one is seeking
1596: Output Parameter:
1597: + dvalue - the double value to return
1598: - set - PETSC_TRUE if found, else PETSC_FALSE
1600: Level: beginner
1602: Usage:
1603: A complex number 2+3i can be specified as 2,3 at the command line.
1604: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1606: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1608: Concepts: options database^has scalar
1610: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1611: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1612: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1613: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1614: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1615: PetscOptionsList(), PetscOptionsEList()
1616: @*/
1617: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1618: {
1619: char *value;
1620: PetscBool flag;
1626: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1627: if (flag) {
1628: if (!value) {
1629: if (set) *set = PETSC_FALSE;
1630: } else {
1631: #if !defined(PETSC_USE_COMPLEX)
1632: PetscOptionsStringToReal(value,dvalue);
1633: #else
1634: PetscReal re=0.0,im=0.0;
1635: PetscToken token;
1636: char *tvalue = 0;
1638: PetscTokenCreate(value,',',&token);
1639: PetscTokenFind(token,&tvalue);
1640: if (!tvalue) { SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1641: PetscOptionsStringToReal(tvalue,&re);
1642: PetscTokenFind(token,&tvalue);
1643: if (!tvalue) { /* Unknown separator used. using only real value */
1644: *dvalue = re;
1645: } else {
1646: PetscOptionsStringToReal(tvalue,&im);
1647: *dvalue = re + PETSC_i*im;
1648: }
1649: PetscTokenDestroy(token);
1650: #endif
1651: if (set) *set = PETSC_TRUE;
1652: }
1653: } else { /* flag */
1654: if (set) *set = PETSC_FALSE;
1655: }
1656: return(0);
1657: }
1661: /*@C
1662: PetscOptionsGetRealArray - Gets an array of double precision values for a
1663: particular option in the database. The values must be separated with
1664: commas with no intervening spaces.
1666: Not Collective
1668: Input Parameters:
1669: + pre - string to prepend to each name or PETSC_NULL
1670: . name - the option one is seeking
1671: - nmax - maximum number of values to retrieve
1673: Output Parameters:
1674: + dvalue - the double value to return
1675: . nmax - actual number of values retreived
1676: - set - PETSC_TRUE if found, else PETSC_FALSE
1678: Level: beginner
1680: Concepts: options database^array of doubles
1682: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1683: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1684: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1685: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1686: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1687: PetscOptionsList(), PetscOptionsEList()
1688: @*/
1689: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal 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: PetscOptionsStringToReal(value,dvalue++);
1711: PetscTokenFind(token,&value);
1712: n++;
1713: }
1714: PetscTokenDestroy(token);
1715: *nmax = n;
1716: return(0);
1717: }
1721: /*@C
1722: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1723: option in the database. The values must be separated with commas with
1724: no intervening spaces.
1726: Not Collective
1728: Input Parameters:
1729: + pre - string to prepend to each name or PETSC_NULL
1730: . name - the option one is seeking
1731: - nmax - maximum number of values to retrieve, can include d-D to indicate d,d+1,..,D-1
1733: Output Parameter:
1734: + dvalue - the integer values to return
1735: . nmax - actual number of values retreived
1736: - set - PETSC_TRUE if found, else PETSC_FALSE
1738: Level: beginner
1740: Concepts: options database^array of ints
1742: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1743: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1744: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1745: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1746: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1747: PetscOptionsList(), PetscOptionsEList()
1748: @*/
1749: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
1750: {
1751: char *value;
1753: PetscInt n = 0,i,start,end;
1754: size_t len;
1755: PetscBool flag,foundrange;
1756: PetscToken token;
1761: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1762: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1763: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1765: if (set) *set = PETSC_TRUE;
1767: PetscTokenCreate(value,',',&token);
1768: PetscTokenFind(token,&value);
1769: while (n < *nmax) {
1770: if (!value) break;
1771:
1772: /* look for form d-D where d and D are integers */
1773: foundrange = PETSC_FALSE;
1774: PetscStrlen(value,&len);
1775: if (value[0] == '-') i=2;
1776: else i=1;
1777: for (;i<(int)len; i++) {
1778: if (value[i] == '-') {
1779: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1780: value[i] = 0;
1781: PetscOptionsStringToInt(value,&start);
1782: PetscOptionsStringToInt(value+i+1,&end);
1783: 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);
1784: 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);
1785: for (;start<end; start++) {
1786: *dvalue = start; dvalue++;n++;
1787: }
1788: foundrange = PETSC_TRUE;
1789: break;
1790: }
1791: }
1792: if (!foundrange) {
1793: PetscOptionsStringToInt(value,dvalue);
1794: dvalue++;
1795: n++;
1796: }
1797: PetscTokenFind(token,&value);
1798: }
1799: PetscTokenDestroy(token);
1800: *nmax = n;
1801: return(0);
1802: }
1806: /*@C
1807: PetscOptionsGetString - Gets the string value for a particular option in
1808: the database.
1810: Not Collective
1812: Input Parameters:
1813: + pre - string to prepend to name or PETSC_NULL
1814: . name - the option one is seeking
1815: - len - maximum length of the string including null termination
1817: Output Parameters:
1818: + string - location to copy string
1819: - set - PETSC_TRUE if found, else PETSC_FALSE
1821: Level: beginner
1823: Fortran Note:
1824: The Fortran interface is slightly different from the C/C++
1825: interface (len is not used). Sample usage in Fortran follows
1826: .vb
1827: character *20 string
1828: integer flg, ierr
1829: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1830: .ve
1832: 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
1834: Concepts: options database^string
1836: Note:
1837: 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).
1839: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1840: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1841: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1842: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1843: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1844: PetscOptionsList(), PetscOptionsEList()
1845: @*/
1846: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool *set)
1847: {
1848: char *value;
1850: PetscBool flag;
1855: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1856: if (!flag) {
1857: if (set) *set = PETSC_FALSE;
1858: } else {
1859: if (set) *set = PETSC_TRUE;
1860: if (value) {
1861: PetscStrncpy(string,value,len);
1862: string[len-1] = 0; /* Ensure that the string is NULL terminated */
1863: } else {
1864: PetscMemzero(string,len);
1865: }
1866: }
1867: return(0);
1868: }
1872: char* PetscOptionsGetStringMatlab(const char pre[],const char name[])
1873: {
1874: char *value;
1876: PetscBool flag;
1879: PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
1880: if (flag) PetscFunctionReturn(value);
1881: else return(0);
1882: }
1887: /*@C
1888: PetscOptionsGetStringArray - Gets an array of string values for a particular
1889: option in the database. The values must be separated with commas with
1890: no intervening spaces.
1892: Not Collective
1894: Input Parameters:
1895: + pre - string to prepend to name or PETSC_NULL
1896: . name - the option one is seeking
1897: - nmax - maximum number of strings
1899: Output Parameter:
1900: + strings - location to copy strings
1901: - set - PETSC_TRUE if found, else PETSC_FALSE
1903: Level: beginner
1905: Notes:
1906: The user should pass in an array of pointers to char, to hold all the
1907: strings returned by this function.
1909: The user is responsible for deallocating the strings that are
1910: returned. The Fortran interface for this routine is not supported.
1912: Contributed by Matthew Knepley.
1914: Concepts: options database^array of strings
1916: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1917: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1918: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1919: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1920: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1921: PetscOptionsList(), PetscOptionsEList()
1922: @*/
1923: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
1924: {
1925: char *value;
1927: PetscInt n;
1928: PetscBool flag;
1929: PetscToken token;
1930:
1934: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1935: if (!flag) {*nmax = 0; if (set) *set = PETSC_FALSE; return(0);}
1936: if (!value) {*nmax = 0; if (set) *set = PETSC_FALSE;return(0);}
1937: if (!*nmax) {if (set) *set = PETSC_FALSE;return(0);}
1938: if (set) *set = PETSC_TRUE;
1940: PetscTokenCreate(value,',',&token);
1941: PetscTokenFind(token,&value);
1942: n = 0;
1943: while (n < *nmax) {
1944: if (!value) break;
1945: PetscStrallocpy(value,&strings[n]);
1946: PetscTokenFind(token,&value);
1947: n++;
1948: }
1949: PetscTokenDestroy(token);
1950: *nmax = n;
1951: return(0);
1952: }
1956: /*@C
1957: PetscOptionsAllUsed - Returns a count of the number of options in the
1958: database that have never been selected.
1960: Not Collective
1962: Output Parameter:
1963: . N - count of options not used
1965: Level: advanced
1967: .seealso: PetscOptionsView()
1968: @*/
1969: PetscErrorCode PetscOptionsAllUsed(PetscInt *N)
1970: {
1971: PetscInt i,n = 0;
1974: for (i=0; i<options->N; i++) {
1975: if (!options->used[i]) { n++; }
1976: }
1977: *N = n;
1978: return(0);
1979: }
1983: /*@
1984: PetscOptionsLeft - Prints to screen any options that were set and never used.
1986: Not collective
1988: Options Database Key:
1989: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1991: Level: advanced
1993: .seealso: PetscOptionsAllUsed()
1994: @*/
1995: PetscErrorCode PetscOptionsLeft(void)
1996: {
1998: PetscInt i;
2001: for (i=0; i<options->N; i++) {
2002: if (!options->used[i]) {
2003: if (options->values[i]) {
2004: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2005: } else {
2006: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
2007: }
2008: }
2009: }
2010: return(0);
2011: }
2016: /*
2017: PetscOptionsCreate - Creates the empty options database.
2019: */
2020: PetscErrorCode PetscOptionsCreate(void)
2021: {
2025: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
2026: PetscMemzero(options,sizeof(PetscOptionsTable));
2027: options->namegiven = PETSC_FALSE;
2028: options->N = 0;
2029: options->Naliases = 0;
2030: options->numbermonitors = 0;
2032: PetscOptionsObject.prefix = PETSC_NULL;
2033: PetscOptionsObject.title = PETSC_NULL;
2034:
2035: return(0);
2036: }
2040: /*@
2041: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
2043: Collective on PETSC_COMM_WORLD
2045: Options Database Keys:
2046: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2047: available for options set through a file, environment variable, or on
2048: the command line. Only options set after PetscInitialize completes will
2049: be monitored.
2050: . -options_monitor_cancel - cancel all options database monitors
2052: Notes:
2053: To see all options, run your program with the -help option or consult
2054: the <A href="../../docs/manual.pdf">users manual</A>..
2056: Level: intermediate
2058: .keywords: set, options, database
2059: @*/
2060: PetscErrorCode PetscOptionsSetFromOptions(void)
2061: {
2062: PetscBool flgc,flgm;
2063: PetscErrorCode ierr;
2064: char monfilename[PETSC_MAX_PATH_LEN];
2065: PetscViewer monviewer;
2068: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
2069: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2070: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",PETSC_FALSE,&flgc,PETSC_NULL);
2071: PetscOptionsEnd();
2072: if (flgm) {
2073: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2074: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2075: }
2076: if (flgc) { PetscOptionsMonitorCancel(); }
2077: return(0);
2078: }
2083: /*@C
2084: PetscOptionsMonitorDefault - Print all options set value events.
2086: Logically Collective on PETSC_COMM_WORLD
2088: Input Parameters:
2089: + name - option name string
2090: . value - option value string
2091: - dummy - unused monitor context
2093: Level: intermediate
2095: .keywords: PetscOptions, default, monitor
2097: .seealso: PetscOptionsMonitorSet()
2098: @*/
2099: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2100: {
2102: PetscViewer viewer = (PetscViewer) dummy;
2105: if (!viewer) {
2106: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
2107: }
2108: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2109: return(0);
2110: }
2114: /*@C
2115: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2116: modified the PETSc options database.
2117:
2118: Not collective
2120: Input Parameters:
2121: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
2122: . mctx - [optional] context for private data for the
2123: monitor routine (use PETSC_NULL if no context is desired)
2124: - monitordestroy - [optional] routine that frees monitor context
2125: (may be PETSC_NULL)
2127: Calling Sequence of monitor:
2128: $ monitor (const char name[], const char value[], void *mctx)
2130: + name - option name string
2131: . value - option value string
2132: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2134: Options Database Keys:
2135: + -options_monitor - sets PetscOptionsMonitorDefault()
2136: - -options_monitor_cancel - cancels all monitors that have
2137: been hardwired into a code by
2138: calls to PetscOptionsMonitorSet(), but
2139: does not cancel those set via
2140: the options database.
2142: Notes:
2143: The default is to do nothing. To print the name and value of options
2144: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2145: with a null monitoring context.
2147: Several different monitoring routines may be set by calling
2148: PetscOptionsMonitorSet() multiple times; all will be called in the
2149: order in which they were set.
2151: Level: beginner
2153: .keywords: PetscOptions, set, monitor
2155: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2156: @*/
2157: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2158: {
2160: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2161: options->monitor[options->numbermonitors] = monitor;
2162: options->monitordestroy[options->numbermonitors] = monitordestroy;
2163: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2164: return(0);
2165: }
2169: /*@
2170: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2172: Not collective
2174: Options Database Key:
2175: . -options_monitor_cancel - Cancels all monitors that have
2176: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2177: but does not cancel those set via the options database.
2179: Level: intermediate
2181: .keywords: PetscOptions, set, monitor
2183: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2184: @*/
2185: PetscErrorCode PetscOptionsMonitorCancel(void)
2186: {
2188: PetscInt i;
2191: for (i=0; i<options->numbermonitors; i++) {
2192: if (options->monitordestroy[i]) {
2193: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2194: }
2195: }
2196: options->numbermonitors = 0;
2197: return(0);
2198: }