Actual source code: options.c
petsc-3.7.7 2017-09-25
2: /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
3: #define PETSC_DESIRE_FEATURE_TEST_MACROS
5: /*
6: These routines simplify the use of command line, file options, etc., and are used to manipulate the options database.
7: This provides the low-level interface, the high level interface is in aoptions.c
9: Some routines use regular malloc and free because it cannot know what malloc is requested with the
10: options database until it has already processed the input.
11: */
13: #include <petsc/private/petscimpl.h> /*I "petscsys.h" I*/
14: #include <petscviewer.h>
15: #include <ctype.h>
16: #if defined(PETSC_HAVE_MALLOC_H)
17: #include <malloc.h>
18: #endif
19: #if defined(PETSC_HAVE_STRING_H)
20: #include <string.h> /* strstr */
21: #endif
22: #if defined(PETSC_HAVE_STRINGS_H)
23: # include <strings.h> /* strcasecmp */
24: #endif
25: #if defined(PETSC_HAVE_YAML)
26: #include <yaml.h>
27: #endif
29: /*
30: This table holds all the options set by the user. For simplicity, we use a static size database
31: */
32: #define MAXOPTIONS 512
33: #define MAXALIASES 25
34: #define MAXOPTIONSMONITORS 5
35: #define MAXPREFIXES 25
37: struct _n_PetscOptions {
38: int N,argc,Naliases;
39: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
40: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
41: PetscBool used[MAXOPTIONS];
42: PetscBool namegiven;
43: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
45: /* --------User (or default) routines (most return -1 on error) --------*/
46: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
47: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void**); /* */
48: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
49: PetscInt numbermonitors; /* to, for instance, detect options being set */
51: /* Prefixes */
52: PetscInt prefixind,prefixstack[MAXPREFIXES];
53: char prefix[2048];
54: };
57: static PetscOptions defaultoptions = NULL;
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) *a = PETSC_DEFAULT;
95: else if (decide) *a = PETSC_DECIDE;
96: else if (mouse) *a = -1;
97: else {
98: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
100: for (i=1; i<len; i++) {
101: if (name[i] < '0' || name[i] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
102: }
104: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
105: *a = atoll(name);
106: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
107: *a = _atoi64(name);
108: #else
109: *a = (PetscInt)atoi(name);
110: #endif
111: }
112: return(0);
113: }
115: #if defined(PETSC_USE_REAL___FLOAT128)
116: #include <quadmath.h>
117: #endif
121: /*
122: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
123: */
124: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
125: {
127: size_t len;
128: PetscBool decide,tdefault;
131: PetscStrlen(name,&len);
132: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
134: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
135: if (!tdefault) {
136: PetscStrcasecmp(name,"DEFAULT",&tdefault);
137: }
138: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
139: if (!decide) {
140: PetscStrcasecmp(name,"DECIDE",&decide);
141: }
143: if (tdefault) *a = PETSC_DEFAULT;
144: else if (decide) *a = PETSC_DECIDE;
145: else {
146: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
147: #if defined(PETSC_USE_REAL___FLOAT128)
148: *a = strtoflt128(name,NULL);
149: #else
150: *a = atof(name);
151: #endif
152: }
153: return(0);
154: }
158: /*
159: Converts a string to PetscScalar value. Handles
160: [-][2].0
161: [-][2].0i
162: [-][2].0+/-2.0i
164: */
165: PetscErrorCode PetscOptionsStringToScalar(const char name[],PetscScalar *a)
166: {
168: size_t len;
171: PetscStrlen(name,&len);
172: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
174: if (name[0] == '+') name++;
175: if (name[0] == 'i') {
176: #if defined(PETSC_USE_COMPLEX)
177: *a = PETSC_i;
178: #else
179: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
180: #endif
181: } else {
182: PetscToken token;
183: char *tvalue1,*tvalue2;
184: PetscBool neg = PETSC_FALSE, negim = PETSC_FALSE;
185: PetscReal re = 0.0,im = 0.0;
187: if (name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
188: if (name[0] == '-') {
189: neg = PETSC_TRUE;
190: name++;
191: }
192: if (name[0] == 'i') {
193: #if defined(PETSC_USE_COMPLEX)
194: *a = -PETSC_i;
195: #else
196: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is imaginary but complex not supported ",name);
197: #endif
198: return(0);
199: }
201: PetscTokenCreate(name,'+',&token);
202: PetscTokenFind(token,&tvalue1);
203: PetscTokenFind(token,&tvalue2);
204: if (!tvalue2) {
205: negim = PETSC_TRUE;
206: PetscTokenDestroy(&token);
207: PetscTokenCreate(name,'-',&token);
208: PetscTokenFind(token,&tvalue1);
209: PetscTokenFind(token,&tvalue2);
210: }
211: if (!tvalue2) {
212: PetscBool isim;
213: PetscStrendswith(tvalue1,"i",&isim);
214: if (isim) {
215: tvalue2 = tvalue1;
216: tvalue1 = NULL;
217: negim = neg;
218: }
219: } else {
220: PetscBool isim;
221: PetscStrendswith(tvalue2,"i",&isim);
222: if (!isim) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
223: }
224: if (tvalue1) {
225: PetscOptionsStringToReal(tvalue1,&re);
226: if (neg) re = -re;
227: }
228: if (tvalue2) {
229: PetscStrlen(tvalue2,&len);
230: tvalue2[len-1] = 0;
231: PetscOptionsStringToReal(tvalue2,&im);
232: if (negim) im = -im;
233: }
234: PetscTokenDestroy(&token);
235: #if defined(PETSC_USE_COMPLEX)
236: *a = re + im*PETSC_i;
237: #else
238: if (im != 0.0) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s is complex but complex not supported ",name);
239: *a = re;
240: #endif
241: }
242: return(0);
243: }
247: /*
248: PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
249: */
250: PetscErrorCode PetscOptionsStringToBool(const char value[], PetscBool *a)
251: {
252: PetscBool istrue, isfalse;
253: size_t len;
257: PetscStrlen(value, &len);
258: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
259: PetscStrcasecmp(value,"TRUE",&istrue);
260: if (istrue) {*a = PETSC_TRUE; return(0);}
261: PetscStrcasecmp(value,"YES",&istrue);
262: if (istrue) {*a = PETSC_TRUE; return(0);}
263: PetscStrcasecmp(value,"1",&istrue);
264: if (istrue) {*a = PETSC_TRUE; return(0);}
265: PetscStrcasecmp(value,"on",&istrue);
266: if (istrue) {*a = PETSC_TRUE; return(0);}
267: PetscStrcasecmp(value,"FALSE",&isfalse);
268: if (isfalse) {*a = PETSC_FALSE; return(0);}
269: PetscStrcasecmp(value,"NO",&isfalse);
270: if (isfalse) {*a = PETSC_FALSE; return(0);}
271: PetscStrcasecmp(value,"0",&isfalse);
272: if (isfalse) {*a = PETSC_FALSE; return(0);}
273: PetscStrcasecmp(value,"off",&isfalse);
274: if (isfalse) {*a = PETSC_FALSE; return(0);}
275: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
276: }
280: /*@C
281: PetscGetProgramName - Gets the name of the running program.
283: Not Collective
285: Input Parameter:
286: . len - length of the string name
288: Output Parameter:
289: . name - the name of the running program
291: Level: advanced
293: Notes:
294: The name of the program is copied into the user-provided character
295: array of length len. On some machines the program name includes
296: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
297: @*/
298: PetscErrorCode PetscGetProgramName(char name[],size_t len)
299: {
303: PetscStrncpy(name,defaultoptions->programname,len);
304: return(0);
305: }
309: PetscErrorCode PetscSetProgramName(const char name[])
310: {
314: PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);
315: return(0);
316: }
320: /*@
321: PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter.
323: Input Parameter:
324: . in_str - string to check if valid
326: Output Parameter:
327: . key - PETSC_TRUE if a valid key
329: Level: intermediate
331: @*/
332: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscBool *key)
333: {
334: PetscBool inf,INF;
338: *key = PETSC_FALSE;
339: if (!in_str) return(0);
340: if (in_str[0] != '-') return(0);
341: if (in_str[1] == '-') in_str++;
342: if (!isalpha((int)(in_str[1]))) return(0);
343: PetscStrncmp(in_str+1,"inf",3,&inf);
344: PetscStrncmp(in_str+1,"INF",3,&INF);
345: if ((inf || INF) && !(in_str[4] == '_' || isalnum((int)(in_str[4])))) return(0);
346: *key = PETSC_TRUE;
347: return(0);
348: }
352: /*@C
353: PetscOptionsInsertString - Inserts options into the database from a string
355: Not collective: but only processes that call this routine will set the options
356: included in the string
358: Input Parameter:
359: . in_str - string that contains options separated by blanks
362: Level: intermediate
364: Contributed by Boyana Norris
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: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()
373: @*/
374: PetscErrorCode PetscOptionsInsertString(PetscOptions options,const char in_str[])
375: {
376: char *first,*second;
378: PetscToken token;
379: PetscBool key,ispush,ispop;
382: options = options ? options : defaultoptions;
383: PetscTokenCreate(in_str,' ',&token);
384: PetscTokenFind(token,&first);
385: while (first) {
386: PetscStrcasecmp(first,"-prefix_push",&ispush);
387: PetscStrcasecmp(first,"-prefix_pop",&ispop);
388: PetscOptionsValidKey(first,&key);
389: if (ispush) {
390: PetscTokenFind(token,&second);
391: PetscOptionsPrefixPush(options,second);
392: PetscTokenFind(token,&first);
393: } else if (ispop) {
394: PetscOptionsPrefixPop(options);
395: PetscTokenFind(token,&first);
396: } else if (key) {
397: PetscTokenFind(token,&second);
398: PetscOptionsValidKey(second,&key);
399: if (!key) {
400: PetscOptionsSetValue(options,first,second);
401: PetscTokenFind(token,&first);
402: } else {
403: PetscOptionsSetValue(options,first,NULL);
404: first = second;
405: }
406: } else {
407: PetscTokenFind(token,&first);
408: }
409: }
410: PetscTokenDestroy(&token);
411: return(0);
412: }
414: /*
415: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
416: */
417: static char *Petscgetline(FILE * f)
418: {
419: size_t size = 0;
420: size_t len = 0;
421: size_t last = 0;
422: char *buf = NULL;
424: if (feof(f)) return 0;
425: do {
426: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
427: buf = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
428: /* Actually do the read. Note that fgets puts a terminal '\0' on the
429: end of the string, so we make sure we overwrite this */
430: if (!fgets(buf+len,size,f)) buf[len]=0;
431: PetscStrlen(buf,&len);
432: last = len - 1;
433: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
434: if (len) return buf;
435: free(buf);
436: return 0;
437: }
442: /*@C
443: PetscOptionsInsertFile - Inserts options into the database from a file.
445: Collective on MPI_Comm
447: Input Parameter:
448: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
449: . options - options database, use NULL for default global database
450: . file - name of file
451: - require - if PETSC_TRUE will generate an error if the file does not exist
454: Notes: Use # for lines that are comments and which should be ignored.
456: Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
457: such as -log_summary or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later
458: calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().
460: Level: developer
462: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
463: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
464: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
465: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
466: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
467: PetscOptionsFList(), PetscOptionsEList()
469: @*/
470: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
471: {
472: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
474: size_t i,len,bytes;
475: FILE *fd;
476: PetscToken token;
477: int err;
478: char cmt[1]={'#'},*cmatch;
479: PetscMPIInt rank,cnt=0,acnt=0,counts[2];
480: PetscBool isdir;
483: options = options ? options : defaultoptions;
484: MPI_Comm_rank(comm,&rank);
485: if (!rank) {
486: cnt = 0;
487: acnt = 0;
489: PetscFixFilename(file,fname);
490: fd = fopen(fname,"r");
491: PetscTestDirectory(fname,'r',&isdir);
492: if (isdir && require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Specified options file %s is a directory",fname);
493: if (fd && !isdir) {
494: PetscSegBuffer vseg,aseg;
495: PetscSegBufferCreate(1,4000,&vseg);
496: PetscSegBufferCreate(1,2000,&aseg);
498: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
499: PetscInfo1(0,"Opened options file %s\n",file);
501: while ((string = Petscgetline(fd))) {
502: /* eliminate comments from each line */
503: for (i=0; i<1; i++) {
504: PetscStrchr(string,cmt[i],&cmatch);
505: if (cmatch) *cmatch = 0;
506: }
507: PetscStrlen(string,&len);
508: /* replace tabs, ^M, \n with " " */
509: for (i=0; i<len; i++) {
510: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
511: string[i] = ' ';
512: }
513: }
514: PetscTokenCreate(string,' ',&token);
515: PetscTokenFind(token,&first);
516: if (!first) {
517: goto destroy;
518: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
519: PetscTokenFind(token,&first);
520: }
521: PetscTokenFind(token,&second);
522: if (!first) {
523: goto destroy;
524: } else if (first[0] == '-') {
525: PetscStrlen(first,&len);
526: PetscSegBufferGet(vseg,len+1,&vstring);
527: PetscMemcpy(vstring,first,len);
528: vstring[len] = ' ';
529: if (second) {
530: PetscStrlen(second,&len);
531: PetscSegBufferGet(vseg,len+3,&vstring);
532: vstring[0] = '"';
533: PetscMemcpy(vstring+1,second,len);
534: vstring[len+1] = '"';
535: vstring[len+2] = ' ';
536: }
537: } else {
538: PetscBool match;
540: PetscStrcasecmp(first,"alias",&match);
541: if (match) {
542: PetscTokenFind(token,&third);
543: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
544: PetscStrlen(second,&len);
545: PetscSegBufferGet(aseg,len+1,&astring);
546: PetscMemcpy(astring,second,len);
547: astring[len] = ' ';
549: PetscStrlen(third,&len);
550: PetscSegBufferGet(aseg,len+1,&astring);
551: PetscMemcpy(astring,third,len);
552: astring[len] = ' ';
553: } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
554: }
555: destroy:
556: free(string);
557: PetscTokenDestroy(&token);
558: }
559: err = fclose(fd);
560: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
561: PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
562: PetscMPIIntCast(bytes,&acnt);
563: PetscSegBufferGet(aseg,1,&astring);
564: astring[0] = 0;
565: PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
566: PetscMPIIntCast(bytes,&cnt);
567: PetscSegBufferGet(vseg,1,&vstring);
568: vstring[0] = 0;
569: PetscMalloc1(2+acnt+cnt,&packed);
570: PetscSegBufferExtractTo(aseg,packed);
571: PetscSegBufferExtractTo(vseg,packed+acnt+1);
572: PetscSegBufferDestroy(&aseg);
573: PetscSegBufferDestroy(&vseg);
574: } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
575: }
577: counts[0] = acnt;
578: counts[1] = cnt;
579: MPI_Bcast(counts,2,MPI_INT,0,comm);
580: acnt = counts[0];
581: cnt = counts[1];
582: if (rank) {
583: PetscMalloc1(2+acnt+cnt,&packed);
584: }
585: if (acnt || cnt) {
586: MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
587: astring = packed;
588: vstring = packed + acnt + 1;
589: }
591: if (acnt) {
592: PetscToken token;
593: char *first,*second;
595: PetscTokenCreate(astring,' ',&token);
596: PetscTokenFind(token,&first);
597: while (first) {
598: PetscTokenFind(token,&second);
599: PetscOptionsSetAlias(options,first,second);
600: PetscTokenFind(token,&first);
601: }
602: PetscTokenDestroy(&token);
603: }
605: if (cnt) {
606: PetscOptionsInsertString(options,vstring);
607: }
608: PetscFree(packed);
609: return(0);
610: }
614: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
615: {
617: int left = argc - 1;
618: char **eargs = args + 1;
621: options = options ? options : defaultoptions;
622: while (left) {
623: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
624: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
625: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
626: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
627: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
628: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
629: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
630: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
631: isp4 = (PetscBool) (isp4 || tisp4);
632: PetscStrcasecmp(eargs[0],"-np",&tisp4);
633: isp4 = (PetscBool) (isp4 || tisp4);
634: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
635: PetscOptionsValidKey(eargs[0],&key);
637: if (!key) {
638: eargs++; left--;
639: } else if (isoptions_file) {
640: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
641: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
642: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
643: eargs += 2; left -= 2;
644: } else if (isprefixpush) {
645: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
646: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
647: PetscOptionsPrefixPush(options,eargs[1]);
648: eargs += 2; left -= 2;
649: } else if (isprefixpop) {
650: PetscOptionsPrefixPop(options);
651: eargs++; left--;
653: /*
654: These are "bad" options that MPICH, etc put on the command line
655: we strip them out here.
656: */
657: } else if (tisp4 || isp4rmrank) {
658: eargs += 1; left -= 1;
659: } else if (isp4 || isp4yourname) {
660: eargs += 2; left -= 2;
661: } else {
662: PetscBool nextiskey = PETSC_FALSE;
663: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
664: if (left < 2 || nextiskey) {
665: PetscOptionsSetValue(options,eargs[0],NULL);
666: eargs++; left--;
667: } else {
668: PetscOptionsSetValue(options,eargs[0],eargs[1]);
669: eargs += 2; left -= 2;
670: }
671: }
672: }
673: return(0);
674: }
679: /*@C
680: PetscOptionsInsert - Inserts into the options database from the command line,
681: the environmental variable and a file.
683: Input Parameters:
684: + options - options database or NULL for the default global database
685: . argc - count of number of command line arguments
686: . args - the command line arguments
687: - file - optional filename, defaults to ~username/.petscrc
689: Note:
690: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
691: the user does not typically need to call this routine. PetscOptionsInsert()
692: can be called several times, adding additional entries into the database.
694: Options Database Keys:
695: + -options_monitor <optional filename> - print options names and values as they are set
696: . -options_file <filename> - read options from a file
698: Level: advanced
700: Concepts: options database^adding
702: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
703: PetscInitialize()
704: @*/
705: PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
706: {
708: PetscMPIInt rank;
709: char pfile[PETSC_MAX_PATH_LEN];
710: PetscBool flag = PETSC_FALSE;
712:
714: if (!options) {
715: if (!defaultoptions) {
716: PetscOptionsCreateDefault();
717: }
718: options = defaultoptions;
719: }
720: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
722: options->argc = (argc) ? *argc : 0;
723: options->args = (args) ? *args : NULL;
725: if (file && file[0]) {
726: char fullpath[PETSC_MAX_PATH_LEN];
728: PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
729: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
730: }
731: /*
732: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
733: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
734: */
735: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
736: PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
737: if (!flag) {
738: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
739: /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
740: if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
741: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
742: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
743: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
744: }
746: /* insert environmental options */
747: {
748: char *eoptions = 0;
749: size_t len = 0;
750: if (!rank) {
751: eoptions = (char*)getenv("PETSC_OPTIONS");
752: PetscStrlen(eoptions,&len);
753: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
754: } else {
755: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
756: if (len) {
757: PetscMalloc1(len+1,&eoptions);
758: }
759: }
760: if (len) {
761: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
762: if (rank) eoptions[len] = 0;
763: PetscOptionsInsertString(options,eoptions);
764: if (rank) {PetscFree(eoptions);}
765: }
766: }
768: #if defined(PETSC_HAVE_YAML)
769: char yaml_file[PETSC_MAX_PATH_LEN];
770: PetscBool yaml_flg = PETSC_FALSE;
771: PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
772: if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
773: #endif
775: /* insert command line options again because they take precedence over arguments in petscrc/environment */
776: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
777: return(0);
778: }
782: /*@C
783: PetscOptionsView - Prints the options that have been loaded. This is
784: useful for debugging purposes.
786: Logically Collective on PetscViewer
788: Input Parameter:
789: . viewer - must be an PETSCVIEWERASCII viewer
791: Options Database Key:
792: . -options_table - Activates PetscOptionsView() within PetscFinalize()
794: Level: advanced
796: Concepts: options database^printing
798: .seealso: PetscOptionsAllUsed()
799: @*/
800: PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer)
801: {
803: PetscInt i;
804: PetscBool isascii;
807: options = options ? options : defaultoptions;
808: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
809: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
810: if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");
812: if (options->N) {
813: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
814: } else {
815: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
816: }
817: for (i=0; i<options->N; i++) {
818: if (options->values[i]) {
819: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
820: } else {
821: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
822: }
823: }
824: if (options->N) {
825: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
826: }
827: return(0);
828: }
832: /*
833: Called by error handlers to print options used in run
834: */
835: PetscErrorCode PetscOptionsViewError(void)
836: {
837: PetscInt i;
838: PetscOptions options = defaultoptions;
841: if (options->N) {
842: (*PetscErrorPrintf)("PETSc Option Table entries:\n");
843: } else {
844: (*PetscErrorPrintf)("No PETSc Option Table entries\n");
845: }
846: for (i=0; i<options->N; i++) {
847: if (options->values[i]) {
848: (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
849: } else {
850: (*PetscErrorPrintf)("-%s\n",options->names[i]);
851: }
852: }
853: return(0);
854: }
858: /*@C
859: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
861: Not Collective
863: Input Paramter:
864: . options - the options database, use NULL for the default global database
866: Output Parameter:
867: . copts - pointer where string pointer is stored
869: Notes: the array and each entry in the array should be freed with PetscFree()
871: Level: advanced
873: Concepts: options database^listing
875: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
876: @*/
877: PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[])
878: {
880: PetscInt i;
881: size_t len = 1,lent = 0;
882: char *coptions = NULL;
885: options = options ? options : defaultoptions;
887: /* count the length of the required string */
888: for (i=0; i<options->N; i++) {
889: PetscStrlen(options->names[i],&lent);
890: len += 2 + lent;
891: if (options->values[i]) {
892: PetscStrlen(options->values[i],&lent);
893: len += 1 + lent;
894: }
895: }
896: PetscMalloc1(len,&coptions);
897: coptions[0] = 0;
898: for (i=0; i<options->N; i++) {
899: PetscStrcat(coptions,"-");
900: PetscStrcat(coptions,options->names[i]);
901: PetscStrcat(coptions," ");
902: if (options->values[i]) {
903: PetscStrcat(coptions,options->values[i]);
904: PetscStrcat(coptions," ");
905: }
906: }
907: *copts = coptions;
908: return(0);
909: }
913: /*@C
914: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
916: Not Collective, but prefix will only be applied on calling ranks
918: Input Parameter:
919: + options - options database, or NULL for the default global database
920: - prefix - The string to append to the existing prefix
922: Options Database Keys:
923: + -prefix_push <some_prefix_> - push the given prefix
924: - -prefix_pop - pop the last prefix
926: Notes:
927: It is common to use this in conjunction with -options_file as in
929: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
931: where the files no longer require all options to be prefixed with -system2_.
933: Level: advanced
935: .seealso: PetscOptionsPrefixPop()
936: @*/
937: PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
938: {
940: size_t n;
941: PetscInt start;
942: char buf[2048];
943: PetscBool key;
947: options = options ? options : defaultoptions;
948: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
949: buf[0] = '-';
950: PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
951: buf[sizeof(buf) - 1] = 0;
952: PetscOptionsValidKey(buf,&key);
953: 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);
955: if (!options) {
956: PetscOptionsInsert(NULL,0,0,0);
957: options = defaultoptions;
958: }
959: 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);
960: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
961: PetscStrlen(prefix,&n);
962: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
963: PetscMemcpy(options->prefix+start,prefix,n+1);
964: options->prefixstack[options->prefixind++] = start+n;
965: return(0);
966: }
970: /*@C
971: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
973: Not Collective, but prefix will only be popped on calling ranks
975: Input Parameters:
976: . options - options database, or NULL for the default global database
978: Level: advanced
980: .seealso: PetscOptionsPrefixPush()
981: @*/
982: PetscErrorCode PetscOptionsPrefixPop(PetscOptions options)
983: {
984: PetscInt offset;
987: options = options ? options : defaultoptions;
988: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
989: options->prefixind--;
990: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
991: options->prefix[offset] = 0;
992: return(0);
993: }
997: /*@C
998: PetscOptionsClear - Removes all options form the database leaving it empty.
1000: Input Parameters:
1001: . options - options database, use NULL for the default global database
1003: Level: developer
1005: .seealso: PetscOptionsInsert()
1006: @*/
1007: PetscErrorCode PetscOptionsClear(PetscOptions options)
1008: {
1009: PetscInt i;
1012: options = options ? options : defaultoptions;
1013: for (i=0; i<options->N; i++) {
1014: if (options->names[i]) free(options->names[i]);
1015: if (options->values[i]) free(options->values[i]);
1016: }
1017: for (i=0; i<options->Naliases; i++) {
1018: free(options->aliases1[i]);
1019: free(options->aliases2[i]);
1020: }
1021: options->prefix[0] = 0;
1022: options->prefixind = 0;
1023: options->N = 0;
1024: options->Naliases = 0;
1025: return(0);
1026: }
1030: /*@
1031: PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options
1033: Input Parameters:
1034: . obj - the PetscObject
1036: Level: developer
1038: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
1039: PCBJACOBI from all printing the same help messages to the screen
1041: .seealso: PetscOptionsInsert()
1042: @*/
1043: PetscErrorCode PetscObjectSetPrintedOptions(PetscObject obj)
1044: {
1046: obj->optionsprinted = PETSC_TRUE;
1047: return(0);
1048: }
1052: /*@
1053: PetscObjectInheritPrintedOptions - If the child object is not on the rank 0 process of the parent object and the child is sequential then the child gets it set.
1055: Input Parameters:
1056: + pobj - the parent object
1057: - obj - the PetscObject
1059: Level: developer
1061: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
1062: PCBJACOBI from all printing the same help messages to the screen
1064: This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap
1066: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1067: @*/
1068: PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1069: {
1071: PetscMPIInt prank,size;
1074: MPI_Comm_rank(pobj->comm,&prank);
1075: MPI_Comm_size(obj->comm,&size);
1076: if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
1077: return(0);
1078: }
1082: /*@
1083: PetscOptionsDestroy - Destroys an option database.
1085: Input Parameter:
1086: . options - the PetscOptions object
1088: Level: developer
1090: .seealso: PetscOptionsInsert()
1091: @*/
1092: PetscErrorCode PetscOptionsDestroy(PetscOptions *options)
1093: {
1097: PetscOptionsClear(*options);
1098: free(*options);
1099: *options = NULL;
1100: return(0);
1101: }
1105: PetscErrorCode PetscOptionsDestroyDefault(void)
1106: {
1109: PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1110: return 0;
1111: }
1116: /*@C
1117: PetscOptionsSetValue - Sets an option name-value pair in the options
1118: database, overriding whatever is already present.
1120: Not collective, but setting values on certain processors could cause problems
1121: for parallel objects looking for options.
1123: Input Parameters:
1124: + options - options database, use NULL for the default global database
1125: . name - name of option, this SHOULD have the - prepended
1126: - value - the option value (not used for all options)
1128: Level: intermediate
1130: Note:
1131: This function can be called BEFORE PetscInitialize()
1133: Only some options have values associated with them, such as
1134: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
1136: Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized
1138: Concepts: options database^adding option
1140: .seealso: PetscOptionsInsert()
1141: @*/
1142: PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1143: {
1144: size_t len;
1146: PetscInt N,n,i;
1147: char **names;
1148: char fullname[2048];
1149: const char *name = iname;
1150: int match;
1152: if (!options) {
1153: if (!defaultoptions) {
1154: PetscOptionsCreateDefault();
1155: if (ierr) return ierr;
1156: }
1157: options = defaultoptions;
1158: }
1160: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
1161: match = strcmp(name,"-h");
1162: if (!match) name = "-help";
1164: name++; /* skip starting hyphen */
1165: if (options->prefixind > 0) {
1166: strncpy(fullname,options->prefix,sizeof(fullname));
1167: strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1168: name = fullname;
1169: }
1171: /* check against aliases */
1172: N = options->Naliases;
1173: for (i=0; i<N; i++) {
1174: #if defined(PETSC_HAVE_STRCASECMP)
1175: match = strcasecmp(options->aliases1[i],name);
1176: #elif defined(PETSC_HAVE_STRICMP)
1177: match = stricmp(options->aliases1[i],name);
1178: #else
1179: Error
1180: #endif
1181: if (!match) {
1182: name = options->aliases2[i];
1183: break;
1184: }
1185: }
1187: N = options->N;
1188: n = N;
1189: names = options->names;
1191: for (i=0; i<N; i++) {
1192: #if defined(PETSC_HAVE_STRCASECMP)
1193: match = strcasecmp(names[i],name);
1194: #elif defined(PETSC_HAVE_STRICMP)
1195: match = stricmp(names[i],name);
1196: #else
1197: Error
1198: #endif
1199: if (!match) {
1200: if (options->values[i]) free(options->values[i]);
1201: len = value ? strlen(value) : 0;
1202: if (len) {
1203: options->values[i] = (char*)malloc((len+1)*sizeof(char));
1204: if (!options->values[i]) return PETSC_ERR_MEM;
1205: strcpy(options->values[i],value);
1206: } else options->values[i] = 0;
1207: return 0;
1208: } else if (strcmp(names[i],name) > 0) {
1209: n = i;
1210: break;
1211: }
1212: }
1213: if (N >= MAXOPTIONS) abort();
1215: /* shift remaining values down 1 */
1216: for (i=N; i>n; i--) {
1217: options->names[i] = options->names[i-1];
1218: options->values[i] = options->values[i-1];
1219: options->used[i] = options->used[i-1];
1220: }
1221: /* insert new name and value */
1222: len = strlen(name);
1223: options->names[n] = (char*)malloc((len+1)*sizeof(char));
1224: if (!options->names[n]) return PETSC_ERR_MEM;
1225: strcpy(options->names[n],name);
1226: len = value ? strlen(value) : 0;
1227: if (len) {
1228: options->values[n] = (char*)malloc((len+1)*sizeof(char));
1229: if (!options->values[n]) return PETSC_ERR_MEM;
1230: strcpy(options->values[n],value);
1231: } else options->values[n] = NULL;
1232: options->used[n] = PETSC_FALSE;
1233: options->N++;
1234: return 0;
1235: }
1239: /*@C
1240: PetscOptionsClearValue - Clears an option name-value pair in the options
1241: database, overriding whatever is already present.
1243: Not Collective, but setting values on certain processors could cause problems
1244: for parallel objects looking for options.
1246: Input Parameter:
1247: + options - options database, use NULL for the default global database
1248: . name - name of option, this SHOULD have the - prepended
1250: Level: intermediate
1252: Concepts: options database^removing option
1253: .seealso: PetscOptionsInsert()
1254: @*/
1255: PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char iname[])
1256: {
1258: PetscInt N,n,i;
1259: char **names,*name=(char*)iname;
1260: PetscBool gt,match;
1263: options = options ? options : defaultoptions;
1264: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1265: name++;
1267: N = options->N; n = 0;
1268: names = options->names;
1270: for (i=0; i<N; i++) {
1271: PetscStrcasecmp(names[i],name,&match);
1272: PetscStrgrt(names[i],name,>);
1273: if (match) {
1274: if (options->names[i]) free(options->names[i]);
1275: if (options->values[i]) free(options->values[i]);
1276: PetscOptionsMonitor(name,"");
1277: break;
1278: } else if (gt) return(0); /* it was not listed */
1280: n++;
1281: }
1282: if (n == N) return(0); /* it was not listed */
1284: /* shift remaining values down 1 */
1285: for (i=n; i<N-1; i++) {
1286: options->names[i] = options->names[i+1];
1287: options->values[i] = options->values[i+1];
1288: options->used[i] = options->used[i+1];
1289: }
1290: options->N--;
1291: return(0);
1292: }
1296: /*@C
1297: PetscOptionsSetAlias - Makes a key and alias for another key
1299: Not Collective, but setting values on certain processors could cause problems
1300: for parallel objects looking for options.
1302: Input Parameters:
1303: + options - options database or NULL for default global database
1304: . inewname - the alias
1305: - ioldname - the name that alias will refer to
1307: Level: advanced
1309: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1310: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1311: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1312: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1313: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1314: PetscOptionsFList(), PetscOptionsEList()
1315: @*/
1316: PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1317: {
1319: PetscInt n = options->Naliases;
1320: size_t len;
1321: char *newname = (char*)inewname,*oldname = (char*)ioldname;
1324: options = options ? options : defaultoptions;
1325: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1326: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1327: if (n >= MAXALIASES) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n src/sys/objects/options.c with larger value for MAXALIASES",MAXALIASES);
1329: newname++; oldname++;
1330: PetscStrlen(newname,&len);
1331: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1332: PetscStrcpy(options->aliases1[n],newname);
1333: PetscStrlen(oldname,&len);
1334: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1335: PetscStrcpy(options->aliases2[n],oldname);
1336: options->Naliases++;
1337: return(0);
1338: }
1342: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool *flg)
1343: {
1345: PetscInt i,N;
1346: size_t len;
1347: char **names,tmp[256];
1348: PetscBool match;
1351: options = options ? options : defaultoptions;
1352: N = options->N;
1353: names = options->names;
1355: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1357: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1358: if (pre) {
1359: char *ptr = tmp;
1360: const char *namep = name;
1361: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1362: if (name[1] == '-') {
1363: *ptr++ = '-';
1364: namep++;
1365: }
1366: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1367: tmp[sizeof(tmp)-1] = 0;
1368: PetscStrlen(tmp,&len);
1369: PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1370: } else {
1371: PetscStrncpy(tmp,name+1,sizeof(tmp));
1372: tmp[sizeof(tmp)-1] = 0;
1373: }
1374: #if defined(PETSC_USE_DEBUG)
1375: {
1376: PetscBool valid;
1377: char key[sizeof(tmp)+1] = "-";
1379: PetscMemcpy(key+1,tmp,sizeof(tmp));
1380: PetscOptionsValidKey(key,&valid);
1381: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1382: }
1383: #endif
1385: /* slow search */
1386: *flg = PETSC_FALSE;
1387: for (i=0; i<N; i++) {
1388: PetscStrcasecmp(names[i],tmp,&match);
1389: if (match) {
1390: *value = options->values[i];
1391: options->used[i] = PETSC_TRUE;
1392: *flg = PETSC_TRUE;
1393: break;
1394: }
1395: }
1396: if (!*flg) {
1397: PetscInt j,cnt = 0,locs[16],loce[16];
1398: size_t n;
1399: PetscStrlen(tmp,&n);
1400: /* determine the location and number of all _%d_ in the key */
1401: for (i=0; i< (PetscInt)n; i++) {
1402: if (tmp[i] == '_') {
1403: for (j=i+1; j< (PetscInt)n; j++) {
1404: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1405: if (tmp[j] == '_' && j > i+1) { /* found a number */
1406: locs[cnt] = i+1;
1407: loce[cnt++] = j+1;
1408: }
1409: break;
1410: }
1411: }
1412: }
1413: if (cnt) {
1414: char tmp2[256];
1415: for (i=0; i<cnt; i++) {
1416: PetscStrcpy(tmp2,"-");
1417: PetscStrncat(tmp2,tmp,locs[i]);
1418: PetscStrcat(tmp2,tmp+loce[i]);
1419: PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
1420: if (*flg) break;
1421: }
1422: }
1423: }
1424: return(0);
1425: }
1429: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
1430: {
1432: PetscInt i,N;
1433: size_t len;
1434: char **names,tmp[256];
1435: PetscBool match;
1438: options = options ? options : defaultoptions;
1439: N = options->N;
1440: names = options->names;
1442: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1444: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1445: if (pre) {
1446: char *ptr = tmp;
1447: const char *namep = name;
1448: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1449: if (name[1] == '-') {
1450: *ptr++ = '-';
1451: namep++;
1452: }
1453: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1454: tmp[sizeof(tmp)-1] = 0;
1455: PetscStrlen(tmp,&len);
1456: PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1457: } else {
1458: PetscStrncpy(tmp,name+1,sizeof(tmp));
1459: tmp[sizeof(tmp)-1] = 0;
1460: }
1461: #if defined(PETSC_USE_DEBUG)
1462: {
1463: PetscBool valid;
1464: char key[sizeof(tmp)+1] = "-";
1466: PetscMemcpy(key+1,tmp,sizeof(tmp));
1467: PetscOptionsValidKey(key,&valid);
1468: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1469: }
1470: #endif
1472: /* slow search */
1473: *flg = PETSC_FALSE;
1474: PetscStrlen(tmp,&len);
1475: for (i = 0; i < N; ++i) {
1476: PetscStrncmp(names[i], tmp, len, &match);
1477: if (match) {
1478: if (value) *value = options->values[i];
1479: options->used[i] = PETSC_TRUE;
1480: if (flg) *flg = PETSC_TRUE;
1481: break;
1482: }
1483: }
1484: return(0);
1485: }
1489: /*@C
1490: PetscOptionsReject - Generates an error if a certain option is given.
1492: Not Collective, but setting values on certain processors could cause problems
1493: for parallel objects looking for options.
1495: Input Parameters:
1496: + options - options database use NULL for default global database
1497: . name - the option one is seeking
1498: - mess - error message (may be NULL)
1500: Level: advanced
1502: Concepts: options database^rejecting option
1504: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1505: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1506: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1507: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1508: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1509: PetscOptionsFList(), PetscOptionsEList()
1510: @*/
1511: PetscErrorCode PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
1512: {
1514: PetscBool flag = PETSC_FALSE;
1517: options = options ? options : defaultoptions;
1518: PetscOptionsHasName(options,NULL,name,&flag);
1519: if (flag) {
1520: if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1521: else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1522: }
1523: return(0);
1524: }
1528: /*@C
1529: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1530: its value is set to false.
1532: Not Collective
1534: Input Parameters:
1535: + options - options database use NULL for default global database
1536: . name - the option one is seeking
1537: - pre - string to prepend to the name or NULL
1539: Output Parameters:
1540: . set - PETSC_TRUE if found else PETSC_FALSE.
1542: Level: beginner
1544: Concepts: options database^has option name
1546: Notes: Name cannot be simply -h
1548: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1550: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1551: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1552: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1553: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1554: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1555: PetscOptionsFList(), PetscOptionsEList()
1556: @*/
1557: PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set)
1558: {
1559: char *value;
1561: PetscBool flag;
1564: options = options ? options : defaultoptions;
1565: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1566: if (set) *set = flag;
1567: return(0);
1568: }
1572: /*@C
1573: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1575: Not Collective
1577: Input Parameters:
1578: + options - options database use NULL for default global database
1579: . pre - the string to prepend to the name or NULL
1580: - name - the option one is seeking
1582: Output Parameter:
1583: + ivalue - the integer value to return
1584: - set - PETSC_TRUE if found, else PETSC_FALSE
1586: Level: beginner
1588: Concepts: options database^has int
1590: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1591: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1592: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1593: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1594: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1595: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1596: PetscOptionsFList(), PetscOptionsEList()
1597: @*/
1598: PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1599: {
1600: char *value;
1602: PetscBool flag;
1607: options = options ? options : defaultoptions;
1608: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1609: if (flag) {
1610: if (!value) {
1611: if (set) *set = PETSC_FALSE;
1612: } else {
1613: if (set) *set = PETSC_TRUE;
1614: PetscOptionsStringToInt(value,ivalue);
1615: }
1616: } else {
1617: if (set) *set = PETSC_FALSE;
1618: }
1619: return(0);
1620: }
1624: /*@C
1625: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1627: Not Collective
1629: Input Parameters:
1630: + options - options database use NULL for default global database
1631: . pre - the string to prepend to the name or NULL
1632: . opt - option name
1633: . list - the possible choices (one of these must be selected, anything else is invalid)
1634: . ntext - number of choices
1636: Output Parameter:
1637: + value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1638: - set - PETSC_TRUE if found, else PETSC_FALSE
1640: Level: intermediate
1642: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1644: Concepts: options database^list
1646: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1647: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1648: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1649: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1650: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1651: PetscOptionsFList(), PetscOptionsEList()
1652: @*/
1653: PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set)
1654: {
1656: size_t alen,len = 0;
1657: char *svalue;
1658: PetscBool aset,flg = PETSC_FALSE;
1659: PetscInt i;
1662: options = options ? options : defaultoptions;
1663: for (i=0; i<ntext; i++) {
1664: PetscStrlen(list[i],&alen);
1665: if (alen > len) len = alen;
1666: }
1667: len += 5; /* a little extra space for user mistypes */
1668: PetscMalloc1(len,&svalue);
1669: PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
1670: if (aset) {
1671: PetscEListFind(ntext,list,svalue,value,&flg);
1672: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1673: if (set) *set = PETSC_TRUE;
1674: } else if (set) *set = PETSC_FALSE;
1675: PetscFree(svalue);
1676: return(0);
1677: }
1681: /*@C
1682: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1684: Not Collective
1686: Input Parameters:
1687: + options - options database use NULL for default global database
1688: . pre - option prefix or NULL
1689: . opt - option name
1690: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1691: - defaultv - the default (current) value
1693: Output Parameter:
1694: + value - the value to return
1695: - set - PETSC_TRUE if found, else PETSC_FALSE
1697: Level: beginner
1699: Concepts: options database
1701: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1703: list is usually something like PCASMTypes or some other predefined list of enum names
1705: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1706: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1707: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1708: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1709: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1710: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1711: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1712: @*/
1713: PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set)
1714: {
1716: PetscInt ntext = 0,tval;
1717: PetscBool fset;
1720: options = options ? options : defaultoptions;
1721: while (list[ntext++]) {
1722: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1723: }
1724: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1725: ntext -= 3;
1726: PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
1727: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1728: if (fset) *value = (PetscEnum)tval;
1729: if (set) *set = fset;
1730: return(0);
1731: }
1735: /*@C
1736: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1737: option in the database.
1739: Not Collective
1741: Input Parameters:
1742: + options - options database use NULL for default global database
1743: . pre - the string to prepend to the name or NULL
1744: - name - the option one is seeking
1746: Output Parameter:
1747: + ivalue - the logical value to return
1748: - set - PETSC_TRUE if found, else PETSC_FALSE
1750: Level: beginner
1752: Notes:
1753: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1754: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1756: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1757: you NEED TO ALWAYS initialize the ivalue.
1759: Concepts: options database^has logical
1761: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1762: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1763: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1764: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1765: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1766: PetscOptionsFList(), PetscOptionsEList()
1767: @*/
1768: PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1769: {
1770: char *value;
1771: PetscBool flag;
1777: options = options ? options : defaultoptions;
1778: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1779: if (flag) {
1780: if (set) *set = PETSC_TRUE;
1781: if (!value) {
1782: if (ivalue) *ivalue = PETSC_TRUE;
1783: } else {
1784: PetscOptionsStringToBool(value, ivalue);
1785: }
1786: } else {
1787: if (set) *set = PETSC_FALSE;
1788: }
1789: return(0);
1790: }
1794: /*@C
1795: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1796: option in the database. The values must be separated with commas with
1797: no intervening spaces.
1799: Not Collective
1801: Input Parameters:
1802: + options - options database use NULL for default global database
1803: . pre - string to prepend to each name or NULL
1804: . name - the option one is seeking
1805: - nmax - maximum number of values to retrieve
1807: Output Parameter:
1808: + dvalue - the integer values to return
1809: . nmax - actual number of values retreived
1810: - set - PETSC_TRUE if found, else PETSC_FALSE
1812: Level: beginner
1814: Concepts: options database^array of ints
1816: Notes:
1817: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1818: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1820: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1821: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1822: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1823: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1824: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1825: PetscOptionsFList(), PetscOptionsEList()
1826: @*/
1827: PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1828: {
1829: char *value;
1831: PetscInt n = 0;
1832: PetscBool flag;
1833: PetscToken token;
1838: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1839: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1840: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1842: if (set) *set = PETSC_TRUE;
1844: PetscTokenCreate(value,',',&token);
1845: PetscTokenFind(token,&value);
1846: while (n < *nmax) {
1847: if (!value) break;
1848: PetscOptionsStringToBool(value,dvalue);
1849: PetscTokenFind(token,&value);
1850: dvalue++;
1851: n++;
1852: }
1853: PetscTokenDestroy(&token);
1854: *nmax = n;
1855: return(0);
1856: }
1860: /*@C
1861: PetscOptionsGetReal - Gets the double precision value for a particular
1862: option in the database.
1864: Not Collective
1866: Input Parameters:
1867: + options - options database use NULL for default global database
1868: . pre - string to prepend to each name or NULL
1869: - name - the option one is seeking
1871: Output Parameter:
1872: + dvalue - the double value to return
1873: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1875: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1877: Level: beginner
1879: Concepts: options database^has double
1881: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1882: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1883: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1884: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1885: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1886: PetscOptionsFList(), PetscOptionsEList()
1887: @*/
1888: PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1889: {
1890: char *value;
1892: PetscBool flag;
1897: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1898: if (flag) {
1899: if (!value) {
1900: if (set) *set = PETSC_FALSE;
1901: } else {
1902: if (set) *set = PETSC_TRUE;
1903: PetscOptionsStringToReal(value,dvalue);
1904: }
1905: } else {
1906: if (set) *set = PETSC_FALSE;
1907: }
1908: return(0);
1909: }
1913: /*@C
1914: PetscOptionsGetScalar - Gets the scalar value for a particular
1915: option in the database.
1917: Not Collective
1919: Input Parameters:
1920: + options - options database use NULL for default global database
1921: . pre - string to prepend to each name or NULL
1922: - name - the option one is seeking
1924: Output Parameter:
1925: + dvalue - the double value to return
1926: - set - PETSC_TRUE if found, else PETSC_FALSE
1928: Level: beginner
1930: Usage:
1931: A complex number 2+3i must be specified with NO spaces
1933: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1935: Concepts: options database^has scalar
1937: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1938: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1939: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1940: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1941: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1942: PetscOptionsFList(), PetscOptionsEList()
1943: @*/
1944: PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1945: {
1946: char *value;
1947: PetscBool flag;
1953: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1954: if (flag) {
1955: if (!value) {
1956: if (set) *set = PETSC_FALSE;
1957: } else {
1958: #if !defined(PETSC_USE_COMPLEX)
1959: PetscOptionsStringToReal(value,dvalue);
1960: #else
1961: PetscOptionsStringToScalar(value,dvalue);
1962: #endif
1963: if (set) *set = PETSC_TRUE;
1964: }
1965: } else { /* flag */
1966: if (set) *set = PETSC_FALSE;
1967: }
1968: return(0);
1969: }
1973: /*@C
1974: PetscOptionsGetRealArray - Gets an array of double precision values for a
1975: particular option in the database. The values must be separated with
1976: commas with no intervening spaces.
1978: Not Collective
1980: Input Parameters:
1981: + options - options database use NULL for default global database
1982: . pre - string to prepend to each name or NULL
1983: . name - the option one is seeking
1984: - nmax - maximum number of values to retrieve
1986: Output Parameters:
1987: + dvalue - the double values to return
1988: . nmax - actual number of values retreived
1989: - set - PETSC_TRUE if found, else PETSC_FALSE
1991: Level: beginner
1993: Concepts: options database^array of doubles
1995: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1996: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1997: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1998: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1999: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2000: PetscOptionsFList(), PetscOptionsEList()
2001: @*/
2002: PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
2003: {
2004: char *value;
2006: PetscInt n = 0;
2007: PetscBool flag;
2008: PetscToken token;
2013: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2014: if (!flag) {
2015: if (set) *set = PETSC_FALSE;
2016: *nmax = 0;
2017: return(0);
2018: }
2019: if (!value) {
2020: if (set) *set = PETSC_TRUE;
2021: *nmax = 0;
2022: return(0);
2023: }
2025: if (set) *set = PETSC_TRUE;
2027: PetscTokenCreate(value,',',&token);
2028: PetscTokenFind(token,&value);
2029: while (n < *nmax) {
2030: if (!value) break;
2031: PetscOptionsStringToReal(value,dvalue++);
2032: PetscTokenFind(token,&value);
2033: n++;
2034: }
2035: PetscTokenDestroy(&token);
2036: *nmax = n;
2037: return(0);
2038: }
2042: /*@C
2043: PetscOptionsGetScalarArray - Gets an array of scalars for a
2044: particular option in the database. The values must be separated with
2045: commas with no intervening spaces.
2047: Not Collective
2049: Input Parameters:
2050: + options - options database use NULL for default global database
2051: . pre - string to prepend to each name or NULL
2052: . name - the option one is seeking
2053: - nmax - maximum number of values to retrieve
2055: Output Parameters:
2056: + dvalue - the scalar values to return
2057: . nmax - actual number of values retreived
2058: - set - PETSC_TRUE if found, else PETSC_FALSE
2060: Level: beginner
2062: Concepts: options database^array of doubles
2064: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2065: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2066: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2067: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2068: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2069: PetscOptionsFList(), PetscOptionsEList()
2070: @*/
2071: PetscErrorCode PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool *set)
2072: {
2073: char *value;
2075: PetscInt n = 0;
2076: PetscBool flag;
2077: PetscToken token;
2082: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2083: if (!flag) {
2084: if (set) *set = PETSC_FALSE;
2085: *nmax = 0;
2086: return(0);
2087: }
2088: if (!value) {
2089: if (set) *set = PETSC_TRUE;
2090: *nmax = 0;
2091: return(0);
2092: }
2094: if (set) *set = PETSC_TRUE;
2096: PetscTokenCreate(value,',',&token);
2097: PetscTokenFind(token,&value);
2098: while (n < *nmax) {
2099: if (!value) break;
2100: PetscOptionsStringToScalar(value,dvalue++);
2101: PetscTokenFind(token,&value);
2102: n++;
2103: }
2104: PetscTokenDestroy(&token);
2105: *nmax = n;
2106: return(0);
2107: }
2111: /*@C
2112: PetscOptionsGetIntArray - Gets an array of integer values for a particular
2113: option in the database.
2115: Not Collective
2117: Input Parameters:
2118: + options - options database use NULL for default global database
2119: . pre - string to prepend to each name or NULL
2120: . name - the option one is seeking
2121: - nmax - maximum number of values to retrieve
2123: Output Parameter:
2124: + dvalue - the integer values to return
2125: . nmax - actual number of values retreived
2126: - set - PETSC_TRUE if found, else PETSC_FALSE
2128: Level: beginner
2130: Notes:
2131: The array can be passed as
2132: a comma separated list: 0,1,2,3,4,5,6,7
2133: a range (start-end+1): 0-8
2134: a range with given increment (start-end+1:inc): 0-7:2
2135: a combination of values and ranges separated by commas: 0,1-8,8-15:2
2137: There must be no intervening spaces between the values.
2139: Concepts: options database^array of ints
2141: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2142: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2143: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2144: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2145: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2146: PetscOptionsFList(), PetscOptionsEList()
2147: @*/
2148: PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
2149: {
2150: char *value;
2152: PetscInt n = 0,i,j,start,end,inc,nvalues;
2153: size_t len;
2154: PetscBool flag,foundrange;
2155: PetscToken token;
2160: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2161: if (!flag) {
2162: if (set) *set = PETSC_FALSE;
2163: *nmax = 0;
2164: return(0);
2165: }
2166: if (!value) {
2167: if (set) *set = PETSC_TRUE;
2168: *nmax = 0;
2169: return(0);
2170: }
2172: if (set) *set = PETSC_TRUE;
2174: PetscTokenCreate(value,',',&token);
2175: PetscTokenFind(token,&value);
2176: while (n < *nmax) {
2177: if (!value) break;
2179: /* look for form d-D where d and D are integers */
2180: foundrange = PETSC_FALSE;
2181: PetscStrlen(value,&len);
2182: if (value[0] == '-') i=2;
2183: else i=1;
2184: for (;i<(int)len; i++) {
2185: if (value[i] == '-') {
2186: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2187: value[i] = 0;
2189: PetscOptionsStringToInt(value,&start);
2190: inc = 1;
2191: j = i+1;
2192: for (;j<(int)len; j++) {
2193: if (value[j] == ':') {
2194: value[j] = 0;
2196: PetscOptionsStringToInt(value+j+1,&inc);
2197: 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);
2198: break;
2199: }
2200: }
2201: PetscOptionsStringToInt(value+i+1,&end);
2202: 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);
2203: nvalues = (end-start)/inc + (end-start)%inc;
2204: 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);
2205: for (;start<end; start+=inc) {
2206: *dvalue = start; dvalue++;n++;
2207: }
2208: foundrange = PETSC_TRUE;
2209: break;
2210: }
2211: }
2212: if (!foundrange) {
2213: PetscOptionsStringToInt(value,dvalue);
2214: dvalue++;
2215: n++;
2216: }
2217: PetscTokenFind(token,&value);
2218: }
2219: PetscTokenDestroy(&token);
2220: *nmax = n;
2221: return(0);
2222: }
2226: /*@C
2227: PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.
2229: Not Collective
2231: Input Parameters:
2232: + options - options database use NULL for default global database
2233: . pre - option prefix or NULL
2234: . name - option name
2235: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2236: - nmax - maximum number of values to retrieve
2238: Output Parameters:
2239: + dvalue - the enum values to return
2240: . nmax - actual number of values retreived
2241: - set - PETSC_TRUE if found, else PETSC_FALSE
2243: Level: beginner
2245: Concepts: options database
2247: Notes:
2248: The array must be passed as a comma separated list.
2250: There must be no intervening spaces between the values.
2252: list is usually something like PCASMTypes or some other predefined list of enum names.
2254: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2255: PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2256: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2257: PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2258: PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2259: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2260: @*/
2261: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2262: {
2263: char *svalue;
2264: PetscInt n = 0;
2265: PetscEnum evalue;
2266: PetscBool flag;
2267: PetscToken token;
2276: PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2277: if (!flag) {
2278: if (set) *set = PETSC_FALSE;
2279: *nmax = 0;
2280: return(0);
2281: }
2282: if (!svalue) {
2283: if (set) *set = PETSC_TRUE;
2284: *nmax = 0;
2285: return(0);
2286: }
2287: if (set) *set = PETSC_TRUE;
2289: PetscTokenCreate(svalue,',',&token);
2290: PetscTokenFind(token,&svalue);
2291: while (svalue && n < *nmax) {
2292: PetscEnumFind(list,svalue,&evalue,&flag);
2293: if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2294: dvalue[n++] = evalue;
2295: PetscTokenFind(token,&svalue);
2296: }
2297: *nmax = n;
2298: PetscTokenDestroy(&token);
2299: return(0);
2300: }
2304: /*@C
2305: PetscOptionsGetString - Gets the string value for a particular option in
2306: the database.
2308: Not Collective
2310: Input Parameters:
2311: + options - options database use NULL for default global database
2312: . pre - string to prepend to name or NULL
2313: . name - the option one is seeking
2314: - len - maximum length of the string including null termination
2316: Output Parameters:
2317: + string - location to copy string
2318: - set - PETSC_TRUE if found, else PETSC_FALSE
2320: Level: beginner
2322: Fortran Note:
2323: The Fortran interface is slightly different from the C/C++
2324: interface (len is not used). Sample usage in Fortran follows
2325: .vb
2326: character *20 string
2327: integer flg, ierr
2328: call PetscOptionsGetString(PETSC_NULL_OBJECT,PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
2329: .ve
2331: 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
2333: Concepts: options database^string
2335: Note:
2336: 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).
2338: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2339: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2340: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2341: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2342: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2343: PetscOptionsFList(), PetscOptionsEList()
2344: @*/
2345: PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set)
2346: {
2347: char *value;
2349: PetscBool flag;
2354: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2355: if (!flag) {
2356: if (set) *set = PETSC_FALSE;
2357: } else {
2358: if (set) *set = PETSC_TRUE;
2359: if (value) {
2360: PetscStrncpy(string,value,len);
2361: string[len-1] = 0; /* Ensure that the string is NULL terminated */
2362: } else {
2363: PetscMemzero(string,len);
2364: }
2365: }
2366: return(0);
2367: }
2371: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2372: {
2373: char *value;
2375: PetscBool flag;
2378: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2379: if (flag) PetscFunctionReturn(value);
2380: else return(0);
2381: }
2386: /*@C
2387: PetscOptionsGetStringArray - Gets an array of string values for a particular
2388: option in the database. The values must be separated with commas with
2389: no intervening spaces.
2391: Not Collective
2393: Input Parameters:
2394: + options - options database use NULL for default global database
2395: . pre - string to prepend to name or NULL
2396: . name - the option one is seeking
2397: - nmax - maximum number of strings
2399: Output Parameter:
2400: + strings - location to copy strings
2401: - set - PETSC_TRUE if found, else PETSC_FALSE
2403: Level: beginner
2405: Notes:
2406: The user should pass in an array of pointers to char, to hold all the
2407: strings returned by this function.
2409: The user is responsible for deallocating the strings that are
2410: returned. The Fortran interface for this routine is not supported.
2412: Contributed by Matthew Knepley.
2414: Concepts: options database^array of strings
2416: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2417: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2418: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2419: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2420: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2421: PetscOptionsFList(), PetscOptionsEList()
2422: @*/
2423: PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
2424: {
2425: char *value;
2427: PetscInt n;
2428: PetscBool flag;
2429: PetscToken token;
2434: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2435: if (!flag) {
2436: *nmax = 0;
2437: if (set) *set = PETSC_FALSE;
2438: return(0);
2439: }
2440: if (!value) {
2441: *nmax = 0;
2442: if (set) *set = PETSC_FALSE;
2443: return(0);
2444: }
2445: if (!*nmax) {
2446: if (set) *set = PETSC_FALSE;
2447: return(0);
2448: }
2449: if (set) *set = PETSC_TRUE;
2451: PetscTokenCreate(value,',',&token);
2452: PetscTokenFind(token,&value);
2453: n = 0;
2454: while (n < *nmax) {
2455: if (!value) break;
2456: PetscStrallocpy(value,&strings[n]);
2457: PetscTokenFind(token,&value);
2458: n++;
2459: }
2460: PetscTokenDestroy(&token);
2461: *nmax = n;
2462: return(0);
2463: }
2467: /*@C
2468: PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database
2470: Not Collective
2472: Input Parameter:
2473: + options - options database use NULL for default global database
2474: - option - string name of option
2476: Output Parameter:
2477: . used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database
2479: Level: advanced
2481: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2482: @*/
2483: PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2484: {
2485: PetscInt i;
2489: options = options ? options : defaultoptions;
2490: *used = PETSC_FALSE;
2491: for (i=0; i<options->N; i++) {
2492: PetscStrcmp(options->names[i],option,used);
2493: if (*used) {
2494: *used = options->used[i];
2495: break;
2496: }
2497: }
2498: return(0);
2499: }
2503: /*@C
2504: PetscOptionsAllUsed - Returns a count of the number of options in the
2505: database that have never been selected.
2507: Not Collective
2509: Input Parameter:
2510: . options - options database use NULL for default global database
2512: Output Parameter:
2513: . N - count of options not used
2515: Level: advanced
2517: .seealso: PetscOptionsView()
2518: @*/
2519: PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2520: {
2521: PetscInt i,n = 0;
2524: options = options ? options : defaultoptions;
2525: for (i=0; i<options->N; i++) {
2526: if (!options->used[i]) n++;
2527: }
2528: *N = n;
2529: return(0);
2530: }
2534: /*@C
2535: PetscOptionsLeft - Prints to screen any options that were set and never used.
2537: Not collective
2539: Input Parameter:
2540: . options - options database use NULL for default global database
2542: Options Database Key:
2543: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
2545: Level: advanced
2547: .seealso: PetscOptionsAllUsed()
2548: @*/
2549: PetscErrorCode PetscOptionsLeft(PetscOptions options)
2550: {
2552: PetscInt i;
2555: options = options ? options : defaultoptions;
2556: for (i=0; i<options->N; i++) {
2557: if (!options->used[i]) {
2558: if (options->values[i]) {
2559: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2560: } else {
2561: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2562: }
2563: }
2564: }
2565: return(0);
2566: }
2570: /*@
2571: PetscOptionsCreate - Creates the empty options database.
2573: Output Parameter:
2574: . options - Options database object
2576: Level: advanced
2578: @*/
2579: PetscErrorCode PetscOptionsCreate(PetscOptions *options)
2580: {
2581: *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2582: if (!options) return PETSC_ERR_MEM;
2583: (*options)->namegiven = PETSC_FALSE;
2584: (*options)->N = 0;
2585: (*options)->Naliases = 0;
2586: (*options)->numbermonitors = 0;
2587: return 0;
2588: }
2592: /*
2593: PetscOptionsCreateDefault - Creates the default global options database
2595: */
2596: PetscErrorCode PetscOptionsCreateDefault(void)
2597: {
2600: if (!defaultoptions) {
2601: PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2602: }
2603: return 0;
2604: }
2608: /*@C
2609: PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc
2611: Collective on PETSC_COMM_WORLD
2613: Input Parameter:
2614: . options - options database use NULL for default global database
2616: Options Database Keys:
2617: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2618: available for options set through a file, environment variable, or on
2619: the command line. Only options set after PetscInitialize() completes will
2620: be monitored.
2621: . -options_monitor_cancel - cancel all options database monitors
2623: Notes:
2624: To see all options, run your program with the -help option or consult Users-Manual: Introduction
2626: Level: intermediate
2628: .keywords: set, options, database
2629: @*/
2630: PetscErrorCode PetscOptionsSetFromOptions(PetscOptions options)
2631: {
2632: PetscBool flgc = PETSC_FALSE,flgm;
2634: char monfilename[PETSC_MAX_PATH_LEN];
2635: PetscViewer monviewer;
2638: /*
2639: The options argument is currently ignored since we currently maintain only a single options database
2641: options = options ? options : defaultoptions;
2642: */
2643: PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2644: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2645: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2646: PetscOptionsEnd();
2647: if (flgm) {
2648: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2649: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2650: }
2651: if (flgc) { PetscOptionsMonitorCancel(); }
2652: return(0);
2653: }
2658: /*@C
2659: PetscOptionsMonitorDefault - Print all options set value events.
2661: Logically Collective on PETSC_COMM_WORLD
2663: Input Parameters:
2664: + name - option name string
2665: . value - option value string
2666: - dummy - an ASCII viewer
2668: Level: intermediate
2670: .keywords: PetscOptions, default, monitor
2672: .seealso: PetscOptionsMonitorSet()
2673: @*/
2674: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2675: {
2677: PetscViewer viewer = (PetscViewer) dummy;
2680: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2681: return(0);
2682: }
2686: /*@C
2687: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2688: modified the PETSc options database.
2690: Not collective
2692: Input Parameters:
2693: + monitor - pointer to function (if this is NULL, it turns off monitoring
2694: . mctx - [optional] context for private data for the
2695: monitor routine (use NULL if no context is desired)
2696: - monitordestroy - [optional] routine that frees monitor context
2697: (may be NULL)
2699: Calling Sequence of monitor:
2700: $ monitor (const char name[], const char value[], void *mctx)
2702: + name - option name string
2703: . value - option value string
2704: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2706: Options Database Keys:
2707: + -options_monitor - sets PetscOptionsMonitorDefault()
2708: - -options_monitor_cancel - cancels all monitors that have
2709: been hardwired into a code by
2710: calls to PetscOptionsMonitorSet(), but
2711: does not cancel those set via
2712: the options database.
2714: Notes:
2715: The default is to do nothing. To print the name and value of options
2716: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2717: with a null monitoring context.
2719: Several different monitoring routines may be set by calling
2720: PetscOptionsMonitorSet() multiple times; all will be called in the
2721: order in which they were set.
2723: Level: beginner
2725: .keywords: PetscOptions, set, monitor
2727: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2728: @*/
2729: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2730: {
2731: PetscOptions options = defaultoptions;
2734: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2735: options->monitor[options->numbermonitors] = monitor;
2736: options->monitordestroy[options->numbermonitors] = monitordestroy;
2737: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2738: return(0);
2739: }
2743: /*@
2744: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2746: Not collective
2748: Options Database Key:
2749: . -options_monitor_cancel - Cancels all monitors that have
2750: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2751: but does not cancel those set via the options database.
2753: Level: intermediate
2755: .keywords: PetscOptions, set, monitor
2757: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2758: @*/
2759: PetscErrorCode PetscOptionsMonitorCancel(void)
2760: {
2762: PetscInt i;
2763: PetscOptions options = defaultoptions;
2766: for (i=0; i<options->numbermonitors; i++) {
2767: if (options->monitordestroy[i]) {
2768: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2769: }
2770: }
2771: options->numbermonitors = 0;
2772: return(0);
2773: }
2775: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }
2779: /*@C
2780: PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed.
2782: Collective on PetscObject
2784: Input Parameters:
2785: + obj - the object
2786: . bobj - optional other object that provides prefix (if NULL then the prefix in obj is used)
2787: - optionname - option to activate viewing
2789: Level: intermediate
2791: @*/
2792: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2793: {
2794: PetscErrorCode ierr;
2795: PetscViewer viewer;
2796: PetscBool flg;
2797: static PetscBool incall = PETSC_FALSE;
2798: PetscViewerFormat format;
2799: char *prefix;
2802: if (incall) return(0);
2803: incall = PETSC_TRUE;
2804: prefix = bobj ? bobj->prefix : obj->prefix;
2805: PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2806: if (flg) {
2807: PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2808: PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2809: PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2810: PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2811: }
2812: incall = PETSC_FALSE;
2813: return(0);
2814: }