Actual source code: options.c
petsc-3.3-p7 2013-05-11
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_ATOLL)
111: *a = atoll(name);
112: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
113: *a = _atoi64(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 one or two dashes (-) 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 (in_str[1] == '-') in_str++;
256: if (!isalpha(in_str[1])) return(0);
257: if ((!strncmp(in_str+1,"inf",3) || !strncmp(in_str+1,"INF",3)) && !(in_str[4] == '_' || isalnum(in_str[4]))) return(0);
258: *key = PETSC_TRUE;
259: return(0);
260: }
264: /*@C
265: PetscOptionsInsertString - Inserts options into the database from a string
267: Not collective: but only processes that call this routine will set the options
268: included in the string
270: Input Parameter:
271: . in_str - string that contains options separated by blanks
274: Level: intermediate
276: Contributed by Boyana Norris
278: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
279: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
280: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
281: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
282: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
283: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
285: @*/
286: PetscErrorCode PetscOptionsInsertString(const char in_str[])
287: {
288: char *first,*second;
290: PetscToken token;
291: PetscBool key,ispush,ispop;
294: PetscTokenCreate(in_str,' ',&token);
295: PetscTokenFind(token,&first);
296: while (first) {
297: PetscStrcasecmp(first,"-prefix_push",&ispush);
298: PetscStrcasecmp(first,"-prefix_pop",&ispop);
299: PetscOptionsValidKey(first,&key);
300: if (ispush) {
301: PetscTokenFind(token,&second);
302: PetscOptionsPrefixPush(second);
303: PetscTokenFind(token,&first);
304: } else if (ispop) {
305: PetscOptionsPrefixPop();
306: PetscTokenFind(token,&first);
307: } else if (key) {
308: PetscTokenFind(token,&second);
309: PetscOptionsValidKey(second,&key);
310: if (!key) {
311: PetscOptionsSetValue(first,second);
312: PetscTokenFind(token,&first);
313: } else {
314: PetscOptionsSetValue(first,PETSC_NULL);
315: first = second;
316: }
317: } else {
318: PetscTokenFind(token,&first);
319: }
320: }
321: PetscTokenDestroy(&token);
322: return(0);
323: }
325: /*
326: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
327: */
328: static char *Petscgetline(FILE * f)
329: {
330: size_t size = 0;
331: size_t len = 0;
332: size_t last = 0;
333: char * buf = PETSC_NULL;
335: if (feof(f)) return 0;
336: do {
337: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
338: buf = (char*)realloc((void *)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
339: /* Actually do the read. Note that fgets puts a terminal '\0' on the
340: end of the string, so we make sure we overwrite this */
341: if (!fgets(buf+len,size,f)) buf[len]=0;
342: PetscStrlen(buf,&len);
343: last = len - 1;
344: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
345: if (len) return buf;
346: free(buf);
347: return 0;
348: }
353: /*@C
354: PetscOptionsInsertFile - Inserts options into the database from a file.
356: Collective on MPI_Comm
358: Input Parameter:
359: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
360: . file - name of file
361: - require - if PETSC_TRUE will generate an error if the file does not exist
364: Level: developer
366: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
367: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
368: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
369: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
370: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
371: PetscOptionsList(), PetscOptionsEList()
373: @*/
374: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,const char file[],PetscBool require)
375: {
376: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0;
378: size_t i,len;
379: FILE *fd;
380: PetscToken token;
381: int err;
382: char cmt[3]={'#','!','%'},*cmatch;
383: PetscMPIInt rank,cnt=0,acnt=0;
386: MPI_Comm_rank(comm,&rank);
387: if (!rank) {
388: /* Warning: assume a maximum size for all options in a string */
389: PetscMalloc(128000*sizeof(char),&vstring);
390: vstring[0] = 0;
391: PetscMalloc(64000*sizeof(char),&astring);
392: astring[0] = 0;
393: cnt = 0;
394: acnt = 0;
396: PetscFixFilename(file,fname);
397: fd = fopen(fname,"r");
398: if (fd) {
399: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
400: PetscInfo1(0,"Opened options file %s\n",file);
401: while ((string = Petscgetline(fd))) {
402: /* eliminate comments from each line */
403: for (i=0; i<3; i++){
404: PetscStrchr(string,cmt[i],&cmatch);
405: if (cmatch) *cmatch = 0;
406: }
407: PetscStrlen(string,&len);
408: /* replace tabs, ^M, \n with " " */
409: for (i=0; i<len; i++) {
410: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
411: string[i] = ' ';
412: }
413: }
414: PetscTokenCreate(string,' ',&token);
415: free(string);
416: PetscTokenFind(token,&first);
417: if (!first) {
418: goto destroy;
419: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
420: PetscTokenFind(token,&first);
421: }
422: PetscTokenFind(token,&second);
423: if (!first) {
424: goto destroy;
425: } else if (first[0] == '-') {
426: /* warning: should be making sure we do not overfill vstring */
427: PetscStrcat(vstring,first);
428: PetscStrcat(vstring," ");
429: if (second) {
430: /* protect second with quotes in case it contains strings */
431: PetscStrcat(vstring,"\"");
432: PetscStrcat(vstring,second);
433: PetscStrcat(vstring,"\"");
434: }
435: PetscStrcat(vstring," ");
436: } else {
437: PetscBool match;
439: PetscStrcasecmp(first,"alias",&match);
440: if (match) {
441: PetscTokenFind(token,&third);
442: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
443: PetscStrcat(astring,second);
444: PetscStrcat(astring," ");
445: PetscStrcat(astring,third);
446: PetscStrcat(astring," ");
447: } else {
448: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
449: }
450: }
451: destroy:
452: PetscTokenDestroy(&token);
453: }
454: err = fclose(fd);
455: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
456: PetscStrlen(astring,&len);
457: acnt = PetscMPIIntCast(len);
458: PetscStrlen(vstring,&len);
459: cnt = PetscMPIIntCast(len);
460: } else if (require) {
461: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
462: }
463: }
465: MPI_Bcast(&acnt,1,MPI_INT,0,comm);
466: if (acnt) {
467: PetscToken token;
468: char *first,*second;
470: if (rank) {
471: PetscMalloc((acnt+1)*sizeof(char),&astring);
472: }
473: MPI_Bcast(astring,acnt,MPI_CHAR,0,comm);
474: astring[acnt] = 0;
475: PetscTokenCreate(astring,' ',&token);
476: PetscTokenFind(token,&first);
477: while (first) {
478: PetscTokenFind(token,&second);
479: PetscOptionsSetAlias(first,second);
480: PetscTokenFind(token,&first);
481: }
482: PetscTokenDestroy(&token);
483: }
485: MPI_Bcast(&cnt,1,MPI_INT,0,comm);
486: if (cnt) {
487: if (rank) {
488: PetscMalloc((cnt+1)*sizeof(char),&vstring);
489: }
490: MPI_Bcast(vstring,cnt,MPI_CHAR,0,comm);
491: vstring[cnt] = 0;
492: PetscOptionsInsertString(vstring);
493: }
494: PetscFree(astring);
495: PetscFree(vstring);
496: return(0);
497: }
501: static PetscErrorCode PetscOptionsInsertArgs_Private(int argc,char *args[])
502: {
504: int left = argc - 1;
505: char **eargs = args + 1;
508: while (left) {
509: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
510: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
511: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
512: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
513: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
514: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
515: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
516: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
517: isp4 = (PetscBool) (isp4 || tisp4);
518: PetscStrcasecmp(eargs[0],"-np",&tisp4);
519: isp4 = (PetscBool) (isp4 || tisp4);
520: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
521: PetscOptionsValidKey(eargs[0],&key);
523: if (!key) {
524: eargs++; left--;
525: } else if (isoptions_file) {
526: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
527: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
528: PetscOptionsInsertFile(PETSC_COMM_WORLD,eargs[1],PETSC_TRUE);
529: eargs += 2; left -= 2;
530: } else if (isprefixpush) {
531: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
532: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
533: PetscOptionsPrefixPush(eargs[1]);
534: eargs += 2; left -= 2;
535: } else if (isprefixpop) {
536: PetscOptionsPrefixPop();
537: eargs++; left--;
539: /*
540: These are "bad" options that MPICH, etc put on the command line
541: we strip them out here.
542: */
543: } else if (tisp4 || isp4rmrank) {
544: eargs += 1; left -= 1;
545: } else if (isp4 || isp4yourname) {
546: eargs += 2; left -= 2;
547: } else {
548: PetscBool nextiskey = PETSC_FALSE;
549: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
550: if (left < 2 || nextiskey) {
551: PetscOptionsSetValue(eargs[0],PETSC_NULL);
552: eargs++; left--;
553: } else {
554: PetscOptionsSetValue(eargs[0],eargs[1]);
555: eargs += 2; left -= 2;
556: }
557: }
558: }
559: return(0);
560: }
565: /*@C
566: PetscOptionsInsert - Inserts into the options database from the command line,
567: the environmental variable and a file.
569: Input Parameters:
570: + argc - count of number of command line arguments
571: . args - the command line arguments
572: - file - optional filename, defaults to ~username/.petscrc
574: Note:
575: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
576: the user does not typically need to call this routine. PetscOptionsInsert()
577: can be called several times, adding additional entries into the database.
579: Options Database Keys:
580: + -options_monitor <optional filename> - print options names and values as they are set
581: . -options_file <filename> - read options from a file
583: Level: advanced
585: Concepts: options database^adding
587: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
588: PetscInitialize()
589: @*/
590: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
591: {
593: PetscMPIInt rank;
594: char pfile[PETSC_MAX_PATH_LEN];
595: PetscBool flag = PETSC_FALSE;
598: if (!options) {
599: fprintf(stderr, "Options have not been enabled.\nYou might have forgotten to call PetscInitialize().\n");
600: MPI_Abort(MPI_COMM_WORLD, PETSC_ERR_SUP);
601: }
602: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
604: options->argc = (argc) ? *argc : 0;
605: options->args = (args) ? *args : PETSC_NULL;
607: if (file && file[0]) {
608: PetscOptionsInsertFile(PETSC_COMM_WORLD,file,PETSC_TRUE);
609: }
610: /*
611: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
612: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
613: */
614: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
615: PetscOptionsGetBool(PETSC_NULL,"-skip_petscrc",&flag,PETSC_NULL);
616: if (!flag) {
617: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
618: /* warning: assumes all processes have a home directory or none, but nothing in between */
619: if (pfile[0]) {
620: PetscStrcat(pfile,"/.petscrc");
621: PetscOptionsInsertFile(PETSC_COMM_WORLD,pfile,PETSC_FALSE);
622: }
623: PetscOptionsInsertFile(PETSC_COMM_WORLD,".petscrc",PETSC_FALSE);
624: PetscOptionsInsertFile(PETSC_COMM_WORLD,"petscrc",PETSC_FALSE);
625: }
627: /* insert environmental options */
628: {
629: char *eoptions = 0;
630: size_t len = 0;
631: if (!rank) {
632: eoptions = (char*)getenv("PETSC_OPTIONS");
633: PetscStrlen(eoptions,&len);
634: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
635: } else {
636: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
637: if (len) {
638: PetscMalloc((len+1)*sizeof(char*),&eoptions);
639: }
640: }
641: if (len) {
642: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
643: if (rank) eoptions[len] = 0;
644: PetscOptionsInsertString(eoptions);
645: if (rank) {PetscFree(eoptions);}
646: }
647: }
649: #if defined(PETSC_HAVE_YAML)
650: char yaml_file[PETSC_MAX_PATH_LEN];
651: PetscBool yaml_flg = PETSC_FALSE;
652: PetscOptionsGetString(PETSC_NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
653: if (yaml_flg) PetscOptionsInsertFile_YAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
654: #endif
656: /* insert command line options again because they take precedence over arguments in petscrc/environment */
657: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(*argc,*args);}
659: return(0);
660: }
664: /*@C
665: PetscOptionsView - Prints the options that have been loaded. This is
666: useful for debugging purposes.
668: Logically Collective on PetscViewer
670: Input Parameter:
671: . viewer - must be an PETSCVIEWERASCII viewer
673: Options Database Key:
674: . -options_table - Activates PetscOptionsView() within PetscFinalize()
676: Level: advanced
678: Concepts: options database^printing
680: .seealso: PetscOptionsAllUsed()
681: @*/
682: PetscErrorCode PetscOptionsView(PetscViewer viewer)
683: {
685: PetscInt i;
686: PetscBool isascii;
689: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
690: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
691: if (!isascii) SETERRQ(((PetscObject)viewer)->comm,PETSC_ERR_SUP,"Only supports ASCII viewer");
693: if (!options) {PetscOptionsInsert(0,0,0);}
694: if (options->N) {
695: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
696: } else {
697: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
698: }
699: for (i=0; i<options->N; i++) {
700: if (options->values[i]) {
701: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
702: } else {
703: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
704: }
705: }
706: if (options->N) {
707: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
708: }
709: return(0);
710: }
714: /*@C
715: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
717: Not Collective
719: Output Parameter:
720: . copts - pointer where string pointer is stored
722: Notes: the array and each entry in the array should be freed with PetscFree()
724: Level: advanced
726: Concepts: options database^listing
728: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
729: @*/
730: PetscErrorCode PetscOptionsGetAll(char *copts[])
731: {
733: PetscInt i;
734: size_t len = 1,lent = 0;
735: char *coptions = PETSC_NULL;
738: if (!options) {PetscOptionsInsert(0,0,0);}
740: /* count the length of the required string */
741: for (i=0; i<options->N; i++) {
742: PetscStrlen(options->names[i],&lent);
743: len += 2 + lent;
744: if (options->values[i]) {
745: PetscStrlen(options->values[i],&lent);
746: len += 1 + lent;
747: }
748: }
749: PetscMalloc(len*sizeof(char),&coptions);
750: coptions[0] = 0;
751: for (i=0; i<options->N; i++) {
752: PetscStrcat(coptions,"-");
753: PetscStrcat(coptions,options->names[i]);
754: PetscStrcat(coptions," ");
755: if (options->values[i]) {
756: PetscStrcat(coptions,options->values[i]);
757: PetscStrcat(coptions," ");
758: }
759: }
760: *copts = coptions;
761: return(0);
762: }
766: /*@
767: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
769: Not Collective, but prefix will only be applied on calling ranks
771: Input Parameter:
772: . prefix - The string to append to the existing prefix
774: Options Database Keys:
775: + -prefix_push <some_prefix_> - push the given prefix
776: - -prefix_pop - pop the last prefix
778: Notes:
779: It is common to use this in conjunction with -options_file as in
781: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
783: where the files no longer require all options to be prefixed with -system2_.
785: Level: advanced
787: .seealso: PetscOptionsPrefixPop()
788: @*/
789: PetscErrorCode PetscOptionsPrefixPush(const char prefix[])
790: {
792: size_t n;
793: PetscInt start;
794: char buf[2048];
795: PetscBool key;
799: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
800: buf[0] = '-';
801: PetscStrncpy(buf+1,prefix,sizeof buf - 1);
802: buf[sizeof buf - 1] = 0;
803: PetscOptionsValidKey(buf,&key);
804: 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);
806: if (!options) {PetscOptionsInsert(0,0,0);}
807: 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);
808: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
809: PetscStrlen(prefix,&n);
810: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
811: PetscMemcpy(options->prefix+start,prefix,n+1);
812: options->prefixstack[options->prefixind++] = start+n;
813: return(0);
814: }
818: /*@
819: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
821: Not Collective, but prefix will only be popped on calling ranks
823: Level: advanced
825: .seealso: PetscOptionsPrefixPush()
826: @*/
827: PetscErrorCode PetscOptionsPrefixPop(void)
828: {
829: PetscInt offset;
832: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
833: options->prefixind--;
834: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
835: options->prefix[offset] = 0;
836: return(0);
837: }
841: /*@C
842: PetscOptionsClear - Removes all options form the database leaving it empty.
844: Level: developer
846: .seealso: PetscOptionsInsert()
847: @*/
848: PetscErrorCode PetscOptionsClear(void)
849: {
850: PetscInt i;
853: if (!options) return(0);
854: for (i=0; i<options->N; i++) {
855: if (options->names[i]) free(options->names[i]);
856: if (options->values[i]) free(options->values[i]);
857: }
858: for (i=0; i<options->Naliases; i++) {
859: free(options->aliases1[i]);
860: free(options->aliases2[i]);
861: }
862: options->prefix[0] = 0;
863: options->prefixind = 0;
864: options->N = 0;
865: options->Naliases = 0;
866: return(0);
867: }
871: /*@C
872: PetscOptionsDestroy - Destroys the option database.
874: Note:
875: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
876: typically does not need to call this routine.
878: Level: developer
880: .seealso: PetscOptionsInsert()
881: @*/
882: PetscErrorCode PetscOptionsDestroy(void)
883: {
887: if (!options) return(0);
888: PetscOptionsClear();
889: free(options);
890: options = 0;
891: return(0);
892: }
896: /*@C
897: PetscOptionsSetValue - Sets an option name-value pair in the options
898: database, overriding whatever is already present.
900: Not collective, but setting values on certain processors could cause problems
901: for parallel objects looking for options.
903: Input Parameters:
904: + name - name of option, this SHOULD have the - prepended
905: - value - the option value (not used for all options)
907: Level: intermediate
909: Note:
910: Only some options have values associated with them, such as
911: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
913: Concepts: options database^adding option
915: .seealso: PetscOptionsInsert()
916: @*/
917: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
918: {
919: size_t len;
921: PetscInt N,n,i;
922: char **names;
923: char fullname[2048];
924: const char *name = iname;
925: PetscBool gt,match;
928: if (!options) {PetscOptionsInsert(0,0,0);}
930: /* this is so that -h and -hel\p are equivalent (p4 does not like -help)*/
931: PetscStrcasecmp(name,"-h",&match);
932: if (match) name = "-help";
934: name++; /* skip starting hyphen */
935: if (options->prefixind > 0) {
936: PetscStrncpy(fullname,options->prefix,sizeof fullname);
937: PetscStrncat(fullname,name,sizeof fullname);
938: name = fullname;
939: }
941: /* check against aliases */
942: N = options->Naliases;
943: for (i=0; i<N; i++) {
944: PetscStrcasecmp(options->aliases1[i],name,&match);
945: if (match) {
946: name = options->aliases2[i];
947: break;
948: }
949: }
951: N = options->N;
952: n = N;
953: names = options->names;
954:
955: for (i=0; i<N; i++) {
956: PetscStrcasecmp(names[i],name,&match);
957: PetscStrgrt(names[i],name,>);
958: if (match) {
959: if (options->values[i]) free(options->values[i]);
960: PetscStrlen(value,&len);
961: if (len) {
962: options->values[i] = (char*)malloc((len+1)*sizeof(char));
963: PetscStrcpy(options->values[i],value);
964: } else { options->values[i] = 0;}
965: PetscOptionsMonitor(name,value);
966: return(0);
967: } else if (gt) {
968: n = i;
969: break;
970: }
971: }
972: if (N >= MAXOPTIONS) {
973: 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);
974: }
975: /* shift remaining values down 1 */
976: for (i=N; i>n; i--) {
977: options->names[i] = options->names[i-1];
978: options->values[i] = options->values[i-1];
979: options->used[i] = options->used[i-1];
980: }
981: /* insert new name and value */
982: PetscStrlen(name,&len);
983: options->names[n] = (char*)malloc((len+1)*sizeof(char));
984: PetscStrcpy(options->names[n],name);
985: PetscStrlen(value,&len);
986: if (len) {
987: options->values[n] = (char*)malloc((len+1)*sizeof(char));
988: PetscStrcpy(options->values[n],value);
989: } else {options->values[n] = 0;}
990: options->used[n] = PETSC_FALSE;
991: options->N++;
992: PetscOptionsMonitor(name,value);
993: return(0);
994: }
998: /*@C
999: PetscOptionsClearValue - Clears an option name-value pair in the options
1000: database, overriding whatever is already present.
1002: Not Collective, but setting values on certain processors could cause problems
1003: for parallel objects looking for options.
1005: Input Parameter:
1006: . name - name of option, this SHOULD have the - prepended
1008: Level: intermediate
1010: Concepts: options database^removing option
1011: .seealso: PetscOptionsInsert()
1012: @*/
1013: PetscErrorCode PetscOptionsClearValue(const char iname[])
1014: {
1016: PetscInt N,n,i;
1017: char **names,*name=(char*)iname;
1018: PetscBool gt,match;
1021: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1022: if (!options) {PetscOptionsInsert(0,0,0);}
1024: name++;
1026: N = options->N; n = 0;
1027: names = options->names;
1028:
1029: for (i=0; i<N; i++) {
1030: PetscStrcasecmp(names[i],name,&match);
1031: PetscStrgrt(names[i],name,>);
1032: if (match) {
1033: if (options->names[i]) free(options->names[i]);
1034: if (options->values[i]) free(options->values[i]);
1035: PetscOptionsMonitor(name,"");
1036: break;
1037: } else if (gt) {
1038: return(0); /* it was not listed */
1039: }
1040: n++;
1041: }
1042: if (n == N) return(0); /* it was not listed */
1044: /* shift remaining values down 1 */
1045: for (i=n; i<N-1; i++) {
1046: options->names[i] = options->names[i+1];
1047: options->values[i] = options->values[i+1];
1048: options->used[i] = options->used[i+1];
1049: }
1050: options->N--;
1051: return(0);
1052: }
1056: /*@C
1057: PetscOptionsSetAlias - Makes a key and alias for another key
1059: Not Collective, but setting values on certain processors could cause problems
1060: for parallel objects looking for options.
1062: Input Parameters:
1063: + inewname - the alias
1064: - ioldname - the name that alias will refer to
1066: Level: advanced
1068: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1069: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1070: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1071: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1072: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1073: PetscOptionsList(), PetscOptionsEList()
1074: @*/
1075: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
1076: {
1078: PetscInt n = options->Naliases;
1079: size_t len;
1080: char *newname = (char *)inewname,*oldname = (char*)ioldname;
1083: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1084: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1085: if (n >= MAXALIASES) {
1086: 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);
1087: }
1089: newname++; oldname++;
1090: PetscStrlen(newname,&len);
1091: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1092: PetscStrcpy(options->aliases1[n],newname);
1093: PetscStrlen(oldname,&len);
1094: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1095: PetscStrcpy(options->aliases2[n],oldname);
1096: options->Naliases++;
1097: return(0);
1098: }
1102: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscBool *flg)
1103: {
1105: PetscInt i,N;
1106: size_t len;
1107: char **names,tmp[256];
1108: PetscBool match;
1111: if (!options) {PetscOptionsInsert(0,0,0);}
1112: N = options->N;
1113: names = options->names;
1115: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1117: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1118: if (pre) {
1119: char *ptr = tmp;
1120: const char *namep = name;
1121: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1122: if (name[1] == '-') {
1123: *ptr++ = '-';
1124: namep++;
1125: }
1126: PetscStrncpy(ptr,pre,tmp+sizeof tmp-ptr);
1127: tmp[sizeof tmp-1] = 0;
1128: PetscStrlen(tmp,&len);
1129: PetscStrncat(tmp,namep+1,sizeof tmp-len-1);
1130: } else {
1131: PetscStrncpy(tmp,name+1,sizeof tmp);
1132: tmp[sizeof tmp-1] = 0;
1133: }
1134: #if defined(PETSC_USE_DEBUG)
1135: {
1136: PetscBool valid;
1137: char key[sizeof tmp+1] = "-";
1138: PetscMemcpy(key+1,tmp,sizeof tmp);
1139: PetscOptionsValidKey(key,&valid);
1140: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1141: }
1142: #endif
1144: /* slow search */
1145: *flg = PETSC_FALSE;
1146: for (i=0; i<N; i++) {
1147: PetscStrcasecmp(names[i],tmp,&match);
1148: if (match) {
1149: *value = options->values[i];
1150: options->used[i] = PETSC_TRUE;
1151: *flg = PETSC_TRUE;
1152: break;
1153: }
1154: }
1155: if (!*flg) {
1156: PetscInt j,cnt = 0,locs[16],loce[16];
1157: size_t n;
1158: PetscStrlen(tmp,&n);
1159: /* determine the location and number of all _%d_ in the key */
1160: for (i=0; i< (PetscInt)n; i++) {
1161: if (tmp[i] == '_') {
1162: for (j=i+1; j< (PetscInt)n; j++) {
1163: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1164: if (tmp[j] == '_' && j > i+1) { /* found a number */
1165: locs[cnt] = i+1;
1166: loce[cnt++] = j+1;
1167: }
1168: break;
1169: }
1170: }
1171: }
1172: if (cnt) {
1173: char tmp2[256];
1174: for (i=0; i<cnt; i++) {
1175: PetscStrcpy(tmp2,"-");
1176: PetscStrncat(tmp2,tmp,locs[i]);
1177: PetscStrcat(tmp2,tmp+loce[i]);
1178: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
1179: if (*flg) break;
1180: }
1181: }
1182: }
1183: return(0);
1184: }
1188: /*@C
1189: PetscOptionsReject - Generates an error if a certain option is given.
1191: Not Collective, but setting values on certain processors could cause problems
1192: for parallel objects looking for options.
1194: Input Parameters:
1195: + name - the option one is seeking
1196: - mess - error message (may be PETSC_NULL)
1198: Level: advanced
1200: Concepts: options database^rejecting option
1202: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1203: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1204: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1205: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1206: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1207: PetscOptionsList(), PetscOptionsEList()
1208: @*/
1209: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
1210: {
1212: PetscBool flag = PETSC_FALSE;
1215: PetscOptionsHasName(PETSC_NULL,name,&flag);
1216: if (flag) {
1217: if (mess) {
1218: SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1219: } else {
1220: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1221: }
1222: }
1223: return(0);
1224: }
1228: /*@C
1229: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1230: its value is set to false.
1232: Not Collective
1234: Input Parameters:
1235: + name - the option one is seeking
1236: - pre - string to prepend to the name or PETSC_NULL
1238: Output Parameters:
1239: . set - PETSC_TRUE if found else PETSC_FALSE.
1241: Level: beginner
1243: Concepts: options database^has option name
1245: Notes: Name cannot be simply -h
1247: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1249: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1250: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1251: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1252: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1253: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1254: PetscOptionsList(), PetscOptionsEList()
1255: @*/
1256: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscBool *set)
1257: {
1258: char *value;
1260: PetscBool flag;
1263: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1264: if (set) *set = flag;
1265: return(0);
1266: }
1270: /*@C
1271: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1273: Not Collective
1275: Input Parameters:
1276: + pre - the string to prepend to the name or PETSC_NULL
1277: - name - the option one is seeking
1279: Output Parameter:
1280: + ivalue - the integer value to return
1281: - set - PETSC_TRUE if found, else PETSC_FALSE
1283: Level: beginner
1285: Concepts: options database^has int
1287: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1288: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1289: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1290: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1291: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1292: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1293: PetscOptionsList(), PetscOptionsEList()
1294: @*/
1295: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1296: {
1297: char *value;
1299: PetscBool flag;
1304: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1305: if (flag) {
1306: if (!value) {if (set) *set = PETSC_FALSE;}
1307: else {
1308: if (set) *set = PETSC_TRUE;
1309: PetscOptionsStringToInt(value,ivalue);
1310: }
1311: } else {
1312: if (set) *set = PETSC_FALSE;
1313: }
1314: return(0);
1315: }
1319: /*@C
1320: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1322: Not Collective
1324: Input Parameters:
1325: + pre - the string to prepend to the name or PETSC_NULL
1326: . opt - option name
1327: . list - the possible choices
1328: . ntext - number of choices
1330: Output Parameter:
1331: + value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1332: - set - PETSC_TRUE if found, else PETSC_FALSE
1333:
1334: Level: intermediate
1336: See PetscOptionsList() for when the choices are given in a PetscFList()
1338: Concepts: options database^list
1340: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1341: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1342: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1343: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1344: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1345: PetscOptionsList(), PetscOptionsEList()
1346: @*/
1347: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char *const*list,PetscInt ntext,PetscInt *value,PetscBool *set)
1348: {
1350: size_t alen,len = 0;
1351: char *svalue;
1352: PetscBool aset,flg = PETSC_FALSE;
1353: PetscInt i;
1356: for ( i=0; i<ntext; i++) {
1357: PetscStrlen(list[i],&alen);
1358: if (alen > len) len = alen;
1359: }
1360: len += 5; /* a little extra space for user mistypes */
1361: PetscMalloc(len*sizeof(char),&svalue);
1362: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1363: if (aset) {
1364: if (set) *set = PETSC_TRUE;
1365: for (i=0; i<ntext; i++) {
1366: PetscStrcasecmp(svalue,list[i],&flg);
1367: if (flg || !svalue[0]) {
1368: flg = PETSC_TRUE;
1369: *value = i;
1370: break;
1371: }
1372: }
1373: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1374: } else if (set) {
1375: *set = PETSC_FALSE;
1376: }
1377: PetscFree(svalue);
1378: return(0);
1379: }
1383: /*@C
1384: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1386: Not Collective
1388: Input Parameters:
1389: + pre - option prefix or PETSC_NULL
1390: . opt - option name
1391: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1392: - defaultv - the default (current) value
1394: Output Parameter:
1395: + value - the value to return
1396: - set - PETSC_TRUE if found, else PETSC_FALSE
1398: Level: beginner
1400: Concepts: options database
1402: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1404: list is usually something like PCASMTypes or some other predefined list of enum names
1406: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1407: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1408: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1409: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1410: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1411: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1412: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1413: @*/
1414: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char *const*list,PetscEnum *value,PetscBool *set)
1415: {
1417: PetscInt ntext = 0,tval;
1418: PetscBool fset;
1421: while (list[ntext++]) {
1422: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1423: }
1424: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1425: ntext -= 3;
1426: PetscOptionsGetEList(pre,opt,list,ntext,&tval,&fset);
1427: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1428: if (fset) *value = (PetscEnum)tval;
1429: if (set) *set = fset;
1430: return(0);
1431: }
1435: /*@C
1436: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1437: option in the database.
1439: Not Collective
1441: Input Parameters:
1442: + pre - the string to prepend to the name or PETSC_NULL
1443: - name - the option one is seeking
1445: Output Parameter:
1446: + ivalue - the logical value to return
1447: - set - PETSC_TRUE if found, else PETSC_FALSE
1449: Level: beginner
1451: Notes:
1452: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1453: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1455: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1456: you NEED TO ALWAYS initialize the ivalue.
1458: Concepts: options database^has logical
1460: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1461: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1462: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1463: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1464: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1465: PetscOptionsList(), PetscOptionsEList()
1466: @*/
1467: PetscErrorCode PetscOptionsGetBool(const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1468: {
1469: char *value;
1470: PetscBool flag;
1476: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1477: if (flag) {
1478: if (set) *set = PETSC_TRUE;
1479: if (!value) {
1480: *ivalue = PETSC_TRUE;
1481: } else {
1482: PetscOptionsStringToBool(value, ivalue);
1483: }
1484: } else {
1485: if (set) *set = PETSC_FALSE;
1486: }
1487: return(0);
1488: }
1492: /*@C
1493: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1494: option in the database. The values must be separated with commas with
1495: no intervening spaces.
1497: Not Collective
1499: Input Parameters:
1500: + pre - string to prepend to each name or PETSC_NULL
1501: . name - the option one is seeking
1502: - nmax - maximum number of values to retrieve
1504: Output Parameter:
1505: + dvalue - the integer values to return
1506: . nmax - actual number of values retreived
1507: - set - PETSC_TRUE if found, else PETSC_FALSE
1509: Level: beginner
1511: Concepts: options database^array of ints
1513: Notes:
1514: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1515: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1517: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1518: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1519: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1520: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1521: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1522: PetscOptionsList(), PetscOptionsEList()
1523: @*/
1524: PetscErrorCode PetscOptionsGetBoolArray(const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1525: {
1526: char *value;
1528: PetscInt n = 0;
1529: PetscBool flag;
1530: PetscToken token;
1535: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1536: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1537: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1539: if (set) *set = PETSC_TRUE;
1541: PetscTokenCreate(value,',',&token);
1542: PetscTokenFind(token,&value);
1543: while (n < *nmax) {
1544: if (!value) break;
1545: PetscOptionsStringToBool(value,dvalue);
1546: PetscTokenFind(token,&value);
1547: dvalue++;
1548: n++;
1549: }
1550: PetscTokenDestroy(&token);
1551: *nmax = n;
1552: return(0);
1553: }
1557: /*@C
1558: PetscOptionsGetReal - Gets the double precision value for a particular
1559: option in the database.
1561: Not Collective
1563: Input Parameters:
1564: + pre - string to prepend to each name or PETSC_NULL
1565: - name - the option one is seeking
1567: Output Parameter:
1568: + dvalue - the double value to return
1569: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1571: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1573: Level: beginner
1575: Concepts: options database^has double
1577: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1578: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1579: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1580: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1581: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1582: PetscOptionsList(), PetscOptionsEList()
1583: @*/
1584: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1585: {
1586: char *value;
1588: PetscBool flag;
1593: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1594: if (flag) {
1595: if (!value) {if (set) *set = PETSC_FALSE;}
1596: else {if (set) *set = PETSC_TRUE; PetscOptionsStringToReal(value,dvalue);}
1597: } else {
1598: if (set) *set = PETSC_FALSE;
1599: }
1600: return(0);
1601: }
1605: /*@C
1606: PetscOptionsGetScalar - Gets the scalar value for a particular
1607: option in the database.
1609: Not Collective
1611: Input Parameters:
1612: + pre - string to prepend to each name or PETSC_NULL
1613: - name - the option one is seeking
1615: Output Parameter:
1616: + dvalue - the double value to return
1617: - set - PETSC_TRUE if found, else PETSC_FALSE
1619: Level: beginner
1621: Usage:
1622: A complex number 2+3i can be specified as 2,3 at the command line.
1623: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,-3.3e-20
1625: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1627: Concepts: options database^has scalar
1629: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1630: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1631: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1632: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1633: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1634: PetscOptionsList(), PetscOptionsEList()
1635: @*/
1636: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1637: {
1638: char *value;
1639: PetscBool flag;
1645: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1646: if (flag) {
1647: if (!value) {
1648: if (set) *set = PETSC_FALSE;
1649: } else {
1650: #if !defined(PETSC_USE_COMPLEX)
1651: PetscOptionsStringToReal(value,dvalue);
1652: #else
1653: PetscReal re=0.0,im=0.0;
1654: PetscToken token;
1655: char *tvalue = 0;
1657: PetscTokenCreate(value,',',&token);
1658: PetscTokenFind(token,&tvalue);
1659: if (!tvalue) { SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1660: PetscOptionsStringToReal(tvalue,&re);
1661: PetscTokenFind(token,&tvalue);
1662: if (!tvalue) { /* Unknown separator used. using only real value */
1663: *dvalue = re;
1664: } else {
1665: PetscOptionsStringToReal(tvalue,&im);
1666: *dvalue = re + PETSC_i*im;
1667: }
1668: PetscTokenDestroy(&token);
1669: #endif
1670: if (set) *set = PETSC_TRUE;
1671: }
1672: } else { /* flag */
1673: if (set) *set = PETSC_FALSE;
1674: }
1675: return(0);
1676: }
1680: /*@C
1681: PetscOptionsGetRealArray - Gets an array of double precision values for a
1682: particular option in the database. The values must be separated with
1683: commas with no intervening spaces.
1685: Not Collective
1687: Input Parameters:
1688: + pre - string to prepend to each name or PETSC_NULL
1689: . name - the option one is seeking
1690: - nmax - maximum number of values to retrieve
1692: Output Parameters:
1693: + dvalue - the double value to return
1694: . nmax - actual number of values retreived
1695: - set - PETSC_TRUE if found, else PETSC_FALSE
1697: Level: beginner
1699: Concepts: options database^array of doubles
1701: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1702: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1703: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1704: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1705: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1706: PetscOptionsList(), PetscOptionsEList()
1707: @*/
1708: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
1709: {
1710: char *value;
1712: PetscInt n = 0;
1713: PetscBool flag;
1714: PetscToken token;
1719: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1720: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1721: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1723: if (set) *set = PETSC_TRUE;
1725: PetscTokenCreate(value,',',&token);
1726: PetscTokenFind(token,&value);
1727: while (n < *nmax) {
1728: if (!value) break;
1729: PetscOptionsStringToReal(value,dvalue++);
1730: PetscTokenFind(token,&value);
1731: n++;
1732: }
1733: PetscTokenDestroy(&token);
1734: *nmax = n;
1735: return(0);
1736: }
1740: /*@C
1741: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1742: option in the database.
1744: Not Collective
1746: Input Parameters:
1747: + pre - string to prepend to each name or PETSC_NULL
1748: . name - the option one is seeking
1749: - nmax - maximum number of values to retrieve
1751: Output Parameter:
1752: + dvalue - the integer values to return
1753: . nmax - actual number of values retreived
1754: - set - PETSC_TRUE if found, else PETSC_FALSE
1756: Level: beginner
1758: Notes:
1759: The array can be passed as
1760: a comma seperated list: 0,1,2,3,4,5,6,7
1761: a range (start-end+1): 0-8
1762: a range with given increment (start-end+1:inc): 0-7:2
1763: a combination of values and ranges seperated by commas: 0,1-8,8-15:2
1765: There must be no intervening spaces between the values.
1767: Concepts: options database^array of ints
1769: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1770: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1771: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1772: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1773: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1774: PetscOptionsList(), PetscOptionsEList()
1775: @*/
1776: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
1777: {
1778: char *value;
1780: PetscInt n = 0,i,j,start,end,inc,nvalues;
1781: size_t len;
1782: PetscBool flag,foundrange;
1783: PetscToken token;
1788: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1789: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1790: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1792: if (set) *set = PETSC_TRUE;
1794: PetscTokenCreate(value,',',&token);
1795: PetscTokenFind(token,&value);
1796: while (n < *nmax) {
1797: if (!value) break;
1798:
1799: /* look for form d-D where d and D are integers */
1800: foundrange = PETSC_FALSE;
1801: PetscStrlen(value,&len);
1802: if (value[0] == '-') i=2;
1803: else i=1;
1804: for (;i<(int)len; i++) {
1805: if (value[i] == '-') {
1806: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
1807: value[i] = 0;
1808: PetscOptionsStringToInt(value,&start);
1809: inc = 1;
1810: j = i+1;
1811: for(;j<(int)len; j++) {
1812: if (value[j] == ':') {
1813: value[j] = 0;
1814: PetscOptionsStringToInt(value+j+1,&inc);
1815: if (inc <= 0) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry,%s cannot have negative increment",n,value+j+1);
1816: break;
1817: }
1818: }
1819: PetscOptionsStringToInt(value+i+1,&end);
1820: 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);
1821: nvalues = (end-start)/inc + (end-start)%inc;
1822: if (n + nvalues > *nmax) SETERRQ4(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry, not enough space left in array (%D) to contain entire range from %D to %D",n,*nmax-n,start,end);
1823: for (;start<end; start+=inc) {
1824: *dvalue = start; dvalue++;n++;
1825: }
1826: foundrange = PETSC_TRUE;
1827: break;
1828: }
1829: }
1830: if (!foundrange) {
1831: PetscOptionsStringToInt(value,dvalue);
1832: dvalue++;
1833: n++;
1834: }
1835: PetscTokenFind(token,&value);
1836: }
1837: PetscTokenDestroy(&token);
1838: *nmax = n;
1839: return(0);
1840: }
1844: /*@C
1845: PetscOptionsGetString - Gets the string value for a particular option in
1846: the database.
1848: Not Collective
1850: Input Parameters:
1851: + pre - string to prepend to name or PETSC_NULL
1852: . name - the option one is seeking
1853: - len - maximum length of the string including null termination
1855: Output Parameters:
1856: + string - location to copy string
1857: - set - PETSC_TRUE if found, else PETSC_FALSE
1859: Level: beginner
1861: Fortran Note:
1862: The Fortran interface is slightly different from the C/C++
1863: interface (len is not used). Sample usage in Fortran follows
1864: .vb
1865: character *20 string
1866: integer flg, ierr
1867: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1868: .ve
1870: 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
1872: Concepts: options database^string
1874: Note:
1875: 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).
1877: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1878: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1879: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1880: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1881: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1882: PetscOptionsList(), PetscOptionsEList()
1883: @*/
1884: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscBool *set)
1885: {
1886: char *value;
1888: PetscBool flag;
1893: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1894: if (!flag) {
1895: if (set) *set = PETSC_FALSE;
1896: } else {
1897: if (set) *set = PETSC_TRUE;
1898: if (value) {
1899: PetscStrncpy(string,value,len);
1900: string[len-1] = 0; /* Ensure that the string is NULL terminated */
1901: } else {
1902: PetscMemzero(string,len);
1903: }
1904: }
1905: return(0);
1906: }
1910: char* PetscOptionsGetStringMatlab(const char pre[],const char name[])
1911: {
1912: char *value;
1914: PetscBool flag;
1917: PetscOptionsFindPair_Private(pre,name,&value,&flag);if (ierr) return(0);
1918: if (flag) PetscFunctionReturn(value);
1919: else return(0);
1920: }
1925: /*@C
1926: PetscOptionsGetStringArray - Gets an array of string values for a particular
1927: option in the database. The values must be separated with commas with
1928: no intervening spaces.
1930: Not Collective
1932: Input Parameters:
1933: + pre - string to prepend to name or PETSC_NULL
1934: . name - the option one is seeking
1935: - nmax - maximum number of strings
1937: Output Parameter:
1938: + strings - location to copy strings
1939: - set - PETSC_TRUE if found, else PETSC_FALSE
1941: Level: beginner
1943: Notes:
1944: The user should pass in an array of pointers to char, to hold all the
1945: strings returned by this function.
1947: The user is responsible for deallocating the strings that are
1948: returned. The Fortran interface for this routine is not supported.
1950: Contributed by Matthew Knepley.
1952: Concepts: options database^array of strings
1954: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1955: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1956: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1957: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1958: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1959: PetscOptionsList(), PetscOptionsEList()
1960: @*/
1961: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
1962: {
1963: char *value;
1965: PetscInt n;
1966: PetscBool flag;
1967: PetscToken token;
1968:
1972: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1973: if (!flag) {*nmax = 0; if (set) *set = PETSC_FALSE; return(0);}
1974: if (!value) {*nmax = 0; if (set) *set = PETSC_FALSE;return(0);}
1975: if (!*nmax) {if (set) *set = PETSC_FALSE;return(0);}
1976: if (set) *set = PETSC_TRUE;
1978: PetscTokenCreate(value,',',&token);
1979: PetscTokenFind(token,&value);
1980: n = 0;
1981: while (n < *nmax) {
1982: if (!value) break;
1983: PetscStrallocpy(value,&strings[n]);
1984: PetscTokenFind(token,&value);
1985: n++;
1986: }
1987: PetscTokenDestroy(&token);
1988: *nmax = n;
1989: return(0);
1990: }
1994: /*@C
1995: PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database
1997: Not Collective
1999: Input Parameter:
2000: . option - string name of option
2002: Output Parameter:
2003: . used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database
2005: Level: advanced
2007: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2008: @*/
2009: PetscErrorCode PetscOptionsUsed(const char *option,PetscBool *used)
2010: {
2011: PetscInt i;
2015: *used = PETSC_FALSE;
2016: for (i=0; i<options->N; i++) {
2017: PetscStrcmp(options->names[i],option,used);
2018: if (*used) {
2019: *used = options->used[i];
2020: break;
2021: }
2022: }
2023: return(0);
2024: }
2028: /*@C
2029: PetscOptionsAllUsed - Returns a count of the number of options in the
2030: database that have never been selected.
2032: Not Collective
2034: Output Parameter:
2035: . N - count of options not used
2037: Level: advanced
2039: .seealso: PetscOptionsView()
2040: @*/
2041: PetscErrorCode PetscOptionsAllUsed(PetscInt *N)
2042: {
2043: PetscInt i,n = 0;
2046: for (i=0; i<options->N; i++) {
2047: if (!options->used[i]) { n++; }
2048: }
2049: *N = n;
2050: return(0);
2051: }
2055: /*@
2056: PetscOptionsLeft - Prints to screen any options that were set and never used.
2058: Not collective
2060: Options Database Key:
2061: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
2063: Level: advanced
2065: .seealso: PetscOptionsAllUsed()
2066: @*/
2067: PetscErrorCode PetscOptionsLeft(void)
2068: {
2070: PetscInt i;
2073: for (i=0; i<options->N; i++) {
2074: if (!options->used[i]) {
2075: if (options->values[i]) {
2076: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2077: } else {
2078: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
2079: }
2080: }
2081: }
2082: return(0);
2083: }
2088: /*
2089: PetscOptionsCreate - Creates the empty options database.
2091: */
2092: PetscErrorCode PetscOptionsCreate(void)
2093: {
2097: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
2098: PetscMemzero(options,sizeof(PetscOptionsTable));
2099: options->namegiven = PETSC_FALSE;
2100: options->N = 0;
2101: options->Naliases = 0;
2102: options->numbermonitors = 0;
2104: PetscOptionsObject.prefix = PETSC_NULL;
2105: PetscOptionsObject.title = PETSC_NULL;
2106:
2107: return(0);
2108: }
2112: /*@
2113: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
2115: Collective on PETSC_COMM_WORLD
2117: Options Database Keys:
2118: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2119: available for options set through a file, environment variable, or on
2120: the command line. Only options set after PetscInitialize completes will
2121: be monitored.
2122: . -options_monitor_cancel - cancel all options database monitors
2124: Notes:
2125: To see all options, run your program with the -help option or consult
2126: the <A href="../../docs/manual.pdf">users manual</A>..
2128: Level: intermediate
2130: .keywords: set, options, database
2131: @*/
2132: PetscErrorCode PetscOptionsSetFromOptions(void)
2133: {
2134: PetscBool flgc,flgm;
2135: PetscErrorCode ierr;
2136: char monfilename[PETSC_MAX_PATH_LEN];
2137: PetscViewer monviewer;
2140: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
2141: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2142: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",PETSC_FALSE,&flgc,PETSC_NULL);
2143: PetscOptionsEnd();
2144: if (flgm) {
2145: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2146: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2147: }
2148: if (flgc) { PetscOptionsMonitorCancel(); }
2149: return(0);
2150: }
2155: /*@C
2156: PetscOptionsMonitorDefault - Print all options set value events.
2158: Logically Collective on PETSC_COMM_WORLD
2160: Input Parameters:
2161: + name - option name string
2162: . value - option value string
2163: - dummy - unused monitor context
2165: Level: intermediate
2167: .keywords: PetscOptions, default, monitor
2169: .seealso: PetscOptionsMonitorSet()
2170: @*/
2171: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2172: {
2174: PetscViewer viewer = (PetscViewer) dummy;
2177: if (!viewer) {
2178: PetscViewerASCIIGetStdout(PETSC_COMM_WORLD,&viewer);
2179: }
2180: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2181: return(0);
2182: }
2186: /*@C
2187: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2188: modified the PETSc options database.
2189:
2190: Not collective
2192: Input Parameters:
2193: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
2194: . mctx - [optional] context for private data for the
2195: monitor routine (use PETSC_NULL if no context is desired)
2196: - monitordestroy - [optional] routine that frees monitor context
2197: (may be PETSC_NULL)
2199: Calling Sequence of monitor:
2200: $ monitor (const char name[], const char value[], void *mctx)
2202: + name - option name string
2203: . value - option value string
2204: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2206: Options Database Keys:
2207: + -options_monitor - sets PetscOptionsMonitorDefault()
2208: - -options_monitor_cancel - cancels all monitors that have
2209: been hardwired into a code by
2210: calls to PetscOptionsMonitorSet(), but
2211: does not cancel those set via
2212: the options database.
2214: Notes:
2215: The default is to do nothing. To print the name and value of options
2216: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2217: with a null monitoring context.
2219: Several different monitoring routines may be set by calling
2220: PetscOptionsMonitorSet() multiple times; all will be called in the
2221: order in which they were set.
2223: Level: beginner
2225: .keywords: PetscOptions, set, monitor
2227: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2228: @*/
2229: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2230: {
2232: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2233: options->monitor[options->numbermonitors] = monitor;
2234: options->monitordestroy[options->numbermonitors] = monitordestroy;
2235: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2236: return(0);
2237: }
2241: /*@
2242: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2244: Not collective
2246: Options Database Key:
2247: . -options_monitor_cancel - Cancels all monitors that have
2248: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2249: but does not cancel those set via the options database.
2251: Level: intermediate
2253: .keywords: PetscOptions, set, monitor
2255: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2256: @*/
2257: PetscErrorCode PetscOptionsMonitorCancel(void)
2258: {
2260: PetscInt i;
2263: for (i=0; i<options->numbermonitors; i++) {
2264: if (options->monitordestroy[i]) {
2265: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2266: }
2267: }
2268: options->numbermonitors = 0;
2269: return(0);
2270: }