Actual source code: options.c
petsc-3.7.5 2017-01-01
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];
482: options = options ? options : defaultoptions;
483: MPI_Comm_rank(comm,&rank);
484: if (!rank) {
485: cnt = 0;
486: acnt = 0;
488: PetscFixFilename(file,fname);
489: fd = fopen(fname,"r");
490: if (fd) {
491: PetscSegBuffer vseg,aseg;
492: PetscSegBufferCreate(1,4000,&vseg);
493: PetscSegBufferCreate(1,2000,&aseg);
495: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
496: PetscInfo1(0,"Opened options file %s\n",file);
498: while ((string = Petscgetline(fd))) {
499: /* eliminate comments from each line */
500: for (i=0; i<1; i++) {
501: PetscStrchr(string,cmt[i],&cmatch);
502: if (cmatch) *cmatch = 0;
503: }
504: PetscStrlen(string,&len);
505: /* replace tabs, ^M, \n with " " */
506: for (i=0; i<len; i++) {
507: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
508: string[i] = ' ';
509: }
510: }
511: PetscTokenCreate(string,' ',&token);
512: PetscTokenFind(token,&first);
513: if (!first) {
514: goto destroy;
515: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
516: PetscTokenFind(token,&first);
517: }
518: PetscTokenFind(token,&second);
519: if (!first) {
520: goto destroy;
521: } else if (first[0] == '-') {
522: PetscStrlen(first,&len);
523: PetscSegBufferGet(vseg,len+1,&vstring);
524: PetscMemcpy(vstring,first,len);
525: vstring[len] = ' ';
526: if (second) {
527: PetscStrlen(second,&len);
528: PetscSegBufferGet(vseg,len+3,&vstring);
529: vstring[0] = '"';
530: PetscMemcpy(vstring+1,second,len);
531: vstring[len+1] = '"';
532: vstring[len+2] = ' ';
533: }
534: } else {
535: PetscBool match;
537: PetscStrcasecmp(first,"alias",&match);
538: if (match) {
539: PetscTokenFind(token,&third);
540: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
541: PetscStrlen(second,&len);
542: PetscSegBufferGet(aseg,len+1,&astring);
543: PetscMemcpy(astring,second,len);
544: astring[len] = ' ';
546: PetscStrlen(third,&len);
547: PetscSegBufferGet(aseg,len+1,&astring);
548: PetscMemcpy(astring,third,len);
549: astring[len] = ' ';
550: } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
551: }
552: destroy:
553: free(string);
554: PetscTokenDestroy(&token);
555: }
556: err = fclose(fd);
557: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
558: PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
559: PetscMPIIntCast(bytes,&acnt);
560: PetscSegBufferGet(aseg,1,&astring);
561: astring[0] = 0;
562: PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
563: PetscMPIIntCast(bytes,&cnt);
564: PetscSegBufferGet(vseg,1,&vstring);
565: vstring[0] = 0;
566: PetscMalloc1(2+acnt+cnt,&packed);
567: PetscSegBufferExtractTo(aseg,packed);
568: PetscSegBufferExtractTo(vseg,packed+acnt+1);
569: PetscSegBufferDestroy(&aseg);
570: PetscSegBufferDestroy(&vseg);
571: } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
572: }
574: counts[0] = acnt;
575: counts[1] = cnt;
576: MPI_Bcast(counts,2,MPI_INT,0,comm);
577: acnt = counts[0];
578: cnt = counts[1];
579: if (rank) {
580: PetscMalloc1(2+acnt+cnt,&packed);
581: }
582: if (acnt || cnt) {
583: MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
584: astring = packed;
585: vstring = packed + acnt + 1;
586: }
588: if (acnt) {
589: PetscToken token;
590: char *first,*second;
592: PetscTokenCreate(astring,' ',&token);
593: PetscTokenFind(token,&first);
594: while (first) {
595: PetscTokenFind(token,&second);
596: PetscOptionsSetAlias(options,first,second);
597: PetscTokenFind(token,&first);
598: }
599: PetscTokenDestroy(&token);
600: }
602: if (cnt) {
603: PetscOptionsInsertString(options,vstring);
604: }
605: PetscFree(packed);
606: return(0);
607: }
611: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
612: {
614: int left = argc - 1;
615: char **eargs = args + 1;
618: options = options ? options : defaultoptions;
619: while (left) {
620: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
621: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
622: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
623: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
624: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
625: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
626: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
627: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
628: isp4 = (PetscBool) (isp4 || tisp4);
629: PetscStrcasecmp(eargs[0],"-np",&tisp4);
630: isp4 = (PetscBool) (isp4 || tisp4);
631: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
632: PetscOptionsValidKey(eargs[0],&key);
634: if (!key) {
635: eargs++; left--;
636: } else if (isoptions_file) {
637: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
638: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
639: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
640: eargs += 2; left -= 2;
641: } else if (isprefixpush) {
642: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
643: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
644: PetscOptionsPrefixPush(options,eargs[1]);
645: eargs += 2; left -= 2;
646: } else if (isprefixpop) {
647: PetscOptionsPrefixPop(options);
648: eargs++; left--;
650: /*
651: These are "bad" options that MPICH, etc put on the command line
652: we strip them out here.
653: */
654: } else if (tisp4 || isp4rmrank) {
655: eargs += 1; left -= 1;
656: } else if (isp4 || isp4yourname) {
657: eargs += 2; left -= 2;
658: } else {
659: PetscBool nextiskey = PETSC_FALSE;
660: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
661: if (left < 2 || nextiskey) {
662: PetscOptionsSetValue(options,eargs[0],NULL);
663: eargs++; left--;
664: } else {
665: PetscOptionsSetValue(options,eargs[0],eargs[1]);
666: eargs += 2; left -= 2;
667: }
668: }
669: }
670: return(0);
671: }
676: /*@C
677: PetscOptionsInsert - Inserts into the options database from the command line,
678: the environmental variable and a file.
680: Input Parameters:
681: + options - options database or NULL for the default global database
682: . argc - count of number of command line arguments
683: . args - the command line arguments
684: - file - optional filename, defaults to ~username/.petscrc
686: Note:
687: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
688: the user does not typically need to call this routine. PetscOptionsInsert()
689: can be called several times, adding additional entries into the database.
691: Options Database Keys:
692: + -options_monitor <optional filename> - print options names and values as they are set
693: . -options_file <filename> - read options from a file
695: Level: advanced
697: Concepts: options database^adding
699: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
700: PetscInitialize()
701: @*/
702: PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
703: {
705: PetscMPIInt rank;
706: char pfile[PETSC_MAX_PATH_LEN];
707: PetscBool flag = PETSC_FALSE;
709:
711: if (!options) {
712: if (!defaultoptions) {
713: PetscOptionsCreateDefault();
714: }
715: options = defaultoptions;
716: }
717: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
719: options->argc = (argc) ? *argc : 0;
720: options->args = (args) ? *args : NULL;
722: if (file && file[0]) {
723: char fullpath[PETSC_MAX_PATH_LEN];
725: PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
726: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
727: }
728: /*
729: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
730: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
731: */
732: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
733: PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
734: if (!flag) {
735: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
736: /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
737: if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
738: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
739: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
740: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
741: }
743: /* insert environmental options */
744: {
745: char *eoptions = 0;
746: size_t len = 0;
747: if (!rank) {
748: eoptions = (char*)getenv("PETSC_OPTIONS");
749: PetscStrlen(eoptions,&len);
750: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
751: } else {
752: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
753: if (len) {
754: PetscMalloc1(len+1,&eoptions);
755: }
756: }
757: if (len) {
758: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
759: if (rank) eoptions[len] = 0;
760: PetscOptionsInsertString(options,eoptions);
761: if (rank) {PetscFree(eoptions);}
762: }
763: }
765: #if defined(PETSC_HAVE_YAML)
766: char yaml_file[PETSC_MAX_PATH_LEN];
767: PetscBool yaml_flg = PETSC_FALSE;
768: PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
769: if (yaml_flg) PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
770: #endif
772: /* insert command line options again because they take precedence over arguments in petscrc/environment */
773: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
774: return(0);
775: }
779: /*@C
780: PetscOptionsView - Prints the options that have been loaded. This is
781: useful for debugging purposes.
783: Logically Collective on PetscViewer
785: Input Parameter:
786: . viewer - must be an PETSCVIEWERASCII viewer
788: Options Database Key:
789: . -options_table - Activates PetscOptionsView() within PetscFinalize()
791: Level: advanced
793: Concepts: options database^printing
795: .seealso: PetscOptionsAllUsed()
796: @*/
797: PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer)
798: {
800: PetscInt i;
801: PetscBool isascii;
804: options = options ? options : defaultoptions;
805: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
806: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
807: if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");
809: if (options->N) {
810: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
811: } else {
812: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
813: }
814: for (i=0; i<options->N; i++) {
815: if (options->values[i]) {
816: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
817: } else {
818: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
819: }
820: }
821: if (options->N) {
822: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
823: }
824: return(0);
825: }
829: /*
830: Called by error handlers to print options used in run
831: */
832: PetscErrorCode PetscOptionsViewError(void)
833: {
834: PetscInt i;
835: PetscOptions options = defaultoptions;
838: if (options->N) {
839: (*PetscErrorPrintf)("PETSc Option Table entries:\n");
840: } else {
841: (*PetscErrorPrintf)("No PETSc Option Table entries\n");
842: }
843: for (i=0; i<options->N; i++) {
844: if (options->values[i]) {
845: (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
846: } else {
847: (*PetscErrorPrintf)("-%s\n",options->names[i]);
848: }
849: }
850: return(0);
851: }
855: /*@C
856: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
858: Not Collective
860: Input Paramter:
861: . options - the options database, use NULL for the default global database
863: Output Parameter:
864: . copts - pointer where string pointer is stored
866: Notes: the array and each entry in the array should be freed with PetscFree()
868: Level: advanced
870: Concepts: options database^listing
872: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
873: @*/
874: PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[])
875: {
877: PetscInt i;
878: size_t len = 1,lent = 0;
879: char *coptions = NULL;
882: options = options ? options : defaultoptions;
884: /* count the length of the required string */
885: for (i=0; i<options->N; i++) {
886: PetscStrlen(options->names[i],&lent);
887: len += 2 + lent;
888: if (options->values[i]) {
889: PetscStrlen(options->values[i],&lent);
890: len += 1 + lent;
891: }
892: }
893: PetscMalloc1(len,&coptions);
894: coptions[0] = 0;
895: for (i=0; i<options->N; i++) {
896: PetscStrcat(coptions,"-");
897: PetscStrcat(coptions,options->names[i]);
898: PetscStrcat(coptions," ");
899: if (options->values[i]) {
900: PetscStrcat(coptions,options->values[i]);
901: PetscStrcat(coptions," ");
902: }
903: }
904: *copts = coptions;
905: return(0);
906: }
910: /*@C
911: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
913: Not Collective, but prefix will only be applied on calling ranks
915: Input Parameter:
916: + options - options database, or NULL for the default global database
917: - prefix - The string to append to the existing prefix
919: Options Database Keys:
920: + -prefix_push <some_prefix_> - push the given prefix
921: - -prefix_pop - pop the last prefix
923: Notes:
924: It is common to use this in conjunction with -options_file as in
926: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
928: where the files no longer require all options to be prefixed with -system2_.
930: Level: advanced
932: .seealso: PetscOptionsPrefixPop()
933: @*/
934: PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
935: {
937: size_t n;
938: PetscInt start;
939: char buf[2048];
940: PetscBool key;
944: options = options ? options : defaultoptions;
945: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
946: buf[0] = '-';
947: PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
948: buf[sizeof(buf) - 1] = 0;
949: PetscOptionsValidKey(buf,&key);
950: 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);
952: if (!options) {
953: PetscOptionsInsert(NULL,0,0,0);
954: options = defaultoptions;
955: }
956: 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);
957: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
958: PetscStrlen(prefix,&n);
959: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
960: PetscMemcpy(options->prefix+start,prefix,n+1);
961: options->prefixstack[options->prefixind++] = start+n;
962: return(0);
963: }
967: /*@C
968: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
970: Not Collective, but prefix will only be popped on calling ranks
972: Input Parameters:
973: . options - options database, or NULL for the default global database
975: Level: advanced
977: .seealso: PetscOptionsPrefixPush()
978: @*/
979: PetscErrorCode PetscOptionsPrefixPop(PetscOptions options)
980: {
981: PetscInt offset;
984: options = options ? options : defaultoptions;
985: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
986: options->prefixind--;
987: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
988: options->prefix[offset] = 0;
989: return(0);
990: }
994: /*@C
995: PetscOptionsClear - Removes all options form the database leaving it empty.
997: Input Parameters:
998: . options - options database, use NULL for the default global database
1000: Level: developer
1002: .seealso: PetscOptionsInsert()
1003: @*/
1004: PetscErrorCode PetscOptionsClear(PetscOptions options)
1005: {
1006: PetscInt i;
1009: options = options ? options : defaultoptions;
1010: for (i=0; i<options->N; i++) {
1011: if (options->names[i]) free(options->names[i]);
1012: if (options->values[i]) free(options->values[i]);
1013: }
1014: for (i=0; i<options->Naliases; i++) {
1015: free(options->aliases1[i]);
1016: free(options->aliases2[i]);
1017: }
1018: options->prefix[0] = 0;
1019: options->prefixind = 0;
1020: options->N = 0;
1021: options->Naliases = 0;
1022: return(0);
1023: }
1027: /*@
1028: PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options
1030: Input Parameters:
1031: . obj - the PetscObject
1033: Level: developer
1035: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
1036: PCBJACOBI from all printing the same help messages to the screen
1038: .seealso: PetscOptionsInsert()
1039: @*/
1040: PetscErrorCode PetscObjectSetPrintedOptions(PetscObject obj)
1041: {
1043: obj->optionsprinted = PETSC_TRUE;
1044: return(0);
1045: }
1049: /*@
1050: 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.
1052: Input Parameters:
1053: + pobj - the parent object
1054: - obj - the PetscObject
1056: Level: developer
1058: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
1059: PCBJACOBI from all printing the same help messages to the screen
1061: This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap
1063: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1064: @*/
1065: PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1066: {
1068: PetscMPIInt prank,size;
1071: MPI_Comm_rank(pobj->comm,&prank);
1072: MPI_Comm_size(obj->comm,&size);
1073: if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
1074: return(0);
1075: }
1079: /*@
1080: PetscOptionsDestroy - Destroys an option database.
1082: Input Parameter:
1083: . options - the PetscOptions object
1085: Level: developer
1087: .seealso: PetscOptionsInsert()
1088: @*/
1089: PetscErrorCode PetscOptionsDestroy(PetscOptions *options)
1090: {
1094: PetscOptionsClear(*options);
1095: free(*options);
1096: *options = NULL;
1097: return(0);
1098: }
1102: PetscErrorCode PetscOptionsDestroyDefault(void)
1103: {
1106: PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1107: return 0;
1108: }
1113: /*@C
1114: PetscOptionsSetValue - Sets an option name-value pair in the options
1115: database, overriding whatever is already present.
1117: Not collective, but setting values on certain processors could cause problems
1118: for parallel objects looking for options.
1120: Input Parameters:
1121: + options - options database, use NULL for the default global database
1122: . name - name of option, this SHOULD have the - prepended
1123: - value - the option value (not used for all options)
1125: Level: intermediate
1127: Note:
1128: This function can be called BEFORE PetscInitialize()
1130: Only some options have values associated with them, such as
1131: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
1133: Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized
1135: Concepts: options database^adding option
1137: .seealso: PetscOptionsInsert()
1138: @*/
1139: PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1140: {
1141: size_t len;
1143: PetscInt N,n,i;
1144: char **names;
1145: char fullname[2048];
1146: const char *name = iname;
1147: int match;
1149: if (!options) {
1150: if (!defaultoptions) {
1151: PetscOptionsCreateDefault();
1152: if (ierr) return ierr;
1153: }
1154: options = defaultoptions;
1155: }
1157: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
1158: match = strcmp(name,"-h");
1159: if (!match) name = "-help";
1161: name++; /* skip starting hyphen */
1162: if (options->prefixind > 0) {
1163: strncpy(fullname,options->prefix,sizeof(fullname));
1164: strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1165: name = fullname;
1166: }
1168: /* check against aliases */
1169: N = options->Naliases;
1170: for (i=0; i<N; i++) {
1171: #if defined(PETSC_HAVE_STRCASECMP)
1172: match = strcasecmp(options->aliases1[i],name);
1173: #elif defined(PETSC_HAVE_STRICMP)
1174: match = stricmp(options->aliases1[i],name);
1175: #else
1176: Error
1177: #endif
1178: if (!match) {
1179: name = options->aliases2[i];
1180: break;
1181: }
1182: }
1184: N = options->N;
1185: n = N;
1186: names = options->names;
1188: for (i=0; i<N; i++) {
1189: #if defined(PETSC_HAVE_STRCASECMP)
1190: match = strcasecmp(names[i],name);
1191: #elif defined(PETSC_HAVE_STRICMP)
1192: match = stricmp(names[i],name);
1193: #else
1194: Error
1195: #endif
1196: if (!match) {
1197: if (options->values[i]) free(options->values[i]);
1198: len = value ? strlen(value) : 0;
1199: if (len) {
1200: options->values[i] = (char*)malloc((len+1)*sizeof(char));
1201: if (!options->values[i]) return PETSC_ERR_MEM;
1202: strcpy(options->values[i],value);
1203: } else options->values[i] = 0;
1204: return 0;
1205: } else if (strcmp(names[i],name) > 0) {
1206: n = i;
1207: break;
1208: }
1209: }
1210: if (N >= MAXOPTIONS) abort();
1212: /* shift remaining values down 1 */
1213: for (i=N; i>n; i--) {
1214: options->names[i] = options->names[i-1];
1215: options->values[i] = options->values[i-1];
1216: options->used[i] = options->used[i-1];
1217: }
1218: /* insert new name and value */
1219: len = strlen(name);
1220: options->names[n] = (char*)malloc((len+1)*sizeof(char));
1221: if (!options->names[n]) return PETSC_ERR_MEM;
1222: strcpy(options->names[n],name);
1223: len = value ? strlen(value) : 0;
1224: if (len) {
1225: options->values[n] = (char*)malloc((len+1)*sizeof(char));
1226: if (!options->values[n]) return PETSC_ERR_MEM;
1227: strcpy(options->values[n],value);
1228: } else options->values[n] = NULL;
1229: options->used[n] = PETSC_FALSE;
1230: options->N++;
1231: return 0;
1232: }
1236: /*@C
1237: PetscOptionsClearValue - Clears an option name-value pair in the options
1238: database, overriding whatever is already present.
1240: Not Collective, but setting values on certain processors could cause problems
1241: for parallel objects looking for options.
1243: Input Parameter:
1244: + options - options database, use NULL for the default global database
1245: . name - name of option, this SHOULD have the - prepended
1247: Level: intermediate
1249: Concepts: options database^removing option
1250: .seealso: PetscOptionsInsert()
1251: @*/
1252: PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char iname[])
1253: {
1255: PetscInt N,n,i;
1256: char **names,*name=(char*)iname;
1257: PetscBool gt,match;
1260: options = options ? options : defaultoptions;
1261: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1262: name++;
1264: N = options->N; n = 0;
1265: names = options->names;
1267: for (i=0; i<N; i++) {
1268: PetscStrcasecmp(names[i],name,&match);
1269: PetscStrgrt(names[i],name,>);
1270: if (match) {
1271: if (options->names[i]) free(options->names[i]);
1272: if (options->values[i]) free(options->values[i]);
1273: PetscOptionsMonitor(name,"");
1274: break;
1275: } else if (gt) return(0); /* it was not listed */
1277: n++;
1278: }
1279: if (n == N) return(0); /* it was not listed */
1281: /* shift remaining values down 1 */
1282: for (i=n; i<N-1; i++) {
1283: options->names[i] = options->names[i+1];
1284: options->values[i] = options->values[i+1];
1285: options->used[i] = options->used[i+1];
1286: }
1287: options->N--;
1288: return(0);
1289: }
1293: /*@C
1294: PetscOptionsSetAlias - Makes a key and alias for another key
1296: Not Collective, but setting values on certain processors could cause problems
1297: for parallel objects looking for options.
1299: Input Parameters:
1300: + options - options database or NULL for default global database
1301: . inewname - the alias
1302: - ioldname - the name that alias will refer to
1304: Level: advanced
1306: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1307: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1308: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1309: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1310: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1311: PetscOptionsFList(), PetscOptionsEList()
1312: @*/
1313: PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1314: {
1316: PetscInt n = options->Naliases;
1317: size_t len;
1318: char *newname = (char*)inewname,*oldname = (char*)ioldname;
1321: options = options ? options : defaultoptions;
1322: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1323: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1324: 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);
1326: newname++; oldname++;
1327: PetscStrlen(newname,&len);
1328: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1329: PetscStrcpy(options->aliases1[n],newname);
1330: PetscStrlen(oldname,&len);
1331: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1332: PetscStrcpy(options->aliases2[n],oldname);
1333: options->Naliases++;
1334: return(0);
1335: }
1339: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool *flg)
1340: {
1342: PetscInt i,N;
1343: size_t len;
1344: char **names,tmp[256];
1345: PetscBool match;
1348: options = options ? options : defaultoptions;
1349: N = options->N;
1350: names = options->names;
1352: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1354: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1355: if (pre) {
1356: char *ptr = tmp;
1357: const char *namep = name;
1358: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1359: if (name[1] == '-') {
1360: *ptr++ = '-';
1361: namep++;
1362: }
1363: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1364: tmp[sizeof(tmp)-1] = 0;
1365: PetscStrlen(tmp,&len);
1366: PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1367: } else {
1368: PetscStrncpy(tmp,name+1,sizeof(tmp));
1369: tmp[sizeof(tmp)-1] = 0;
1370: }
1371: #if defined(PETSC_USE_DEBUG)
1372: {
1373: PetscBool valid;
1374: char key[sizeof(tmp)+1] = "-";
1376: PetscMemcpy(key+1,tmp,sizeof(tmp));
1377: PetscOptionsValidKey(key,&valid);
1378: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1379: }
1380: #endif
1382: /* slow search */
1383: *flg = PETSC_FALSE;
1384: for (i=0; i<N; i++) {
1385: PetscStrcasecmp(names[i],tmp,&match);
1386: if (match) {
1387: *value = options->values[i];
1388: options->used[i] = PETSC_TRUE;
1389: *flg = PETSC_TRUE;
1390: break;
1391: }
1392: }
1393: if (!*flg) {
1394: PetscInt j,cnt = 0,locs[16],loce[16];
1395: size_t n;
1396: PetscStrlen(tmp,&n);
1397: /* determine the location and number of all _%d_ in the key */
1398: for (i=0; i< (PetscInt)n; i++) {
1399: if (tmp[i] == '_') {
1400: for (j=i+1; j< (PetscInt)n; j++) {
1401: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1402: if (tmp[j] == '_' && j > i+1) { /* found a number */
1403: locs[cnt] = i+1;
1404: loce[cnt++] = j+1;
1405: }
1406: break;
1407: }
1408: }
1409: }
1410: if (cnt) {
1411: char tmp2[256];
1412: for (i=0; i<cnt; i++) {
1413: PetscStrcpy(tmp2,"-");
1414: PetscStrncat(tmp2,tmp,locs[i]);
1415: PetscStrcat(tmp2,tmp+loce[i]);
1416: PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
1417: if (*flg) break;
1418: }
1419: }
1420: }
1421: return(0);
1422: }
1426: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
1427: {
1429: PetscInt i,N;
1430: size_t len;
1431: char **names,tmp[256];
1432: PetscBool match;
1435: options = options ? options : defaultoptions;
1436: N = options->N;
1437: names = options->names;
1439: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1441: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1442: if (pre) {
1443: char *ptr = tmp;
1444: const char *namep = name;
1445: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1446: if (name[1] == '-') {
1447: *ptr++ = '-';
1448: namep++;
1449: }
1450: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1451: tmp[sizeof(tmp)-1] = 0;
1452: PetscStrlen(tmp,&len);
1453: PetscStrncat(tmp,namep+1,sizeof(tmp)-len-1);
1454: } else {
1455: PetscStrncpy(tmp,name+1,sizeof(tmp));
1456: tmp[sizeof(tmp)-1] = 0;
1457: }
1458: #if defined(PETSC_USE_DEBUG)
1459: {
1460: PetscBool valid;
1461: char key[sizeof(tmp)+1] = "-";
1463: PetscMemcpy(key+1,tmp,sizeof(tmp));
1464: PetscOptionsValidKey(key,&valid);
1465: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1466: }
1467: #endif
1469: /* slow search */
1470: *flg = PETSC_FALSE;
1471: PetscStrlen(tmp,&len);
1472: for (i = 0; i < N; ++i) {
1473: PetscStrncmp(names[i], tmp, len, &match);
1474: if (match) {
1475: if (value) *value = options->values[i];
1476: options->used[i] = PETSC_TRUE;
1477: if (flg) *flg = PETSC_TRUE;
1478: break;
1479: }
1480: }
1481: return(0);
1482: }
1486: /*@C
1487: PetscOptionsReject - Generates an error if a certain option is given.
1489: Not Collective, but setting values on certain processors could cause problems
1490: for parallel objects looking for options.
1492: Input Parameters:
1493: + options - options database use NULL for default global database
1494: . name - the option one is seeking
1495: - mess - error message (may be NULL)
1497: Level: advanced
1499: Concepts: options database^rejecting option
1501: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1502: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1503: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1504: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1505: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1506: PetscOptionsFList(), PetscOptionsEList()
1507: @*/
1508: PetscErrorCode PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
1509: {
1511: PetscBool flag = PETSC_FALSE;
1514: options = options ? options : defaultoptions;
1515: PetscOptionsHasName(options,NULL,name,&flag);
1516: if (flag) {
1517: if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1518: else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1519: }
1520: return(0);
1521: }
1525: /*@C
1526: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1527: its value is set to false.
1529: Not Collective
1531: Input Parameters:
1532: + options - options database use NULL for default global database
1533: . name - the option one is seeking
1534: - pre - string to prepend to the name or NULL
1536: Output Parameters:
1537: . set - PETSC_TRUE if found else PETSC_FALSE.
1539: Level: beginner
1541: Concepts: options database^has option name
1543: Notes: Name cannot be simply -h
1545: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1547: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1548: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1549: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1550: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1551: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1552: PetscOptionsFList(), PetscOptionsEList()
1553: @*/
1554: PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set)
1555: {
1556: char *value;
1558: PetscBool flag;
1561: options = options ? options : defaultoptions;
1562: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1563: if (set) *set = flag;
1564: return(0);
1565: }
1569: /*@C
1570: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1572: Not Collective
1574: Input Parameters:
1575: + options - options database use NULL for default global database
1576: . pre - the string to prepend to the name or NULL
1577: - name - the option one is seeking
1579: Output Parameter:
1580: + ivalue - the integer value to return
1581: - set - PETSC_TRUE if found, else PETSC_FALSE
1583: Level: beginner
1585: Concepts: options database^has int
1587: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1588: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1589: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1590: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1591: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1592: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1593: PetscOptionsFList(), PetscOptionsEList()
1594: @*/
1595: PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1596: {
1597: char *value;
1599: PetscBool flag;
1604: options = options ? options : defaultoptions;
1605: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1606: if (flag) {
1607: if (!value) {
1608: if (set) *set = PETSC_FALSE;
1609: } else {
1610: if (set) *set = PETSC_TRUE;
1611: PetscOptionsStringToInt(value,ivalue);
1612: }
1613: } else {
1614: if (set) *set = PETSC_FALSE;
1615: }
1616: return(0);
1617: }
1621: /*@C
1622: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1624: Not Collective
1626: Input Parameters:
1627: + options - options database use NULL for default global database
1628: . pre - the string to prepend to the name or NULL
1629: . opt - option name
1630: . list - the possible choices (one of these must be selected, anything else is invalid)
1631: . ntext - number of choices
1633: Output Parameter:
1634: + value - the index of the value to return (defaults to zero if the option name is given but choice is listed)
1635: - set - PETSC_TRUE if found, else PETSC_FALSE
1637: Level: intermediate
1639: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1641: Concepts: options database^list
1643: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1644: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1645: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1646: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1647: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1648: PetscOptionsFList(), PetscOptionsEList()
1649: @*/
1650: PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set)
1651: {
1653: size_t alen,len = 0;
1654: char *svalue;
1655: PetscBool aset,flg = PETSC_FALSE;
1656: PetscInt i;
1659: options = options ? options : defaultoptions;
1660: for (i=0; i<ntext; i++) {
1661: PetscStrlen(list[i],&alen);
1662: if (alen > len) len = alen;
1663: }
1664: len += 5; /* a little extra space for user mistypes */
1665: PetscMalloc1(len,&svalue);
1666: PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
1667: if (aset) {
1668: PetscEListFind(ntext,list,svalue,value,&flg);
1669: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1670: if (set) *set = PETSC_TRUE;
1671: } else if (set) *set = PETSC_FALSE;
1672: PetscFree(svalue);
1673: return(0);
1674: }
1678: /*@C
1679: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1681: Not Collective
1683: Input Parameters:
1684: + options - options database use NULL for default global database
1685: . pre - option prefix or NULL
1686: . opt - option name
1687: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1688: - defaultv - the default (current) value
1690: Output Parameter:
1691: + value - the value to return
1692: - set - PETSC_TRUE if found, else PETSC_FALSE
1694: Level: beginner
1696: Concepts: options database
1698: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1700: list is usually something like PCASMTypes or some other predefined list of enum names
1702: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1703: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1704: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1705: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1706: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1707: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1708: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1709: @*/
1710: PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set)
1711: {
1713: PetscInt ntext = 0,tval;
1714: PetscBool fset;
1717: options = options ? options : defaultoptions;
1718: while (list[ntext++]) {
1719: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1720: }
1721: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1722: ntext -= 3;
1723: PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
1724: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1725: if (fset) *value = (PetscEnum)tval;
1726: if (set) *set = fset;
1727: return(0);
1728: }
1732: /*@C
1733: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1734: option in the database.
1736: Not Collective
1738: Input Parameters:
1739: + options - options database use NULL for default global database
1740: . pre - the string to prepend to the name or NULL
1741: - name - the option one is seeking
1743: Output Parameter:
1744: + ivalue - the logical value to return
1745: - set - PETSC_TRUE if found, else PETSC_FALSE
1747: Level: beginner
1749: Notes:
1750: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1751: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1753: If the user does not supply the option (as either true or false) ivalue is NOT changed. Thus
1754: you NEED TO ALWAYS initialize the ivalue.
1756: Concepts: options database^has logical
1758: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1759: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1760: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1761: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1762: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1763: PetscOptionsFList(), PetscOptionsEList()
1764: @*/
1765: PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1766: {
1767: char *value;
1768: PetscBool flag;
1774: options = options ? options : defaultoptions;
1775: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1776: if (flag) {
1777: if (set) *set = PETSC_TRUE;
1778: if (!value) {
1779: if (ivalue) *ivalue = PETSC_TRUE;
1780: } else {
1781: PetscOptionsStringToBool(value, ivalue);
1782: }
1783: } else {
1784: if (set) *set = PETSC_FALSE;
1785: }
1786: return(0);
1787: }
1791: /*@C
1792: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1793: option in the database. The values must be separated with commas with
1794: no intervening spaces.
1796: Not Collective
1798: Input Parameters:
1799: + options - options database use NULL for default global database
1800: . pre - string to prepend to each name or NULL
1801: . name - the option one is seeking
1802: - nmax - maximum number of values to retrieve
1804: Output Parameter:
1805: + dvalue - the integer values to return
1806: . nmax - actual number of values retreived
1807: - set - PETSC_TRUE if found, else PETSC_FALSE
1809: Level: beginner
1811: Concepts: options database^array of ints
1813: Notes:
1814: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1815: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1817: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1818: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1819: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1820: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1821: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1822: PetscOptionsFList(), PetscOptionsEList()
1823: @*/
1824: PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1825: {
1826: char *value;
1828: PetscInt n = 0;
1829: PetscBool flag;
1830: PetscToken token;
1835: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1836: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1837: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1839: if (set) *set = PETSC_TRUE;
1841: PetscTokenCreate(value,',',&token);
1842: PetscTokenFind(token,&value);
1843: while (n < *nmax) {
1844: if (!value) break;
1845: PetscOptionsStringToBool(value,dvalue);
1846: PetscTokenFind(token,&value);
1847: dvalue++;
1848: n++;
1849: }
1850: PetscTokenDestroy(&token);
1851: *nmax = n;
1852: return(0);
1853: }
1857: /*@C
1858: PetscOptionsGetReal - Gets the double precision value for a particular
1859: option in the database.
1861: Not Collective
1863: Input Parameters:
1864: + options - options database use NULL for default global database
1865: . pre - string to prepend to each name or NULL
1866: - name - the option one is seeking
1868: Output Parameter:
1869: + dvalue - the double value to return
1870: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1872: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1874: Level: beginner
1876: Concepts: options database^has double
1878: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1879: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1880: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1881: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1882: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1883: PetscOptionsFList(), PetscOptionsEList()
1884: @*/
1885: PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1886: {
1887: char *value;
1889: PetscBool flag;
1894: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1895: if (flag) {
1896: if (!value) {
1897: if (set) *set = PETSC_FALSE;
1898: } else {
1899: if (set) *set = PETSC_TRUE;
1900: PetscOptionsStringToReal(value,dvalue);
1901: }
1902: } else {
1903: if (set) *set = PETSC_FALSE;
1904: }
1905: return(0);
1906: }
1910: /*@C
1911: PetscOptionsGetScalar - Gets the scalar value for a particular
1912: option in the database.
1914: Not Collective
1916: Input Parameters:
1917: + options - options database use NULL for default global database
1918: . pre - string to prepend to each name or NULL
1919: - name - the option one is seeking
1921: Output Parameter:
1922: + dvalue - the double value to return
1923: - set - PETSC_TRUE if found, else PETSC_FALSE
1925: Level: beginner
1927: Usage:
1928: A complex number 2+3i must be specified with NO spaces
1930: Note: if the option is given but no value is provided then set is given the value PETSC_FALSE
1932: Concepts: options database^has scalar
1934: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1935: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1936: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1937: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1938: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1939: PetscOptionsFList(), PetscOptionsEList()
1940: @*/
1941: PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1942: {
1943: char *value;
1944: PetscBool flag;
1950: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1951: if (flag) {
1952: if (!value) {
1953: if (set) *set = PETSC_FALSE;
1954: } else {
1955: #if !defined(PETSC_USE_COMPLEX)
1956: PetscOptionsStringToReal(value,dvalue);
1957: #else
1958: PetscOptionsStringToScalar(value,dvalue);
1959: #endif
1960: if (set) *set = PETSC_TRUE;
1961: }
1962: } else { /* flag */
1963: if (set) *set = PETSC_FALSE;
1964: }
1965: return(0);
1966: }
1970: /*@C
1971: PetscOptionsGetRealArray - Gets an array of double precision values for a
1972: particular option in the database. The values must be separated with
1973: commas with no intervening spaces.
1975: Not Collective
1977: Input Parameters:
1978: + options - options database use NULL for default global database
1979: . pre - string to prepend to each name or NULL
1980: . name - the option one is seeking
1981: - nmax - maximum number of values to retrieve
1983: Output Parameters:
1984: + dvalue - the double values to return
1985: . nmax - actual number of values retreived
1986: - set - PETSC_TRUE if found, else PETSC_FALSE
1988: Level: beginner
1990: Concepts: options database^array of doubles
1992: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1993: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1994: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1995: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1996: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1997: PetscOptionsFList(), PetscOptionsEList()
1998: @*/
1999: PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
2000: {
2001: char *value;
2003: PetscInt n = 0;
2004: PetscBool flag;
2005: PetscToken token;
2010: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2011: if (!flag) {
2012: if (set) *set = PETSC_FALSE;
2013: *nmax = 0;
2014: return(0);
2015: }
2016: if (!value) {
2017: if (set) *set = PETSC_TRUE;
2018: *nmax = 0;
2019: return(0);
2020: }
2022: if (set) *set = PETSC_TRUE;
2024: PetscTokenCreate(value,',',&token);
2025: PetscTokenFind(token,&value);
2026: while (n < *nmax) {
2027: if (!value) break;
2028: PetscOptionsStringToReal(value,dvalue++);
2029: PetscTokenFind(token,&value);
2030: n++;
2031: }
2032: PetscTokenDestroy(&token);
2033: *nmax = n;
2034: return(0);
2035: }
2039: /*@C
2040: PetscOptionsGetScalarArray - Gets an array of scalars for a
2041: particular option in the database. The values must be separated with
2042: commas with no intervening spaces.
2044: Not Collective
2046: Input Parameters:
2047: + options - options database use NULL for default global database
2048: . pre - string to prepend to each name or NULL
2049: . name - the option one is seeking
2050: - nmax - maximum number of values to retrieve
2052: Output Parameters:
2053: + dvalue - the scalar values to return
2054: . nmax - actual number of values retreived
2055: - set - PETSC_TRUE if found, else PETSC_FALSE
2057: Level: beginner
2059: Concepts: options database^array of doubles
2061: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2062: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
2063: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2064: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2065: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2066: PetscOptionsFList(), PetscOptionsEList()
2067: @*/
2068: PetscErrorCode PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar dvalue[],PetscInt *nmax,PetscBool *set)
2069: {
2070: char *value;
2072: PetscInt n = 0;
2073: PetscBool flag;
2074: PetscToken token;
2079: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2080: if (!flag) {
2081: if (set) *set = PETSC_FALSE;
2082: *nmax = 0;
2083: return(0);
2084: }
2085: if (!value) {
2086: if (set) *set = PETSC_TRUE;
2087: *nmax = 0;
2088: return(0);
2089: }
2091: if (set) *set = PETSC_TRUE;
2093: PetscTokenCreate(value,',',&token);
2094: PetscTokenFind(token,&value);
2095: while (n < *nmax) {
2096: if (!value) break;
2097: PetscOptionsStringToScalar(value,dvalue++);
2098: PetscTokenFind(token,&value);
2099: n++;
2100: }
2101: PetscTokenDestroy(&token);
2102: *nmax = n;
2103: return(0);
2104: }
2108: /*@C
2109: PetscOptionsGetIntArray - Gets an array of integer values for a particular
2110: option in the database.
2112: Not Collective
2114: Input Parameters:
2115: + options - options database use NULL for default global database
2116: . pre - string to prepend to each name or NULL
2117: . name - the option one is seeking
2118: - nmax - maximum number of values to retrieve
2120: Output Parameter:
2121: + dvalue - the integer values to return
2122: . nmax - actual number of values retreived
2123: - set - PETSC_TRUE if found, else PETSC_FALSE
2125: Level: beginner
2127: Notes:
2128: The array can be passed as
2129: a comma separated list: 0,1,2,3,4,5,6,7
2130: a range (start-end+1): 0-8
2131: a range with given increment (start-end+1:inc): 0-7:2
2132: a combination of values and ranges separated by commas: 0,1-8,8-15:2
2134: There must be no intervening spaces between the values.
2136: Concepts: options database^array of ints
2138: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2139: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2140: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2141: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2142: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2143: PetscOptionsFList(), PetscOptionsEList()
2144: @*/
2145: PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
2146: {
2147: char *value;
2149: PetscInt n = 0,i,j,start,end,inc,nvalues;
2150: size_t len;
2151: PetscBool flag,foundrange;
2152: PetscToken token;
2157: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2158: if (!flag) {
2159: if (set) *set = PETSC_FALSE;
2160: *nmax = 0;
2161: return(0);
2162: }
2163: if (!value) {
2164: if (set) *set = PETSC_TRUE;
2165: *nmax = 0;
2166: return(0);
2167: }
2169: if (set) *set = PETSC_TRUE;
2171: PetscTokenCreate(value,',',&token);
2172: PetscTokenFind(token,&value);
2173: while (n < *nmax) {
2174: if (!value) break;
2176: /* look for form d-D where d and D are integers */
2177: foundrange = PETSC_FALSE;
2178: PetscStrlen(value,&len);
2179: if (value[0] == '-') i=2;
2180: else i=1;
2181: for (;i<(int)len; i++) {
2182: if (value[i] == '-') {
2183: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2184: value[i] = 0;
2186: PetscOptionsStringToInt(value,&start);
2187: inc = 1;
2188: j = i+1;
2189: for (;j<(int)len; j++) {
2190: if (value[j] == ':') {
2191: value[j] = 0;
2193: PetscOptionsStringToInt(value+j+1,&inc);
2194: 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);
2195: break;
2196: }
2197: }
2198: PetscOptionsStringToInt(value+i+1,&end);
2199: 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);
2200: nvalues = (end-start)/inc + (end-start)%inc;
2201: 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);
2202: for (;start<end; start+=inc) {
2203: *dvalue = start; dvalue++;n++;
2204: }
2205: foundrange = PETSC_TRUE;
2206: break;
2207: }
2208: }
2209: if (!foundrange) {
2210: PetscOptionsStringToInt(value,dvalue);
2211: dvalue++;
2212: n++;
2213: }
2214: PetscTokenFind(token,&value);
2215: }
2216: PetscTokenDestroy(&token);
2217: *nmax = n;
2218: return(0);
2219: }
2223: /*@C
2224: PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.
2226: Not Collective
2228: Input Parameters:
2229: + options - options database use NULL for default global database
2230: . pre - option prefix or NULL
2231: . name - option name
2232: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2233: - nmax - maximum number of values to retrieve
2235: Output Parameters:
2236: + dvalue - the enum values to return
2237: . nmax - actual number of values retreived
2238: - set - PETSC_TRUE if found, else PETSC_FALSE
2240: Level: beginner
2242: Concepts: options database
2244: Notes:
2245: The array must be passed as a comma separated list.
2247: There must be no intervening spaces between the values.
2249: list is usually something like PCASMTypes or some other predefined list of enum names.
2251: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2252: PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2253: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2254: PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2255: PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2256: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2257: @*/
2258: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2259: {
2260: char *svalue;
2261: PetscInt n = 0;
2262: PetscEnum evalue;
2263: PetscBool flag;
2264: PetscToken token;
2273: PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2274: if (!flag) {
2275: if (set) *set = PETSC_FALSE;
2276: *nmax = 0;
2277: return(0);
2278: }
2279: if (!svalue) {
2280: if (set) *set = PETSC_TRUE;
2281: *nmax = 0;
2282: return(0);
2283: }
2284: if (set) *set = PETSC_TRUE;
2286: PetscTokenCreate(svalue,',',&token);
2287: PetscTokenFind(token,&svalue);
2288: while (svalue && n < *nmax) {
2289: PetscEnumFind(list,svalue,&evalue,&flag);
2290: if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2291: dvalue[n++] = evalue;
2292: PetscTokenFind(token,&svalue);
2293: }
2294: *nmax = n;
2295: PetscTokenDestroy(&token);
2296: return(0);
2297: }
2301: /*@C
2302: PetscOptionsGetString - Gets the string value for a particular option in
2303: the database.
2305: Not Collective
2307: Input Parameters:
2308: + options - options database use NULL for default global database
2309: . pre - string to prepend to name or NULL
2310: . name - the option one is seeking
2311: - len - maximum length of the string including null termination
2313: Output Parameters:
2314: + string - location to copy string
2315: - set - PETSC_TRUE if found, else PETSC_FALSE
2317: Level: beginner
2319: Fortran Note:
2320: The Fortran interface is slightly different from the C/C++
2321: interface (len is not used). Sample usage in Fortran follows
2322: .vb
2323: character *20 string
2324: integer flg, ierr
2325: call PetscOptionsGetString(PETSC_NULL_OBJECT,PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
2326: .ve
2328: 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
2330: Concepts: options database^string
2332: Note:
2333: 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).
2335: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2336: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2337: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2338: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2339: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2340: PetscOptionsFList(), PetscOptionsEList()
2341: @*/
2342: PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set)
2343: {
2344: char *value;
2346: PetscBool flag;
2351: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2352: if (!flag) {
2353: if (set) *set = PETSC_FALSE;
2354: } else {
2355: if (set) *set = PETSC_TRUE;
2356: if (value) {
2357: PetscStrncpy(string,value,len);
2358: string[len-1] = 0; /* Ensure that the string is NULL terminated */
2359: } else {
2360: PetscMemzero(string,len);
2361: }
2362: }
2363: return(0);
2364: }
2368: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2369: {
2370: char *value;
2372: PetscBool flag;
2375: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2376: if (flag) PetscFunctionReturn(value);
2377: else return(0);
2378: }
2383: /*@C
2384: PetscOptionsGetStringArray - Gets an array of string values for a particular
2385: option in the database. The values must be separated with commas with
2386: no intervening spaces.
2388: Not Collective
2390: Input Parameters:
2391: + options - options database use NULL for default global database
2392: . pre - string to prepend to name or NULL
2393: . name - the option one is seeking
2394: - nmax - maximum number of strings
2396: Output Parameter:
2397: + strings - location to copy strings
2398: - set - PETSC_TRUE if found, else PETSC_FALSE
2400: Level: beginner
2402: Notes:
2403: The user should pass in an array of pointers to char, to hold all the
2404: strings returned by this function.
2406: The user is responsible for deallocating the strings that are
2407: returned. The Fortran interface for this routine is not supported.
2409: Contributed by Matthew Knepley.
2411: Concepts: options database^array of strings
2413: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2414: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2415: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2416: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2417: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2418: PetscOptionsFList(), PetscOptionsEList()
2419: @*/
2420: PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
2421: {
2422: char *value;
2424: PetscInt n;
2425: PetscBool flag;
2426: PetscToken token;
2431: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2432: if (!flag) {
2433: *nmax = 0;
2434: if (set) *set = PETSC_FALSE;
2435: return(0);
2436: }
2437: if (!value) {
2438: *nmax = 0;
2439: if (set) *set = PETSC_FALSE;
2440: return(0);
2441: }
2442: if (!*nmax) {
2443: if (set) *set = PETSC_FALSE;
2444: return(0);
2445: }
2446: if (set) *set = PETSC_TRUE;
2448: PetscTokenCreate(value,',',&token);
2449: PetscTokenFind(token,&value);
2450: n = 0;
2451: while (n < *nmax) {
2452: if (!value) break;
2453: PetscStrallocpy(value,&strings[n]);
2454: PetscTokenFind(token,&value);
2455: n++;
2456: }
2457: PetscTokenDestroy(&token);
2458: *nmax = n;
2459: return(0);
2460: }
2464: /*@C
2465: PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database
2467: Not Collective
2469: Input Parameter:
2470: + options - options database use NULL for default global database
2471: - option - string name of option
2473: Output Parameter:
2474: . used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database
2476: Level: advanced
2478: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2479: @*/
2480: PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2481: {
2482: PetscInt i;
2486: options = options ? options : defaultoptions;
2487: *used = PETSC_FALSE;
2488: for (i=0; i<options->N; i++) {
2489: PetscStrcmp(options->names[i],option,used);
2490: if (*used) {
2491: *used = options->used[i];
2492: break;
2493: }
2494: }
2495: return(0);
2496: }
2500: /*@C
2501: PetscOptionsAllUsed - Returns a count of the number of options in the
2502: database that have never been selected.
2504: Not Collective
2506: Input Parameter:
2507: . options - options database use NULL for default global database
2509: Output Parameter:
2510: . N - count of options not used
2512: Level: advanced
2514: .seealso: PetscOptionsView()
2515: @*/
2516: PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2517: {
2518: PetscInt i,n = 0;
2521: options = options ? options : defaultoptions;
2522: for (i=0; i<options->N; i++) {
2523: if (!options->used[i]) n++;
2524: }
2525: *N = n;
2526: return(0);
2527: }
2531: /*@C
2532: PetscOptionsLeft - Prints to screen any options that were set and never used.
2534: Not collective
2536: Input Parameter:
2537: . options - options database use NULL for default global database
2539: Options Database Key:
2540: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
2542: Level: advanced
2544: .seealso: PetscOptionsAllUsed()
2545: @*/
2546: PetscErrorCode PetscOptionsLeft(PetscOptions options)
2547: {
2549: PetscInt i;
2552: options = options ? options : defaultoptions;
2553: for (i=0; i<options->N; i++) {
2554: if (!options->used[i]) {
2555: if (options->values[i]) {
2556: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2557: } else {
2558: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2559: }
2560: }
2561: }
2562: return(0);
2563: }
2567: /*@
2568: PetscOptionsCreate - Creates the empty options database.
2570: Output Parameter:
2571: . options - Options database object
2573: Level: advanced
2575: @*/
2576: PetscErrorCode PetscOptionsCreate(PetscOptions *options)
2577: {
2578: *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2579: if (!options) return PETSC_ERR_MEM;
2580: (*options)->namegiven = PETSC_FALSE;
2581: (*options)->N = 0;
2582: (*options)->Naliases = 0;
2583: (*options)->numbermonitors = 0;
2584: return 0;
2585: }
2589: /*
2590: PetscOptionsCreateDefault - Creates the default global options database
2592: */
2593: PetscErrorCode PetscOptionsCreateDefault(void)
2594: {
2597: if (!defaultoptions) {
2598: PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2599: }
2600: return 0;
2601: }
2605: /*@C
2606: PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc
2608: Collective on PETSC_COMM_WORLD
2610: Input Parameter:
2611: . options - options database use NULL for default global database
2613: Options Database Keys:
2614: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2615: available for options set through a file, environment variable, or on
2616: the command line. Only options set after PetscInitialize() completes will
2617: be monitored.
2618: . -options_monitor_cancel - cancel all options database monitors
2620: Notes:
2621: To see all options, run your program with the -help option or consult Users-Manual: Introduction
2623: Level: intermediate
2625: .keywords: set, options, database
2626: @*/
2627: PetscErrorCode PetscOptionsSetFromOptions(PetscOptions options)
2628: {
2629: PetscBool flgc = PETSC_FALSE,flgm;
2631: char monfilename[PETSC_MAX_PATH_LEN];
2632: PetscViewer monviewer;
2635: /*
2636: The options argument is currently ignored since we currently maintain only a single options database
2638: options = options ? options : defaultoptions;
2639: */
2640: PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2641: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2642: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2643: PetscOptionsEnd();
2644: if (flgm) {
2645: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2646: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2647: }
2648: if (flgc) { PetscOptionsMonitorCancel(); }
2649: return(0);
2650: }
2655: /*@C
2656: PetscOptionsMonitorDefault - Print all options set value events.
2658: Logically Collective on PETSC_COMM_WORLD
2660: Input Parameters:
2661: + name - option name string
2662: . value - option value string
2663: - dummy - an ASCII viewer
2665: Level: intermediate
2667: .keywords: PetscOptions, default, monitor
2669: .seealso: PetscOptionsMonitorSet()
2670: @*/
2671: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2672: {
2674: PetscViewer viewer = (PetscViewer) dummy;
2677: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2678: return(0);
2679: }
2683: /*@C
2684: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2685: modified the PETSc options database.
2687: Not collective
2689: Input Parameters:
2690: + monitor - pointer to function (if this is NULL, it turns off monitoring
2691: . mctx - [optional] context for private data for the
2692: monitor routine (use NULL if no context is desired)
2693: - monitordestroy - [optional] routine that frees monitor context
2694: (may be NULL)
2696: Calling Sequence of monitor:
2697: $ monitor (const char name[], const char value[], void *mctx)
2699: + name - option name string
2700: . value - option value string
2701: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2703: Options Database Keys:
2704: + -options_monitor - sets PetscOptionsMonitorDefault()
2705: - -options_monitor_cancel - cancels all monitors that have
2706: been hardwired into a code by
2707: calls to PetscOptionsMonitorSet(), but
2708: does not cancel those set via
2709: the options database.
2711: Notes:
2712: The default is to do nothing. To print the name and value of options
2713: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2714: with a null monitoring context.
2716: Several different monitoring routines may be set by calling
2717: PetscOptionsMonitorSet() multiple times; all will be called in the
2718: order in which they were set.
2720: Level: beginner
2722: .keywords: PetscOptions, set, monitor
2724: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2725: @*/
2726: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2727: {
2728: PetscOptions options = defaultoptions;
2731: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2732: options->monitor[options->numbermonitors] = monitor;
2733: options->monitordestroy[options->numbermonitors] = monitordestroy;
2734: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2735: return(0);
2736: }
2740: /*@
2741: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2743: Not collective
2745: Options Database Key:
2746: . -options_monitor_cancel - Cancels all monitors that have
2747: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2748: but does not cancel those set via the options database.
2750: Level: intermediate
2752: .keywords: PetscOptions, set, monitor
2754: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2755: @*/
2756: PetscErrorCode PetscOptionsMonitorCancel(void)
2757: {
2759: PetscInt i;
2760: PetscOptions options = defaultoptions;
2763: for (i=0; i<options->numbermonitors; i++) {
2764: if (options->monitordestroy[i]) {
2765: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2766: }
2767: }
2768: options->numbermonitors = 0;
2769: return(0);
2770: }
2772: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }
2776: /*@C
2777: PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed.
2779: Collective on PetscObject
2781: Input Parameters:
2782: + obj - the object
2783: . bobj - optional other object that provides prefix (if NULL then the prefix in obj is used)
2784: - optionname - option to activate viewing
2786: Level: intermediate
2788: @*/
2789: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2790: {
2791: PetscErrorCode ierr;
2792: PetscViewer viewer;
2793: PetscBool flg;
2794: static PetscBool incall = PETSC_FALSE;
2795: PetscViewerFormat format;
2796: char *prefix;
2799: if (incall) return(0);
2800: incall = PETSC_TRUE;
2801: prefix = bobj ? bobj->prefix : obj->prefix;
2802: PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2803: if (flg) {
2804: PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2805: PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2806: PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2807: PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2808: }
2809: incall = PETSC_FALSE;
2810: return(0);
2811: }