Actual source code: options.c
petsc-3.9.4 2018-09-11
2: /* Define Feature test macros to make sure atoll is available (SVr4, POSIX.1-2001, 4.3BSD, C99), not in (C89 and POSIX.1-1996) */
3: #define PETSC_DESIRE_FEATURE_TEST_MACROS /* for atoll() */
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>
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: }
69: /*
70: PetscOptionsStringToInt - Converts a string to an integer value. Handles special cases such as "default" and "decide"
71: */
72: PetscErrorCode PetscOptionsStringToInt(const char name[],PetscInt *a)
73: {
75: size_t len;
76: PetscBool decide,tdefault,mouse;
79: PetscStrlen(name,&len);
80: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
82: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
83: if (!tdefault) {
84: PetscStrcasecmp(name,"DEFAULT",&tdefault);
85: }
86: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
87: if (!decide) {
88: PetscStrcasecmp(name,"DECIDE",&decide);
89: }
90: PetscStrcasecmp(name,"mouse",&mouse);
92: if (tdefault) *a = PETSC_DEFAULT;
93: else if (decide) *a = PETSC_DECIDE;
94: else if (mouse) *a = -1;
95: else {
96: char *endptr;
97: long strtolval;
99: strtolval = strtol(name,&endptr,10);
100: if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
102: #if defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE_ATOLL)
103: (void) strtolval;
104: *a = atoll(name);
105: #elif defined(PETSC_USE_64BIT_INDICES) && defined(PETSC_HAVE___INT64)
106: (void) strtolval;
107: *a = _atoi64(name);
108: #else
109: *a = (PetscInt)strtolval;
110: #endif
111: }
112: return(0);
113: }
115: #if defined(PETSC_USE_REAL___FLOAT128)
116: #include <quadmath.h>
117: #endif
119: static PetscErrorCode PetscStrtod(const char name[],PetscReal *a,char **endptr)
120: {
122: #if defined(PETSC_USE_REAL___FLOAT128)
123: *a = strtoflt128(name,endptr);
124: #else
125: *a = (PetscReal)strtod(name,endptr);
126: #endif
127: return(0);
128: }
130: static PetscErrorCode PetscStrtoz(const char name[],PetscScalar *a,char **endptr,PetscBool *isImaginary)
131: {
132: PetscBool hasi = PETSC_FALSE;
133: char *ptr;
134: PetscReal strtoval;
138: PetscStrtod(name,&strtoval,&ptr);
139: if (ptr == name) {
140: strtoval = 1.;
141: hasi = PETSC_TRUE;
142: if (name[0] == 'i') {
143: ptr++;
144: } else if (name[0] == '+' && name[1] == 'i') {
145: ptr += 2;
146: } else if (name[0] == '-' && name[1] == 'i') {
147: strtoval = -1.;
148: ptr += 2;
149: }
150: } else if (*ptr == 'i') {
151: hasi = PETSC_TRUE;
152: ptr++;
153: }
154: *endptr = ptr;
155: *isImaginary = hasi;
156: if (hasi) {
157: #if !defined(PETSC_USE_COMPLEX)
158: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s contains imaginary but complex not supported ",name);
159: #else
160: *a = PetscCMPLX(0.,strtoval);
161: #endif
162: } else {
163: *a = strtoval;
164: }
165: return(0);
166: }
168: /*
169: Converts a string to PetscReal value. Handles special cases like "default" and "decide"
170: */
171: PetscErrorCode PetscOptionsStringToReal(const char name[],PetscReal *a)
172: {
174: size_t len;
175: PetscBool decide,tdefault;
178: PetscStrlen(name,&len);
179: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
181: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
182: if (!tdefault) {
183: PetscStrcasecmp(name,"DEFAULT",&tdefault);
184: }
185: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
186: if (!decide) {
187: PetscStrcasecmp(name,"DECIDE",&decide);
188: }
190: if (tdefault) *a = PETSC_DEFAULT;
191: else if (decide) *a = PETSC_DECIDE;
192: else {
193: char *endptr;
195: PetscStrtod(name,a,&endptr);
196: if ((size_t) (endptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
197: }
198: return(0);
199: }
201: PetscErrorCode PetscOptionsStringToScalar(const char name[],PetscScalar *a)
202: {
203: PetscBool imag1;
204: size_t len;
205: PetscScalar val = 0.;
206: char *ptr = NULL;
210: PetscStrlen(name,&len);
211: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
212: PetscStrtoz(name,&val,&ptr,&imag1);
213: #if defined(PETSC_USE_COMPLEX)
214: if ((size_t) (ptr - name) < len) {
215: PetscBool imag2;
216: PetscScalar val2;
218: PetscStrtoz(ptr,&val2,&ptr,&imag2);
219: if (imag1 || !imag2) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s: must specify imaginary component second",name);
220: val = PetscCMPLX(PetscRealPart(val),PetscImaginaryPart(val2));
221: }
222: #endif
223: if ((size_t) (ptr - name) != len) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
224: *a = val;
225: return(0);
226: }
228: /*
229: PetscOptionsStringToBool - Converts string to PetscBool , handles cases like "yes", "no", "true", "false", "0", "1"
230: */
231: PetscErrorCode PetscOptionsStringToBool(const char value[], PetscBool *a)
232: {
233: PetscBool istrue, isfalse;
234: size_t len;
238: PetscStrlen(value, &len);
239: if (!len) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Character string of length zero has no logical value");
240: PetscStrcasecmp(value,"TRUE",&istrue);
241: if (istrue) {*a = PETSC_TRUE; return(0);}
242: PetscStrcasecmp(value,"YES",&istrue);
243: if (istrue) {*a = PETSC_TRUE; return(0);}
244: PetscStrcasecmp(value,"1",&istrue);
245: if (istrue) {*a = PETSC_TRUE; return(0);}
246: PetscStrcasecmp(value,"on",&istrue);
247: if (istrue) {*a = PETSC_TRUE; return(0);}
248: PetscStrcasecmp(value,"FALSE",&isfalse);
249: if (isfalse) {*a = PETSC_FALSE; return(0);}
250: PetscStrcasecmp(value,"NO",&isfalse);
251: if (isfalse) {*a = PETSC_FALSE; return(0);}
252: PetscStrcasecmp(value,"0",&isfalse);
253: if (isfalse) {*a = PETSC_FALSE; return(0);}
254: PetscStrcasecmp(value,"off",&isfalse);
255: if (isfalse) {*a = PETSC_FALSE; return(0);}
256: SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG, "Unknown logical value: %s", value);
257: }
259: /*@C
260: PetscGetProgramName - Gets the name of the running program.
262: Not Collective
264: Input Parameter:
265: . len - length of the string name
267: Output Parameter:
268: . name - the name of the running program
270: Level: advanced
272: Notes:
273: The name of the program is copied into the user-provided character
274: array of length len. On some machines the program name includes
275: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
276: @*/
277: PetscErrorCode PetscGetProgramName(char name[],size_t len)
278: {
282: PetscStrncpy(name,defaultoptions->programname,len);
283: return(0);
284: }
286: PetscErrorCode PetscSetProgramName(const char name[])
287: {
291: PetscStrncpy(defaultoptions->programname,name,PETSC_MAX_PATH_LEN);
292: return(0);
293: }
295: /*@C
296: PetscOptionsValidKey - PETSc Options database keys must begin with one or two dashes (-) followed by a letter.
298: Input Parameter:
299: . in_str - string to check if valid
301: Output Parameter:
302: . key - PETSC_TRUE if a valid key
304: Level: intermediate
306: @*/
307: PetscErrorCode PetscOptionsValidKey(const char in_str[],PetscBool *key)
308: {
309: char *ptr;
312: *key = PETSC_FALSE;
313: if (!in_str) return(0);
314: if (in_str[0] != '-') return(0);
315: if (in_str[1] == '-') in_str++;
316: if (!isalpha((int)(in_str[1]))) return(0);
317: (void) strtod(in_str,&ptr);
318: if (ptr != in_str && !(*ptr == '_' || isalnum((int)*ptr))) return(0);
319: *key = PETSC_TRUE;
320: return(0);
321: }
323: /*@C
324: PetscOptionsInsertString - Inserts options into the database from a string
326: Not collective: but only processes that call this routine will set the options
327: included in the string
329: Input Parameter:
330: . in_str - string that contains options separated by blanks
333: Level: intermediate
335: Contributed by Boyana Norris
337: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
338: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
339: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
340: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
341: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
342: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsInsertFile()
344: @*/
345: PetscErrorCode PetscOptionsInsertString(PetscOptions options,const char in_str[])
346: {
347: char *first,*second;
349: PetscToken token;
350: PetscBool key,ispush,ispop;
353: options = options ? options : defaultoptions;
354: PetscTokenCreate(in_str,' ',&token);
355: PetscTokenFind(token,&first);
356: while (first) {
357: PetscStrcasecmp(first,"-prefix_push",&ispush);
358: PetscStrcasecmp(first,"-prefix_pop",&ispop);
359: PetscOptionsValidKey(first,&key);
360: if (ispush) {
361: PetscTokenFind(token,&second);
362: PetscOptionsPrefixPush(options,second);
363: PetscTokenFind(token,&first);
364: } else if (ispop) {
365: PetscOptionsPrefixPop(options);
366: PetscTokenFind(token,&first);
367: } else if (key) {
368: PetscTokenFind(token,&second);
369: PetscOptionsValidKey(second,&key);
370: if (!key) {
371: PetscOptionsSetValue(options,first,second);
372: PetscTokenFind(token,&first);
373: } else {
374: PetscOptionsSetValue(options,first,NULL);
375: first = second;
376: }
377: } else {
378: PetscTokenFind(token,&first);
379: }
380: }
381: PetscTokenDestroy(&token);
382: return(0);
383: }
385: /*
386: Returns a line (ended by a \n, \r or null character of any length. Result should be freed with free()
387: */
388: static char *Petscgetline(FILE * f)
389: {
390: size_t size = 0;
391: size_t len = 0;
392: size_t last = 0;
393: char *buf = NULL;
395: if (feof(f)) return 0;
396: do {
397: size += 1024; /* BUFSIZ is defined as "the optimal read size for this platform" */
398: buf = (char*)realloc((void*)buf,size); /* realloc(NULL,n) is the same as malloc(n) */
399: /* Actually do the read. Note that fgets puts a terminal '\0' on the
400: end of the string, so we make sure we overwrite this */
401: if (!fgets(buf+len,size,f)) buf[len]=0;
402: PetscStrlen(buf,&len);
403: last = len - 1;
404: } while (!feof(f) && buf[last] != '\n' && buf[last] != '\r');
405: if (len) return buf;
406: free(buf);
407: return 0;
408: }
411: /*@C
412: PetscOptionsInsertFile - Inserts options into the database from a file.
414: Collective on MPI_Comm
416: Input Parameter:
417: + comm - the processes that will share the options (usually PETSC_COMM_WORLD)
418: . options - options database, use NULL for default global database
419: . file - name of file
420: - require - if PETSC_TRUE will generate an error if the file does not exist
423: Notes: Use # for lines that are comments and which should be ignored.
425: Usually, instead of using this command, one should list the file name in the call to PetscInitialize(), this insures that certain options
426: such as -log_view or -malloc_debug are processed properly. This routine only sets options into the options database that will be processed by later
427: calls to XXXSetFromOptions() it should not be used for options listed under PetscInitialize().
429: Level: developer
431: .seealso: PetscOptionsSetValue(), PetscOptionsView(), PetscOptionsHasName(), PetscOptionsGetInt(),
432: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
433: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
434: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
435: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
436: PetscOptionsFList(), PetscOptionsEList()
438: @*/
439: PetscErrorCode PetscOptionsInsertFile(MPI_Comm comm,PetscOptions options,const char file[],PetscBool require)
440: {
441: char *string,fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*vstring = 0,*astring = 0,*packed = 0;
443: size_t i,len,bytes;
444: FILE *fd;
445: PetscToken token;
446: int err;
447: char cmt[1]={'#'},*cmatch;
448: PetscMPIInt rank,cnt=0,acnt=0,counts[2];
449: PetscBool isdir;
452: options = options ? options : defaultoptions;
453: MPI_Comm_rank(comm,&rank);
454: if (!rank) {
455: cnt = 0;
456: acnt = 0;
458: PetscFixFilename(file,fname);
459: fd = fopen(fname,"r");
460: PetscTestDirectory(fname,'r',&isdir);
461: if (isdir && require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Specified options file %s is a directory",fname);
462: if (fd && !isdir) {
463: PetscSegBuffer vseg,aseg;
464: PetscSegBufferCreate(1,4000,&vseg);
465: PetscSegBufferCreate(1,2000,&aseg);
467: /* the following line will not work when opening initial files (like .petscrc) since info is not yet set */
468: PetscInfo1(0,"Opened options file %s\n",file);
470: while ((string = Petscgetline(fd))) {
471: /* eliminate comments from each line */
472: for (i=0; i<1; i++) {
473: PetscStrchr(string,cmt[i],&cmatch);
474: if (cmatch) *cmatch = 0;
475: }
476: PetscStrlen(string,&len);
477: /* replace tabs, ^M, \n with " " */
478: for (i=0; i<len; i++) {
479: if (string[i] == '\t' || string[i] == '\r' || string[i] == '\n') {
480: string[i] = ' ';
481: }
482: }
483: PetscTokenCreate(string,' ',&token);
484: PetscTokenFind(token,&first);
485: if (!first) {
486: goto destroy;
487: } else if (!first[0]) { /* if first token is empty spaces, redo first token */
488: PetscTokenFind(token,&first);
489: }
490: PetscTokenFind(token,&second);
491: if (!first) {
492: goto destroy;
493: } else if (first[0] == '-') {
494: PetscStrlen(first,&len);
495: PetscSegBufferGet(vseg,len+1,&vstring);
496: PetscMemcpy(vstring,first,len);
497: vstring[len] = ' ';
498: if (second) {
499: PetscStrlen(second,&len);
500: PetscSegBufferGet(vseg,len+3,&vstring);
501: vstring[0] = '"';
502: PetscMemcpy(vstring+1,second,len);
503: vstring[len+1] = '"';
504: vstring[len+2] = ' ';
505: }
506: } else {
507: PetscBool match;
509: PetscStrcasecmp(first,"alias",&match);
510: if (match) {
511: PetscTokenFind(token,&third);
512: if (!third) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
513: PetscStrlen(second,&len);
514: PetscSegBufferGet(aseg,len+1,&astring);
515: PetscMemcpy(astring,second,len);
516: astring[len] = ' ';
518: PetscStrlen(third,&len);
519: PetscSegBufferGet(aseg,len+1,&astring);
520: PetscMemcpy(astring,third,len);
521: astring[len] = ' ';
522: } else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Unknown statement in options file: (%s)",string);
523: }
524: destroy:
525: free(string);
526: PetscTokenDestroy(&token);
527: }
528: err = fclose(fd);
529: if (err) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_SYS,"fclose() failed on file");
530: PetscSegBufferGetSize(aseg,&bytes); /* size without null termination */
531: PetscMPIIntCast(bytes,&acnt);
532: PetscSegBufferGet(aseg,1,&astring);
533: astring[0] = 0;
534: PetscSegBufferGetSize(vseg,&bytes); /* size without null termination */
535: PetscMPIIntCast(bytes,&cnt);
536: PetscSegBufferGet(vseg,1,&vstring);
537: vstring[0] = 0;
538: PetscMalloc1(2+acnt+cnt,&packed);
539: PetscSegBufferExtractTo(aseg,packed);
540: PetscSegBufferExtractTo(vseg,packed+acnt+1);
541: PetscSegBufferDestroy(&aseg);
542: PetscSegBufferDestroy(&vseg);
543: } else if (require) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_USER,"Unable to open Options File %s",fname);
544: }
546: counts[0] = acnt;
547: counts[1] = cnt;
548: MPI_Bcast(counts,2,MPI_INT,0,comm);
549: acnt = counts[0];
550: cnt = counts[1];
551: if (rank) {
552: PetscMalloc1(2+acnt+cnt,&packed);
553: }
554: if (acnt || cnt) {
555: MPI_Bcast(packed,2+acnt+cnt,MPI_CHAR,0,comm);
556: astring = packed;
557: vstring = packed + acnt + 1;
558: }
560: if (acnt) {
561: PetscToken token;
562: char *first,*second;
564: PetscTokenCreate(astring,' ',&token);
565: PetscTokenFind(token,&first);
566: while (first) {
567: PetscTokenFind(token,&second);
568: PetscOptionsSetAlias(options,first,second);
569: PetscTokenFind(token,&first);
570: }
571: PetscTokenDestroy(&token);
572: }
574: if (cnt) {
575: PetscOptionsInsertString(options,vstring);
576: }
577: PetscFree(packed);
578: return(0);
579: }
581: static PetscErrorCode PetscOptionsInsertArgs_Private(PetscOptions options,int argc,char *args[])
582: {
584: int left = argc - 1;
585: char **eargs = args + 1;
588: options = options ? options : defaultoptions;
589: while (left) {
590: PetscBool isoptions_file,isprefixpush,isprefixpop,isp4,tisp4,isp4yourname,isp4rmrank,key;
591: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
592: PetscStrcasecmp(eargs[0],"-prefix_push",&isprefixpush);
593: PetscStrcasecmp(eargs[0],"-prefix_pop",&isprefixpop);
594: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
595: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
596: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
597: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
598: isp4 = (PetscBool) (isp4 || tisp4);
599: PetscStrcasecmp(eargs[0],"-np",&tisp4);
600: isp4 = (PetscBool) (isp4 || tisp4);
601: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
602: PetscOptionsValidKey(eargs[0],&key);
604: if (!key) {
605: eargs++; left--;
606: } else if (isoptions_file) {
607: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
608: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing filename for -options_file filename option");
609: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,eargs[1],PETSC_TRUE);
610: eargs += 2; left -= 2;
611: } else if (isprefixpush) {
612: if (left <= 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option");
613: if (eargs[1][0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_USER,"Missing prefix for -prefix_push option (prefixes cannot start with '-')");
614: PetscOptionsPrefixPush(options,eargs[1]);
615: eargs += 2; left -= 2;
616: } else if (isprefixpop) {
617: PetscOptionsPrefixPop(options);
618: eargs++; left--;
620: /*
621: These are "bad" options that MPICH, etc put on the command line
622: we strip them out here.
623: */
624: } else if (tisp4 || isp4rmrank) {
625: eargs += 1; left -= 1;
626: } else if (isp4 || isp4yourname) {
627: eargs += 2; left -= 2;
628: } else {
629: PetscBool nextiskey = PETSC_FALSE;
630: if (left >= 2) {PetscOptionsValidKey(eargs[1],&nextiskey);}
631: if (left < 2 || nextiskey) {
632: PetscOptionsSetValue(options,eargs[0],NULL);
633: eargs++; left--;
634: } else {
635: PetscOptionsSetValue(options,eargs[0],eargs[1]);
636: eargs += 2; left -= 2;
637: }
638: }
639: }
640: return(0);
641: }
644: /*@C
645: PetscOptionsInsert - Inserts into the options database from the command line,
646: the environmental variable and a file.
648: Input Parameters:
649: + options - options database or NULL for the default global database
650: . argc - count of number of command line arguments
651: . args - the command line arguments
652: - file - optional filename, defaults to ~username/.petscrc
654: Note:
655: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
656: the user does not typically need to call this routine. PetscOptionsInsert()
657: can be called several times, adding additional entries into the database.
659: Options Database Keys:
660: + -options_monitor <optional filename> - print options names and values as they are set
661: . -options_file <filename> - read options from a file
663: Level: advanced
665: Concepts: options database^adding
667: .seealso: PetscOptionsDestroy_Private(), PetscOptionsView(), PetscOptionsInsertString(), PetscOptionsInsertFile(),
668: PetscInitialize()
669: @*/
670: PetscErrorCode PetscOptionsInsert(PetscOptions options,int *argc,char ***args,const char file[])
671: {
673: PetscMPIInt rank;
674: char pfile[PETSC_MAX_PATH_LEN];
675: PetscBool flag = PETSC_FALSE;
677:
679: if (!options) {
680: if (!defaultoptions) {
681: PetscOptionsCreateDefault();
682: }
683: options = defaultoptions;
684: }
685: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
687: options->argc = (argc) ? *argc : 0;
688: options->args = (args) ? *args : NULL;
690: if (file && file[0]) {
691: char fullpath[PETSC_MAX_PATH_LEN];
693: PetscStrreplace(PETSC_COMM_WORLD,file,fullpath,PETSC_MAX_PATH_LEN);
694: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,fullpath,PETSC_TRUE);
695: }
696: /*
697: We want to be able to give -skip_petscrc on the command line, but need to parse it first. Since the command line
698: should take precedence, we insert it twice. It would be sufficient to just scan for -skip_petscrc.
699: */
700: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
701: PetscOptionsGetBool(NULL,NULL,"-skip_petscrc",&flag,NULL);
702: if (!flag) {
703: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
704: /* PetscOptionsInsertFile() does a fopen() on rank0 only - so only rank0 HomeDir value is relavent */
705: if (pfile[0]) { PetscStrcat(pfile,"/.petscrc"); }
706: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,pfile,PETSC_FALSE);
707: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,".petscrc",PETSC_FALSE);
708: PetscOptionsInsertFile(PETSC_COMM_WORLD,options,"petscrc",PETSC_FALSE);
709: }
711: /* insert environmental options */
712: {
713: char *eoptions = 0;
714: size_t len = 0;
715: if (!rank) {
716: eoptions = (char*)getenv("PETSC_OPTIONS");
717: PetscStrlen(eoptions,&len);
718: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
719: } else {
720: MPI_Bcast(&len,1,MPIU_SIZE_T,0,PETSC_COMM_WORLD);
721: if (len) {
722: PetscMalloc1(len+1,&eoptions);
723: }
724: }
725: if (len) {
726: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
727: if (rank) eoptions[len] = 0;
728: PetscOptionsInsertString(options,eoptions);
729: if (rank) {PetscFree(eoptions);}
730: }
731: }
733: #if defined(PETSC_HAVE_YAML)
734: {
735: char yaml_file[PETSC_MAX_PATH_LEN];
736: PetscBool yaml_flg;
737: PetscOptionsGetString(NULL,NULL,"-options_file_yaml",yaml_file,PETSC_MAX_PATH_LEN,&yaml_flg);
738: if (yaml_flg) {
739: PetscOptionsInsertFileYAML(PETSC_COMM_WORLD,yaml_file,PETSC_TRUE);
740: }
741: }
742: #endif
744: /* insert command line options again because they take precedence over arguments in petscrc/environment */
745: if (argc && args && *argc) {PetscOptionsInsertArgs_Private(options,*argc,*args);}
746: return(0);
747: }
749: /*@C
750: PetscOptionsView - Prints the options that have been loaded. This is
751: useful for debugging purposes.
753: Logically Collective on PetscViewer
755: Input Parameter:
756: - options - options database, use NULL for default global database
757: + viewer - must be an PETSCVIEWERASCII viewer
759: Options Database Key:
760: . -options_view - Activates PetscOptionsView() within PetscFinalize()
762: Level: advanced
764: Concepts: options database^printing
766: .seealso: PetscOptionsAllUsed()
767: @*/
768: PetscErrorCode PetscOptionsView(PetscOptions options,PetscViewer viewer)
769: {
771: PetscInt i;
772: PetscBool isascii;
775: options = options ? options : defaultoptions;
776: if (!viewer) viewer = PETSC_VIEWER_STDOUT_WORLD;
777: PetscObjectTypeCompare((PetscObject)viewer,PETSCVIEWERASCII,&isascii);
778: if (!isascii) SETERRQ(PetscObjectComm((PetscObject)viewer),PETSC_ERR_SUP,"Only supports ASCII viewer");
780: if (options->N) {
781: PetscViewerASCIIPrintf(viewer,"#PETSc Option Table entries:\n");
782: } else {
783: PetscViewerASCIIPrintf(viewer,"#No PETSc Option Table entries\n");
784: }
785: for (i=0; i<options->N; i++) {
786: if (options->values[i]) {
787: PetscViewerASCIIPrintf(viewer,"-%s %s\n",options->names[i],options->values[i]);
788: } else {
789: PetscViewerASCIIPrintf(viewer,"-%s\n",options->names[i]);
790: }
791: }
792: if (options->N) {
793: PetscViewerASCIIPrintf(viewer,"#End of PETSc Option Table entries\n");
794: }
795: return(0);
796: }
798: /*
799: Called by error handlers to print options used in run
800: */
801: PetscErrorCode PetscOptionsViewError(void)
802: {
803: PetscInt i;
804: PetscOptions options = defaultoptions;
807: if (options->N) {
808: (*PetscErrorPrintf)("PETSc Option Table entries:\n");
809: } else {
810: (*PetscErrorPrintf)("No PETSc Option Table entries\n");
811: }
812: for (i=0; i<options->N; i++) {
813: if (options->values[i]) {
814: (*PetscErrorPrintf)("-%s %s\n",options->names[i],options->values[i]);
815: } else {
816: (*PetscErrorPrintf)("-%s\n",options->names[i]);
817: }
818: }
819: return(0);
820: }
822: /*@C
823: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
825: Not Collective
827: Input Paramter:
828: . options - the options database, use NULL for the default global database
830: Output Parameter:
831: . copts - pointer where string pointer is stored
833: Notes: the array and each entry in the array should be freed with PetscFree()
835: Level: advanced
837: Concepts: options database^listing
839: .seealso: PetscOptionsAllUsed(), PetscOptionsView()
840: @*/
841: PetscErrorCode PetscOptionsGetAll(PetscOptions options,char *copts[])
842: {
844: PetscInt i;
845: size_t len = 1,lent = 0;
846: char *coptions = NULL;
849: options = options ? options : defaultoptions;
851: /* count the length of the required string */
852: for (i=0; i<options->N; i++) {
853: PetscStrlen(options->names[i],&lent);
854: len += 2 + lent;
855: if (options->values[i]) {
856: PetscStrlen(options->values[i],&lent);
857: len += 1 + lent;
858: }
859: }
860: PetscMalloc1(len,&coptions);
861: coptions[0] = 0;
862: for (i=0; i<options->N; i++) {
863: PetscStrcat(coptions,"-");
864: PetscStrcat(coptions,options->names[i]);
865: PetscStrcat(coptions," ");
866: if (options->values[i]) {
867: PetscStrcat(coptions,options->values[i]);
868: PetscStrcat(coptions," ");
869: }
870: }
871: *copts = coptions;
872: return(0);
873: }
875: /*@C
876: PetscOptionsPrefixPush - Designate a prefix to be used by all options insertions to follow.
878: Not Collective, but prefix will only be applied on calling ranks
880: Input Parameter:
881: + options - options database, or NULL for the default global database
882: - prefix - The string to append to the existing prefix
884: Options Database Keys:
885: + -prefix_push <some_prefix_> - push the given prefix
886: - -prefix_pop - pop the last prefix
888: Notes:
889: It is common to use this in conjunction with -options_file as in
891: $ -prefix_push system1_ -options_file system1rc -prefix_pop -prefix_push system2_ -options_file system2rc -prefix_pop
893: where the files no longer require all options to be prefixed with -system2_.
895: Level: advanced
897: .seealso: PetscOptionsPrefixPop()
898: @*/
899: PetscErrorCode PetscOptionsPrefixPush(PetscOptions options,const char prefix[])
900: {
902: size_t n;
903: PetscInt start;
904: char buf[2048];
905: PetscBool key;
909: options = options ? options : defaultoptions;
910: /* Want to check validity of the key using PetscOptionsValidKey(), which requires that the first character is a '-' */
911: buf[0] = '-';
912: PetscStrncpy(buf+1,prefix,sizeof(buf) - 1);
913: buf[sizeof(buf) - 1] = 0;
914: PetscOptionsValidKey(buf,&key);
915: 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);
917: if (!options) {
918: PetscOptionsInsert(NULL,0,0,0);
919: options = defaultoptions;
920: }
921: 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);
922: start = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
923: PetscStrlen(prefix,&n);
924: if (n+1 > sizeof(options->prefix)-start) SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_PLIB,"Maximum prefix length %d exceeded",sizeof(options->prefix));
925: PetscMemcpy(options->prefix+start,prefix,n+1);
926: options->prefixstack[options->prefixind++] = start+n;
927: return(0);
928: }
930: /*@C
931: PetscOptionsPrefixPop - Remove the latest options prefix, see PetscOptionsPrefixPush() for details
933: Not Collective, but prefix will only be popped on calling ranks
935: Input Parameters:
936: . options - options database, or NULL for the default global database
938: Level: advanced
940: .seealso: PetscOptionsPrefixPush()
941: @*/
942: PetscErrorCode PetscOptionsPrefixPop(PetscOptions options)
943: {
944: PetscInt offset;
947: options = options ? options : defaultoptions;
948: if (options->prefixind < 1) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONGSTATE,"More prefixes popped than pushed");
949: options->prefixind--;
950: offset = options->prefixind ? options->prefixstack[options->prefixind-1] : 0;
951: options->prefix[offset] = 0;
952: return(0);
953: }
955: /*@C
956: PetscOptionsClear - Removes all options form the database leaving it empty.
958: Input Parameters:
959: . options - options database, use NULL for the default global database
961: Level: developer
963: .seealso: PetscOptionsInsert()
964: @*/
965: PetscErrorCode PetscOptionsClear(PetscOptions options)
966: {
967: PetscInt i;
970: options = options ? options : defaultoptions;
971: for (i=0; i<options->N; i++) {
972: if (options->names[i]) free(options->names[i]);
973: if (options->values[i]) free(options->values[i]);
974: }
975: for (i=0; i<options->Naliases; i++) {
976: free(options->aliases1[i]);
977: free(options->aliases2[i]);
978: }
979: options->prefix[0] = 0;
980: options->prefixind = 0;
981: options->N = 0;
982: options->Naliases = 0;
983: return(0);
984: }
986: /*@
987: PetscObjectSetPrintedOptions - indicate to an object that it should behave as if it has already printed the help for its options
989: Input Parameters:
990: . obj - the PetscObject
992: Level: developer
994: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
995: PCBJACOBI from all printing the same help messages to the screen
997: .seealso: PetscOptionsInsert()
998: @*/
999: PetscErrorCode PetscObjectSetPrintedOptions(PetscObject obj)
1000: {
1002: obj->optionsprinted = PETSC_TRUE;
1003: return(0);
1004: }
1006: /*@
1007: 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.
1009: Input Parameters:
1010: + pobj - the parent object
1011: - obj - the PetscObject
1013: Level: developer
1015: Developer Notes: This is used, for example to prevent sequential objects that are created from a parallel object; such as the KSP created by
1016: PCBJACOBI from all printing the same help messages to the screen
1018: This will not handle more complicated situations like with GASM where children may live on any subset of the parent's processes and overlap
1020: .seealso: PetscOptionsInsert(), PetscObjectSetPrintedOptions()
1021: @*/
1022: PetscErrorCode PetscObjectInheritPrintedOptions(PetscObject pobj,PetscObject obj)
1023: {
1025: PetscMPIInt prank,size;
1028: MPI_Comm_rank(pobj->comm,&prank);
1029: MPI_Comm_size(obj->comm,&size);
1030: if (size == 1 && prank > 0) obj->optionsprinted = PETSC_TRUE;
1031: return(0);
1032: }
1034: /*@
1035: PetscOptionsDestroy - Destroys an option database.
1037: Input Parameter:
1038: . options - the PetscOptions object
1040: Level: developer
1042: .seealso: PetscOptionsInsert()
1043: @*/
1044: PetscErrorCode PetscOptionsDestroy(PetscOptions *options)
1045: {
1049: PetscOptionsClear(*options);
1050: free(*options);
1051: *options = NULL;
1052: return(0);
1053: }
1055: PetscErrorCode PetscOptionsDestroyDefault(void)
1056: {
1059: PetscOptionsDestroy(&defaultoptions);if (ierr) return ierr;
1060: return 0;
1061: }
1064: /*@C
1065: PetscOptionsSetValue - Sets an option name-value pair in the options
1066: database, overriding whatever is already present.
1068: Not collective, but setting values on certain processors could cause problems
1069: for parallel objects looking for options.
1071: Input Parameters:
1072: + options - options database, use NULL for the default global database
1073: . name - name of option, this SHOULD have the - prepended
1074: - value - the option value (not used for all options)
1076: Level: intermediate
1078: Note:
1079: This function can be called BEFORE PetscInitialize()
1081: Only some options have values associated with them, such as
1082: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
1084: Developers Note: Uses malloc() directly because PETSc may not yet have been fully initialized
1086: Concepts: options database^adding option
1088: .seealso: PetscOptionsInsert()
1089: @*/
1090: PetscErrorCode PetscOptionsSetValue(PetscOptions options,const char iname[],const char value[])
1091: {
1092: size_t len;
1094: PetscInt N,n,i;
1095: char **names;
1096: char fullname[2048];
1097: const char *name = iname;
1098: int match;
1100: if (!options) {
1101: if (!defaultoptions) {
1102: PetscOptionsCreateDefault();
1103: if (ierr) return ierr;
1104: }
1105: options = defaultoptions;
1106: }
1108: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
1109: match = strcmp(name,"-h");
1110: if (!match) name = "-help";
1112: name++; /* skip starting hyphen */
1113: if (options->prefixind > 0) {
1114: strncpy(fullname,options->prefix,sizeof(fullname));
1115: strncat(fullname,name,sizeof(fullname)-strlen(fullname)-1);
1116: name = fullname;
1117: }
1119: /* check against aliases */
1120: N = options->Naliases;
1121: for (i=0; i<N; i++) {
1122: #if defined(PETSC_HAVE_STRCASECMP)
1123: match = strcasecmp(options->aliases1[i],name);
1124: #elif defined(PETSC_HAVE_STRICMP)
1125: match = stricmp(options->aliases1[i],name);
1126: #else
1127: Error
1128: #endif
1129: if (!match) {
1130: name = options->aliases2[i];
1131: break;
1132: }
1133: }
1135: N = options->N;
1136: n = N;
1137: names = options->names;
1139: for (i=0; i<N; i++) {
1140: #if defined(PETSC_HAVE_STRCASECMP)
1141: match = strcasecmp(names[i],name);
1142: #elif defined(PETSC_HAVE_STRICMP)
1143: match = stricmp(names[i],name);
1144: #else
1145: Error
1146: #endif
1147: if (!match) {
1148: if (options->values[i]) free(options->values[i]);
1149: len = value ? strlen(value) : 0;
1150: if (len) {
1151: options->values[i] = (char*)malloc((len+1)*sizeof(char));
1152: if (!options->values[i]) return PETSC_ERR_MEM;
1153: strcpy(options->values[i],value);
1154: } else options->values[i] = 0;
1155: return 0;
1156: } else if (strcmp(names[i],name) > 0) {
1157: n = i;
1158: break;
1159: }
1160: }
1161: if (N >= MAXOPTIONS) abort();
1163: /* shift remaining values down 1 */
1164: for (i=N; i>n; i--) {
1165: options->names[i] = options->names[i-1];
1166: options->values[i] = options->values[i-1];
1167: options->used[i] = options->used[i-1];
1168: }
1169: /* insert new name and value */
1170: len = strlen(name);
1171: options->names[n] = (char*)malloc((len+1)*sizeof(char));
1172: if (!options->names[n]) return PETSC_ERR_MEM;
1173: strcpy(options->names[n],name);
1174: len = value ? strlen(value) : 0;
1175: if (len) {
1176: options->values[n] = (char*)malloc((len+1)*sizeof(char));
1177: if (!options->values[n]) return PETSC_ERR_MEM;
1178: strcpy(options->values[n],value);
1179: } else options->values[n] = NULL;
1180: options->used[n] = PETSC_FALSE;
1181: options->N++;
1182: return 0;
1183: }
1185: /*@C
1186: PetscOptionsClearValue - Clears an option name-value pair in the options
1187: database, overriding whatever is already present.
1189: Not Collective, but setting values on certain processors could cause problems
1190: for parallel objects looking for options.
1192: Input Parameter:
1193: + options - options database, use NULL for the default global database
1194: . name - name of option, this SHOULD have the - prepended
1196: Level: intermediate
1198: Concepts: options database^removing option
1199: .seealso: PetscOptionsInsert()
1200: @*/
1201: PetscErrorCode PetscOptionsClearValue(PetscOptions options,const char iname[])
1202: {
1204: PetscInt N,n,i;
1205: char **names,*name=(char*)iname;
1206: PetscBool gt,match;
1209: options = options ? options : defaultoptions;
1210: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1211: name++;
1213: N = options->N; n = 0;
1214: names = options->names;
1216: for (i=0; i<N; i++) {
1217: PetscStrcasecmp(names[i],name,&match);
1218: PetscStrgrt(names[i],name,>);
1219: if (match) {
1220: if (options->names[i]) free(options->names[i]);
1221: if (options->values[i]) free(options->values[i]);
1222: PetscOptionsMonitor(name,"");
1223: break;
1224: } else if (gt) return(0); /* it was not listed */
1226: n++;
1227: }
1228: if (n == N) return(0); /* it was not listed */
1230: /* shift remaining values down 1 */
1231: for (i=n; i<N-1; i++) {
1232: options->names[i] = options->names[i+1];
1233: options->values[i] = options->values[i+1];
1234: options->used[i] = options->used[i+1];
1235: }
1236: options->N--;
1237: return(0);
1238: }
1240: /*@C
1241: PetscOptionsSetAlias - Makes a key and alias for another key
1243: Not Collective, but setting values on certain processors could cause problems
1244: for parallel objects looking for options.
1246: Input Parameters:
1247: + options - options database or NULL for default global database
1248: . inewname - the alias
1249: - ioldname - the name that alias will refer to
1251: Level: advanced
1253: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1254: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1255: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1256: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1257: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1258: PetscOptionsFList(), PetscOptionsEList()
1259: @*/
1260: PetscErrorCode PetscOptionsSetAlias(PetscOptions options,const char inewname[],const char ioldname[])
1261: {
1263: PetscInt n = options->Naliases;
1264: size_t len;
1265: char *newname = (char*)inewname,*oldname = (char*)ioldname;
1268: options = options ? options : defaultoptions;
1269: if (newname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
1270: if (oldname[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
1271: 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);
1273: newname++; oldname++;
1274: PetscStrlen(newname,&len);
1275: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
1276: PetscStrcpy(options->aliases1[n],newname);
1277: PetscStrlen(oldname,&len);
1278: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
1279: PetscStrcpy(options->aliases2[n],oldname);
1280: options->Naliases++;
1281: return(0);
1282: }
1284: PetscErrorCode PetscOptionsFindPair_Private(PetscOptions options,const char pre[],const char name[],char *value[],PetscBool *flg)
1285: {
1287: PetscInt i,N;
1288: size_t len;
1289: char **names,tmp[512];
1290: PetscBool match;
1293: options = options ? options : defaultoptions;
1294: N = options->N;
1295: names = options->names;
1297: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1299: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1300: if (pre) {
1301: char *ptr = tmp;
1302: const char *namep = name;
1303: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1304: if (name[1] == '-') {
1305: *ptr++ = '-';
1306: namep++;
1307: }
1308: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1309: tmp[sizeof(tmp)-1] = 0;
1310: PetscStrlen(tmp,&len);
1311: PetscStrlcat(tmp,namep+1,sizeof(tmp));
1312: } else {
1313: PetscStrncpy(tmp,name+1,sizeof(tmp));
1314: tmp[sizeof(tmp)-1] = 0;
1315: }
1316: #if defined(PETSC_USE_DEBUG)
1317: {
1318: PetscBool valid;
1319: char key[sizeof(tmp)+1] = "-";
1321: PetscMemcpy(key+1,tmp,sizeof(tmp));
1322: PetscOptionsValidKey(key,&valid);
1323: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1324: }
1325: #endif
1327: /* slow search */
1328: *flg = PETSC_FALSE;
1329: for (i=0; i<N; i++) {
1330: PetscStrcasecmp(names[i],tmp,&match);
1331: if (match) {
1332: *value = options->values[i];
1333: options->used[i] = PETSC_TRUE;
1334: *flg = PETSC_TRUE;
1335: break;
1336: }
1337: }
1338: if (!*flg) {
1339: PetscInt j,cnt = 0,locs[16],loce[16];
1340: size_t n;
1341: PetscStrlen(tmp,&n);
1342: /* determine the location and number of all _%d_ in the key */
1343: for (i=0; i< (PetscInt)n; i++) {
1344: if (tmp[i] == '_') {
1345: for (j=i+1; j< (PetscInt)n; j++) {
1346: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
1347: if (tmp[j] == '_' && j > i+1) { /* found a number */
1348: locs[cnt] = i+1;
1349: loce[cnt++] = j+1;
1350: }
1351: break;
1352: }
1353: }
1354: }
1355: if (cnt) {
1356: char tmp2[512],tmp3[512];
1357: for (i=0; i<cnt; i++) {
1358: PetscStrcpy(tmp2,"-");
1359: PetscStrncpy(tmp3,tmp,locs[i]+1);
1360: PetscStrlcat(tmp2,tmp3,sizeof(tmp2));
1361: PetscStrlcat(tmp2,tmp+loce[i],sizeof(tmp2));
1362: PetscOptionsFindPair_Private(options,NULL,tmp2,value,flg);
1363: if (*flg) break;
1364: }
1365: }
1366: }
1367: return(0);
1368: }
1370: PETSC_EXTERN PetscErrorCode PetscOptionsFindPairPrefix_Private(PetscOptions options,const char pre[], const char name[], char *value[], PetscBool *flg)
1371: {
1373: PetscInt i,N;
1374: size_t len;
1375: char **names,tmp[512];
1376: PetscBool match;
1379: options = options ? options : defaultoptions;
1380: N = options->N;
1381: names = options->names;
1383: if (name[0] != '-') SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
1385: /* append prefix to name, if prefix="foo_" and option='--bar", prefixed option is --foo_bar */
1386: if (pre) {
1387: char *ptr = tmp;
1388: const char *namep = name;
1389: if (pre[0] == '-') SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
1390: if (name[1] == '-') {
1391: *ptr++ = '-';
1392: namep++;
1393: }
1394: PetscStrncpy(ptr,pre,tmp+sizeof(tmp)-ptr);
1395: tmp[sizeof(tmp)-1] = 0;
1396: PetscStrlen(tmp,&len);
1397: PetscStrlcat(tmp,namep+1,sizeof(tmp));
1398: } else {
1399: PetscStrncpy(tmp,name+1,sizeof(tmp));
1400: tmp[sizeof(tmp)-1] = 0;
1401: }
1402: #if defined(PETSC_USE_DEBUG)
1403: {
1404: PetscBool valid;
1405: char key[sizeof(tmp)+1] = "-";
1407: PetscMemcpy(key+1,tmp,sizeof(tmp));
1408: PetscOptionsValidKey(key,&valid);
1409: if (!valid) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"Invalid option '%s' obtained from pre='%s' and name='%s'",key,pre?pre:"",name);
1410: }
1411: #endif
1413: /* slow search */
1414: *flg = PETSC_FALSE;
1415: PetscStrlen(tmp,&len);
1416: for (i = 0; i < N; ++i) {
1417: PetscStrncmp(names[i], tmp, len, &match);
1418: if (match) {
1419: if (value) *value = options->values[i];
1420: options->used[i] = PETSC_TRUE;
1421: if (flg) *flg = PETSC_TRUE;
1422: break;
1423: }
1424: }
1425: return(0);
1426: }
1428: /*@C
1429: PetscOptionsReject - Generates an error if a certain option is given.
1431: Not Collective, but setting values on certain processors could cause problems
1432: for parallel objects looking for options.
1434: Input Parameters:
1435: + options - options database, use NULL for default global database
1436: . name - the option one is seeking
1437: - mess - error message (may be NULL)
1439: Level: advanced
1441: Concepts: options database^rejecting option
1443: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
1444: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1445: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1446: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1447: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1448: PetscOptionsFList(), PetscOptionsEList()
1449: @*/
1450: PetscErrorCode PetscOptionsReject(PetscOptions options,const char name[],const char mess[])
1451: {
1453: PetscBool flag = PETSC_FALSE;
1456: options = options ? options : defaultoptions;
1457: PetscOptionsHasName(options,NULL,name,&flag);
1458: if (flag) {
1459: if (mess) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
1460: else SETERRQ1(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
1461: }
1462: return(0);
1463: }
1465: /*@C
1466: PetscOptionsHasName - Determines whether a certain option is given in the database. This returns true whether the option is a number, string or boolean, even
1467: its value is set to false.
1469: Not Collective
1471: Input Parameters:
1472: + options - options database, use NULL for default global database
1473: . pre - string to prepend to the name or NULL
1474: - name - the option one is seeking
1476: Output Parameters:
1477: . set - PETSC_TRUE if found else PETSC_FALSE.
1479: Level: beginner
1481: Concepts: options database^has option name
1483: Notes: Name cannot be simply -h
1485: In many cases you probably want to use PetscOptionsGetBool() instead of calling this, to allowing toggling values.
1487: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1488: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1489: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1490: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1491: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1492: PetscOptionsFList(), PetscOptionsEList()
1493: @*/
1494: PetscErrorCode PetscOptionsHasName(PetscOptions options,const char pre[],const char name[],PetscBool *set)
1495: {
1496: char *value;
1498: PetscBool flag;
1501: options = options ? options : defaultoptions;
1502: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1503: if (set) *set = flag;
1504: return(0);
1505: }
1507: /*@C
1508: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
1510: Not Collective
1512: Input Parameters:
1513: + options - options database, use NULL for default global database
1514: . pre - the string to prepend to the name or NULL
1515: - name - the option one is seeking
1517: Output Parameter:
1518: + ivalue - the integer value to return
1519: - set - PETSC_TRUE if found, else PETSC_FALSE
1521: Level: beginner
1523: Notes: If the user does not supply the option ivalue is NOT changed. Thus
1524: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1526: Concepts: options database^has int
1528: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1529: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1530: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1531: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1532: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1533: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1534: PetscOptionsFList(), PetscOptionsEList()
1535: @*/
1536: PetscErrorCode PetscOptionsGetInt(PetscOptions options,const char pre[],const char name[],PetscInt *ivalue,PetscBool *set)
1537: {
1538: char *value;
1540: PetscBool flag;
1545: options = options ? options : defaultoptions;
1546: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1547: if (flag) {
1548: if (!value) {
1549: if (set) *set = PETSC_FALSE;
1550: } else {
1551: if (set) *set = PETSC_TRUE;
1552: PetscOptionsStringToInt(value,ivalue);
1553: }
1554: } else {
1555: if (set) *set = PETSC_FALSE;
1556: }
1557: return(0);
1558: }
1560: /*@C
1561: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
1563: Not Collective
1565: Input Parameters:
1566: + options - options database, use NULL for default global database
1567: . pre - the string to prepend to the name or NULL
1568: . opt - option name
1569: . list - the possible choices (one of these must be selected, anything else is invalid)
1570: . ntext - number of choices
1572: Output Parameter:
1573: + value - the index of the value to return (defaults to zero if the option name is given but no choice is listed)
1574: - set - PETSC_TRUE if found, else PETSC_FALSE
1576: Level: intermediate
1578: Notes: If the user does not supply the option value is NOT changed. Thus
1579: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1581: See PetscOptionsFList() for when the choices are given in a PetscFunctionList()
1583: Concepts: options database^list
1585: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1586: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1587: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1588: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1589: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1590: PetscOptionsFList(), PetscOptionsEList()
1591: @*/
1592: PetscErrorCode PetscOptionsGetEList(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscInt ntext,PetscInt *value,PetscBool *set)
1593: {
1595: size_t alen,len = 0;
1596: char *svalue;
1597: PetscBool aset,flg = PETSC_FALSE;
1598: PetscInt i;
1601: options = options ? options : defaultoptions;
1602: for (i=0; i<ntext; i++) {
1603: PetscStrlen(list[i],&alen);
1604: if (alen > len) len = alen;
1605: }
1606: len += 5; /* a little extra space for user mistypes */
1607: PetscMalloc1(len,&svalue);
1608: PetscOptionsGetString(options,pre,opt,svalue,len,&aset);
1609: if (aset) {
1610: PetscEListFind(ntext,list,svalue,value,&flg);
1611: if (!flg) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre ? pre : "",opt+1);
1612: if (set) *set = PETSC_TRUE;
1613: } else if (set) *set = PETSC_FALSE;
1614: PetscFree(svalue);
1615: return(0);
1616: }
1618: /*@C
1619: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1621: Not Collective
1623: Input Parameters:
1624: + options - options database, use NULL for default global database
1625: . pre - option prefix or NULL
1626: . opt - option name
1627: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1628: - defaultv - the default (current) value
1630: Output Parameter:
1631: + value - the value to return
1632: - set - PETSC_TRUE if found, else PETSC_FALSE
1634: Level: beginner
1636: Concepts: options database
1638: Notes: If the user does not supply the option value is NOT changed. Thus
1639: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1641: List is usually something like PCASMTypes or some other predefined list of enum names
1643: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1644: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
1645: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(),
1646: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1647: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1648: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1649: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1650: @*/
1651: PetscErrorCode PetscOptionsGetEnum(PetscOptions options,const char pre[],const char opt[],const char * const *list,PetscEnum *value,PetscBool *set)
1652: {
1654: PetscInt ntext = 0,tval;
1655: PetscBool fset;
1658: options = options ? options : defaultoptions;
1659: while (list[ntext++]) {
1660: if (ntext > 50) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1661: }
1662: if (ntext < 3) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1663: ntext -= 3;
1664: PetscOptionsGetEList(options,pre,opt,list,ntext,&tval,&fset);
1665: /* with PETSC_USE_64BIT_INDICES sizeof(PetscInt) != sizeof(PetscEnum) */
1666: if (fset) *value = (PetscEnum)tval;
1667: if (set) *set = fset;
1668: return(0);
1669: }
1671: /*@C
1672: PetscOptionsGetBool - Gets the Logical (true or false) value for a particular
1673: option in the database.
1675: Not Collective
1677: Input Parameters:
1678: + options - options database, use NULL for default global database
1679: . pre - the string to prepend to the name or NULL
1680: - name - the option one is seeking
1682: Output Parameter:
1683: + ivalue - the logical value to return
1684: - set - PETSC_TRUE if found, else PETSC_FALSE
1686: Level: beginner
1688: Notes:
1689: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1690: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1692: If the option is given, but no value is provided, then ivalue and set are both given the value PETSC_TRUE. That is -requested_bool
1693: is equivalent to -requested_bool true
1695: If the user does not supply the option at all ivalue is NOT changed. Thus
1696: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1698: Concepts: options database^has logical
1700: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1701: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsBool(),
1702: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1703: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1704: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1705: PetscOptionsFList(), PetscOptionsEList()
1706: @*/
1707: PetscErrorCode PetscOptionsGetBool(PetscOptions options,const char pre[],const char name[],PetscBool *ivalue,PetscBool *set)
1708: {
1709: char *value;
1710: PetscBool flag;
1716: options = options ? options : defaultoptions;
1717: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1718: if (flag) {
1719: if (set) *set = PETSC_TRUE;
1720: if (!value) {
1721: if (ivalue) *ivalue = PETSC_TRUE;
1722: } else {
1723: PetscOptionsStringToBool(value, ivalue);
1724: }
1725: } else {
1726: if (set) *set = PETSC_FALSE;
1727: }
1728: return(0);
1729: }
1731: /*@C
1732: PetscOptionsGetBoolArray - Gets an array of Logical (true or false) values for a particular
1733: option in the database. The values must be separated with commas with
1734: no intervening spaces.
1736: Not Collective
1738: Input Parameters:
1739: + options - options database, use NULL for default global database
1740: . pre - string to prepend to each name or NULL
1741: . name - the option one is seeking
1742: - nmax - maximum number of values to retrieve
1744: Output Parameter:
1745: + dvalue - the integer values to return
1746: . nmax - actual number of values retreived
1747: - set - PETSC_TRUE if found, else PETSC_FALSE
1749: Level: beginner
1751: Concepts: options database^array of ints
1753: Notes:
1754: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1755: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1757: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1758: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1759: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1760: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1761: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1762: PetscOptionsFList(), PetscOptionsEList()
1763: @*/
1764: PetscErrorCode PetscOptionsGetBoolArray(PetscOptions options,const char pre[],const char name[],PetscBool dvalue[],PetscInt *nmax,PetscBool *set)
1765: {
1766: char *value;
1768: PetscInt n = 0;
1769: PetscBool flag;
1770: PetscToken token;
1775: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1776: if (!flag) {if (set) *set = PETSC_FALSE; *nmax = 0; return(0);}
1777: if (!value) {if (set) *set = PETSC_TRUE; *nmax = 0; return(0);}
1779: if (set) *set = PETSC_TRUE;
1781: PetscTokenCreate(value,',',&token);
1782: PetscTokenFind(token,&value);
1783: while (n < *nmax) {
1784: if (!value) break;
1785: PetscOptionsStringToBool(value,dvalue);
1786: PetscTokenFind(token,&value);
1787: dvalue++;
1788: n++;
1789: }
1790: PetscTokenDestroy(&token);
1791: *nmax = n;
1792: return(0);
1793: }
1795: /*@C
1796: PetscOptionsGetReal - Gets the double precision value for a particular
1797: option in the database.
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
1806: Output Parameter:
1807: + dvalue - the double value to return
1808: - set - PETSC_TRUE if found, PETSC_FALSE if not found
1810: Notes: If the user does not supply the option dvalue is NOT changed. Thus
1811: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1813: Level: beginner
1815: Concepts: options database^has double
1817: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1818: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsBool(),
1819: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1820: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1821: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1822: PetscOptionsFList(), PetscOptionsEList()
1823: @*/
1824: PetscErrorCode PetscOptionsGetReal(PetscOptions options,const char pre[],const char name[],PetscReal *dvalue,PetscBool *set)
1825: {
1826: char *value;
1828: PetscBool flag;
1833: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1834: if (flag) {
1835: if (!value) {
1836: if (set) *set = PETSC_FALSE;
1837: } else {
1838: if (set) *set = PETSC_TRUE;
1839: PetscOptionsStringToReal(value,dvalue);
1840: }
1841: } else {
1842: if (set) *set = PETSC_FALSE;
1843: }
1844: return(0);
1845: }
1847: /*@C
1848: PetscOptionsGetScalar - Gets the scalar value for a particular
1849: option in the database.
1851: Not Collective
1853: Input Parameters:
1854: + options - options database, use NULL for default global database
1855: . pre - string to prepend to each name or NULL
1856: - name - the option one is seeking
1858: Output Parameter:
1859: + dvalue - the double value to return
1860: - set - PETSC_TRUE if found, else PETSC_FALSE
1862: Level: beginner
1864: Usage:
1865: A complex number 2+3i must be specified with NO spaces
1867: Notes: If the user does not supply the option dvalue is NOT changed. Thus
1868: you should ALWAYS initialize the ivalue if you access it without first checking if the set flag is true.
1870: Concepts: options database^has scalar
1872: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1873: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
1874: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1875: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1876: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1877: PetscOptionsFList(), PetscOptionsEList()
1878: @*/
1879: PetscErrorCode PetscOptionsGetScalar(PetscOptions options,const char pre[],const char name[],PetscScalar *dvalue,PetscBool *set)
1880: {
1881: char *value;
1882: PetscBool flag;
1888: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1889: if (flag) {
1890: if (!value) {
1891: if (set) *set = PETSC_FALSE;
1892: } else {
1893: #if !defined(PETSC_USE_COMPLEX)
1894: PetscOptionsStringToReal(value,dvalue);
1895: #else
1896: PetscOptionsStringToScalar(value,dvalue);
1897: #endif
1898: if (set) *set = PETSC_TRUE;
1899: }
1900: } else { /* flag */
1901: if (set) *set = PETSC_FALSE;
1902: }
1903: return(0);
1904: }
1906: /*@C
1907: PetscOptionsGetRealArray - Gets an array of double precision values for a
1908: particular option in the database. The values must be separated with
1909: commas with no intervening spaces.
1911: Not Collective
1913: Input Parameters:
1914: + options - options database, use NULL for default global database
1915: . pre - string to prepend to each name or NULL
1916: . name - the option one is seeking
1917: - nmax - maximum number of values to retrieve
1919: Output Parameters:
1920: + dvalue - the double values to return
1921: . nmax - actual number of values retreived
1922: - set - PETSC_TRUE if found, else PETSC_FALSE
1924: Level: beginner
1926: Concepts: options database^array of doubles
1928: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1929: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsBool(),
1930: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1931: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1932: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
1933: PetscOptionsFList(), PetscOptionsEList()
1934: @*/
1935: PetscErrorCode PetscOptionsGetRealArray(PetscOptions options,const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscBool *set)
1936: {
1937: char *value;
1939: PetscInt n = 0;
1940: PetscBool flag;
1941: PetscToken token;
1946: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
1947: if (!flag) {
1948: if (set) *set = PETSC_FALSE;
1949: *nmax = 0;
1950: return(0);
1951: }
1952: if (!value) {
1953: if (set) *set = PETSC_TRUE;
1954: *nmax = 0;
1955: return(0);
1956: }
1958: if (set) *set = PETSC_TRUE;
1960: PetscTokenCreate(value,',',&token);
1961: PetscTokenFind(token,&value);
1962: while (n < *nmax) {
1963: if (!value) break;
1964: PetscOptionsStringToReal(value,dvalue++);
1965: PetscTokenFind(token,&value);
1966: n++;
1967: }
1968: PetscTokenDestroy(&token);
1969: *nmax = n;
1970: return(0);
1971: }
1973: /*@C
1974: PetscOptionsGetScalarArray - Gets an array of scalars 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 scalar 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 PetscOptionsGetScalarArray(PetscOptions options,const char pre[],const char name[],PetscScalar 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: PetscOptionsStringToScalar(value,dvalue++);
2032: PetscTokenFind(token,&value);
2033: n++;
2034: }
2035: PetscTokenDestroy(&token);
2036: *nmax = n;
2037: return(0);
2038: }
2040: /*@C
2041: PetscOptionsGetIntArray - Gets an array of integer values for a particular
2042: option in the database.
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 Parameter:
2053: + dvalue - the integer values to return
2054: . nmax - actual number of values retreived
2055: - set - PETSC_TRUE if found, else PETSC_FALSE
2057: Level: beginner
2059: Notes:
2060: The array can be passed as
2061: a comma separated list: 0,1,2,3,4,5,6,7
2062: a range (start-end+1): 0-8
2063: a range with given increment (start-end+1:inc): 0-7:2
2064: a combination of values and ranges separated by commas: 0,1-8,8-15:2
2066: There must be no intervening spaces between the values.
2068: Concepts: options database^array of ints
2070: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
2071: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2072: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2073: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2074: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2075: PetscOptionsFList(), PetscOptionsEList()
2076: @*/
2077: PetscErrorCode PetscOptionsGetIntArray(PetscOptions options,const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscBool *set)
2078: {
2079: char *value;
2081: PetscInt n = 0,i,j,start,end,inc,nvalues;
2082: size_t len;
2083: PetscBool flag,foundrange;
2084: PetscToken token;
2089: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2090: if (!flag) {
2091: if (set) *set = PETSC_FALSE;
2092: *nmax = 0;
2093: return(0);
2094: }
2095: if (!value) {
2096: if (set) *set = PETSC_TRUE;
2097: *nmax = 0;
2098: return(0);
2099: }
2101: if (set) *set = PETSC_TRUE;
2103: PetscTokenCreate(value,',',&token);
2104: PetscTokenFind(token,&value);
2105: while (n < *nmax) {
2106: if (!value) break;
2108: /* look for form d-D where d and D are integers */
2109: foundrange = PETSC_FALSE;
2110: PetscStrlen(value,&len);
2111: if (value[0] == '-') i=2;
2112: else i=1;
2113: for (;i<(int)len; i++) {
2114: if (value[i] == '-') {
2115: if (i == (int)len-1) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_USER,"Error in %D-th array entry %s\n",n,value);
2116: value[i] = 0;
2118: PetscOptionsStringToInt(value,&start);
2119: inc = 1;
2120: j = i+1;
2121: for (;j<(int)len; j++) {
2122: if (value[j] == ':') {
2123: value[j] = 0;
2125: PetscOptionsStringToInt(value+j+1,&inc);
2126: 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);
2127: break;
2128: }
2129: }
2130: PetscOptionsStringToInt(value+i+1,&end);
2131: 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);
2132: nvalues = (end-start)/inc + (end-start)%inc;
2133: 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);
2134: for (;start<end; start+=inc) {
2135: *dvalue = start; dvalue++;n++;
2136: }
2137: foundrange = PETSC_TRUE;
2138: break;
2139: }
2140: }
2141: if (!foundrange) {
2142: PetscOptionsStringToInt(value,dvalue);
2143: dvalue++;
2144: n++;
2145: }
2146: PetscTokenFind(token,&value);
2147: }
2148: PetscTokenDestroy(&token);
2149: *nmax = n;
2150: return(0);
2151: }
2153: /*@C
2154: PetscOptionsGetEnumArray - Gets an array of enum values for a particular option in the database.
2156: Not Collective
2158: Input Parameters:
2159: + options - options database, use NULL for default global database
2160: . pre - option prefix or NULL
2161: . name - option name
2162: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
2163: - nmax - maximum number of values to retrieve
2165: Output Parameters:
2166: + dvalue - the enum values to return
2167: . nmax - actual number of values retreived
2168: - set - PETSC_TRUE if found, else PETSC_FALSE
2170: Level: beginner
2172: Concepts: options database
2174: Notes:
2175: The array must be passed as a comma separated list.
2177: There must be no intervening spaces between the values.
2179: list is usually something like PCASMTypes or some other predefined list of enum names.
2181: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
2182: PetscOptionsGetEnum(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool()
2183: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsBool(), PetscOptionsName(),
2184: PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(), PetscOptionsStringArray(),PetscOptionsRealArray(),
2185: PetscOptionsScalar(), PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2186: PetscOptionsFList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
2187: @*/
2188: PetscErrorCode PetscOptionsGetEnumArray(PetscOptions options,const char pre[],const char name[],const char *const *list,PetscEnum dvalue[],PetscInt *nmax,PetscBool *set)
2189: {
2190: char *svalue;
2191: PetscInt n = 0;
2192: PetscEnum evalue;
2193: PetscBool flag;
2194: PetscToken token;
2203: PetscOptionsFindPair_Private(options,pre,name,&svalue,&flag);
2204: if (!flag) {
2205: if (set) *set = PETSC_FALSE;
2206: *nmax = 0;
2207: return(0);
2208: }
2209: if (!svalue) {
2210: if (set) *set = PETSC_TRUE;
2211: *nmax = 0;
2212: return(0);
2213: }
2214: if (set) *set = PETSC_TRUE;
2216: PetscTokenCreate(svalue,',',&token);
2217: PetscTokenFind(token,&svalue);
2218: while (svalue && n < *nmax) {
2219: PetscEnumFind(list,svalue,&evalue,&flag);
2220: if (!flag) SETERRQ3(PETSC_COMM_SELF,PETSC_ERR_USER,"Unknown enum value '%s' for -%s%s",svalue,pre ? pre : "",name+1);
2221: dvalue[n++] = evalue;
2222: PetscTokenFind(token,&svalue);
2223: }
2224: *nmax = n;
2225: PetscTokenDestroy(&token);
2226: return(0);
2227: }
2229: /*@C
2230: PetscOptionsGetString - Gets the string value for a particular option in
2231: the database.
2233: Not Collective
2235: Input Parameters:
2236: + options - options database, use NULL for default global database
2237: . pre - string to prepend to name or NULL
2238: . name - the option one is seeking
2239: - len - maximum length of the string including null termination
2241: Output Parameters:
2242: + string - location to copy string
2243: - set - PETSC_TRUE if found, else PETSC_FALSE
2245: Level: beginner
2247: Fortran Note:
2248: The Fortran interface is slightly different from the C/C++
2249: interface (len is not used). Sample usage in Fortran follows
2250: .vb
2251: character *20 string
2252: PetscErrorCode ierr
2253: PetscBool set
2254: call PetscOptionsGetString(PETSC_NULL_OPTIONS,PETSC_NULL_CHARACTER,'-s',string,set,ierr)
2255: .ve
2257: 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
2259: If the user does not use the option then the string is not changed. Thus
2260: you should ALWAYS initialize the string if you access it without first checking if the set flag is true.
2262: Concepts: options database^string
2264: Note:
2265: 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).
2267: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2268: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2269: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2270: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2271: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2272: PetscOptionsFList(), PetscOptionsEList()
2273: @*/
2274: PetscErrorCode PetscOptionsGetString(PetscOptions options,const char pre[],const char name[],char string[],size_t len,PetscBool *set)
2275: {
2276: char *value;
2278: PetscBool flag;
2283: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2284: if (!flag) {
2285: if (set) *set = PETSC_FALSE;
2286: } else {
2287: if (set) *set = PETSC_TRUE;
2288: if (value) {
2289: PetscStrncpy(string,value,len);
2290: string[len-1] = 0; /* Ensure that the string is NULL terminated */
2291: } else {
2292: PetscMemzero(string,len);
2293: }
2294: }
2295: return(0);
2296: }
2298: char *PetscOptionsGetStringMatlab(PetscOptions options,const char pre[],const char name[])
2299: {
2300: char *value;
2302: PetscBool flag;
2305: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);if (ierr) return(0);
2306: if (flag) PetscFunctionReturn(value);
2307: else return(0);
2308: }
2311: /*@C
2312: PetscOptionsGetStringArray - Gets an array of string values for a particular
2313: option in the database. The values must be separated with commas with
2314: no intervening spaces.
2316: Not Collective
2318: Input Parameters:
2319: + options - options database, use NULL for default global database
2320: . pre - string to prepend to name or NULL
2321: . name - the option one is seeking
2322: - nmax - maximum number of strings
2324: Output Parameter:
2325: + strings - location to copy strings
2326: - set - PETSC_TRUE if found, else PETSC_FALSE
2328: Level: beginner
2330: Notes:
2331: The user should pass in an array of pointers to char, to hold all the
2332: strings returned by this function.
2334: The user is responsible for deallocating the strings that are
2335: returned. The Fortran interface for this routine is not supported.
2337: Contributed by Matthew Knepley.
2339: Concepts: options database^array of strings
2341: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
2342: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsBool(),
2343: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
2344: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
2345: PetscOptionsBoolGroupBegin(), PetscOptionsBoolGroup(), PetscOptionsBoolGroupEnd(),
2346: PetscOptionsFList(), PetscOptionsEList()
2347: @*/
2348: PetscErrorCode PetscOptionsGetStringArray(PetscOptions options,const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscBool *set)
2349: {
2350: char *value;
2352: PetscInt n;
2353: PetscBool flag;
2354: PetscToken token;
2359: PetscOptionsFindPair_Private(options,pre,name,&value,&flag);
2360: if (!flag) {
2361: *nmax = 0;
2362: if (set) *set = PETSC_FALSE;
2363: return(0);
2364: }
2365: if (!value) {
2366: *nmax = 0;
2367: if (set) *set = PETSC_FALSE;
2368: return(0);
2369: }
2370: if (!*nmax) {
2371: if (set) *set = PETSC_FALSE;
2372: return(0);
2373: }
2374: if (set) *set = PETSC_TRUE;
2376: PetscTokenCreate(value,',',&token);
2377: PetscTokenFind(token,&value);
2378: n = 0;
2379: while (n < *nmax) {
2380: if (!value) break;
2381: PetscStrallocpy(value,&strings[n]);
2382: PetscTokenFind(token,&value);
2383: n++;
2384: }
2385: PetscTokenDestroy(&token);
2386: *nmax = n;
2387: return(0);
2388: }
2390: /*@C
2391: PetscOptionsUsed - Indicates if PETSc has used a particular option set in the database
2393: Not Collective
2395: Input Parameter:
2396: + options - options database, use NULL for default global database
2397: - option - string name of option
2399: Output Parameter:
2400: . used - PETSC_TRUE if the option was used, otherwise false, including if option was not found in options database
2402: Level: advanced
2404: .seealso: PetscOptionsView(), PetscOptionsLeft(), PetscOptionsAllUsed()
2405: @*/
2406: PetscErrorCode PetscOptionsUsed(PetscOptions options,const char *option,PetscBool *used)
2407: {
2408: PetscInt i;
2412: options = options ? options : defaultoptions;
2413: *used = PETSC_FALSE;
2414: for (i=0; i<options->N; i++) {
2415: PetscStrcmp(options->names[i],option,used);
2416: if (*used) {
2417: *used = options->used[i];
2418: break;
2419: }
2420: }
2421: return(0);
2422: }
2424: /*@C
2425: PetscOptionsAllUsed - Returns a count of the number of options in the
2426: database that have never been selected.
2428: Not Collective
2430: Input Parameter:
2431: . options - options database, use NULL for default global database
2433: Output Parameter:
2434: . N - count of options not used
2436: Level: advanced
2438: .seealso: PetscOptionsView()
2439: @*/
2440: PetscErrorCode PetscOptionsAllUsed(PetscOptions options,PetscInt *N)
2441: {
2442: PetscInt i,n = 0;
2445: options = options ? options : defaultoptions;
2446: for (i=0; i<options->N; i++) {
2447: if (!options->used[i]) n++;
2448: }
2449: *N = n;
2450: return(0);
2451: }
2453: /*@C
2454: PetscOptionsLeft - Prints to screen any options that were set and never used.
2456: Not collective
2458: Input Parameter:
2459: . options - options database; use NULL for default global database
2461: Options Database Key:
2462: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
2464: Level: advanced
2466: .seealso: PetscOptionsAllUsed()
2467: @*/
2468: PetscErrorCode PetscOptionsLeft(PetscOptions options)
2469: {
2471: PetscInt i;
2474: options = options ? options : defaultoptions;
2475: for (i=0; i<options->N; i++) {
2476: if (!options->used[i]) {
2477: if (options->values[i]) {
2478: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
2479: } else {
2480: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s (no value)\n",options->names[i]);
2481: }
2482: }
2483: }
2484: return(0);
2485: }
2487: /*@C
2488: PetscOptionsLeftGet - Returns all options that were set and never used.
2490: Not collective
2492: Input Parameter:
2493: . options - options database, use NULL for default global database
2495: Output Parameter:
2496: . N - count of options not used
2497: . names - names of options not used
2498: . values - values of options not used
2500: Level: advanced
2502: Notes:
2503: Users should call PetscOptionsLeftRestore() to free the memory allocated in this routine
2505: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft()
2506: @*/
2507: PetscErrorCode PetscOptionsLeftGet(PetscOptions options,PetscInt *N,char **names[],char **values[])
2508: {
2510: PetscInt i,n;
2513: options = options ? options : defaultoptions;
2515: /* The number of unused PETSc options */
2516: n = 0;
2517: for (i=0; i<options->N; i++) {
2518: if (!options->used[i]) {
2519: n++;
2520: }
2521: }
2522: if (N) {*N = n;}
2523: if (names) { PetscMalloc1(n,names); }
2524: if (values) { PetscMalloc1(n,values); }
2526: n = 0;
2527: if (names || values) {
2528: for (i=0; i<options->N; i++) {
2529: if (!options->used[i]) {
2530: if (names) (*names)[n] = options->names[i];
2531: if (values) (*values)[n] = options->values[i];
2532: n++;
2533: }
2534: }
2535: }
2536: return(0);
2537: }
2540: /*@C
2541: PetscOptionsLeftRestore - Free memory for the unused PETSc options obtained using PetscOptionsLeftGet.
2543: Not collective
2545: Input Parameter:
2546: . options - options database, use NULL for default global database
2547: . names - names of options not used
2548: . values - values of options not used
2550: Level: advanced
2552: .seealso: PetscOptionsAllUsed(), PetscOptionsLeft(), PetscOptionsLeftGet
2553: @*/
2554: PetscErrorCode PetscOptionsLeftRestore(PetscOptions options,PetscInt *N,char **names[],char **values[])
2555: {
2559: if(N) *N = 0;
2560: if (names) { PetscFree(*names); }
2561: if (values) { PetscFree(*values); }
2562: return(0);
2563: }
2566: /*@
2567: PetscOptionsCreate - Creates the empty options database.
2569: Output Parameter:
2570: . options - Options database object
2572: Level: advanced
2574: @*/
2575: PetscErrorCode PetscOptionsCreate(PetscOptions *options)
2576: {
2577: *options = (PetscOptions)calloc(1,sizeof(struct _n_PetscOptions));
2578: if (!options) return PETSC_ERR_MEM;
2579: (*options)->namegiven = PETSC_FALSE;
2580: (*options)->N = 0;
2581: (*options)->Naliases = 0;
2582: (*options)->numbermonitors = 0;
2583: return 0;
2584: }
2586: /*
2587: PetscOptionsCreateDefault - Creates the default global options database
2589: */
2590: PetscErrorCode PetscOptionsCreateDefault(void)
2591: {
2594: if (!defaultoptions) {
2595: PetscOptionsCreate(&defaultoptions);if (ierr) return ierr;
2596: }
2597: return 0;
2598: }
2600: /*@C
2601: PetscOptionsSetFromOptions - Sets options related to the handling of options in PETSc
2603: Collective on PETSC_COMM_WORLD
2605: Input Parameter:
2606: . options - options database, use NULL for default global database
2608: Options Database Keys:
2609: + -options_monitor <optional filename> - prints the names and values of all runtime options as they are set. The monitor functionality is not
2610: available for options set through a file, environment variable, or on
2611: the command line. Only options set after PetscInitialize() completes will
2612: be monitored.
2613: . -options_monitor_cancel - cancel all options database monitors
2615: Notes:
2616: To see all options, run your program with the -help option or consult Users-Manual: Introduction
2618: Level: intermediate
2620: .keywords: set, options, database
2621: @*/
2622: PetscErrorCode PetscOptionsSetFromOptions(PetscOptions options)
2623: {
2624: PetscBool flgc = PETSC_FALSE,flgm;
2626: char monfilename[PETSC_MAX_PATH_LEN];
2627: PetscViewer monviewer;
2630: /*
2631: The options argument is currently ignored since we currently maintain only a single options database
2633: options = options ? options : defaultoptions;
2634: */
2635: PetscOptionsBegin(PETSC_COMM_WORLD,NULL,"Options for handling options","PetscOptions");
2636: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsMonitorSet","stdout",monfilename,PETSC_MAX_PATH_LEN,&flgm);
2637: PetscOptionsBool("-options_monitor_cancel","Cancel all options database monitors","PetscOptionsMonitorCancel",flgc,&flgc,NULL);
2638: PetscOptionsEnd();
2639: if (flgm) {
2640: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
2641: PetscOptionsMonitorSet(PetscOptionsMonitorDefault,monviewer,(PetscErrorCode (*)(void**))PetscViewerDestroy);
2642: }
2643: if (flgc) { PetscOptionsMonitorCancel(); }
2644: return(0);
2645: }
2648: /*@C
2649: PetscOptionsMonitorDefault - Print all options set value events.
2651: Logically Collective on PETSC_COMM_WORLD
2653: Input Parameters:
2654: + name - option name string
2655: . value - option value string
2656: - dummy - an ASCII viewer
2658: Level: intermediate
2660: .keywords: PetscOptions, default, monitor
2662: .seealso: PetscOptionsMonitorSet()
2663: @*/
2664: PetscErrorCode PetscOptionsMonitorDefault(const char name[], const char value[], void *dummy)
2665: {
2667: PetscViewer viewer = (PetscViewer) dummy;
2670: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
2671: return(0);
2672: }
2674: /*@C
2675: PetscOptionsMonitorSet - Sets an ADDITIONAL function to be called at every method that
2676: modified the PETSc options database.
2678: Not collective
2680: Input Parameters:
2681: + monitor - pointer to function (if this is NULL, it turns off monitoring
2682: . mctx - [optional] context for private data for the
2683: monitor routine (use NULL if no context is desired)
2684: - monitordestroy - [optional] routine that frees monitor context
2685: (may be NULL)
2687: Calling Sequence of monitor:
2688: $ monitor (const char name[], const char value[], void *mctx)
2690: + name - option name string
2691: . value - option value string
2692: - mctx - optional monitoring context, as set by PetscOptionsMonitorSet()
2694: Options Database Keys:
2695: + -options_monitor - sets PetscOptionsMonitorDefault()
2696: - -options_monitor_cancel - cancels all monitors that have
2697: been hardwired into a code by
2698: calls to PetscOptionsMonitorSet(), but
2699: does not cancel those set via
2700: the options database.
2702: Notes:
2703: The default is to do nothing. To print the name and value of options
2704: being inserted into the database, use PetscOptionsMonitorDefault() as the monitoring routine,
2705: with a null monitoring context.
2707: Several different monitoring routines may be set by calling
2708: PetscOptionsMonitorSet() multiple times; all will be called in the
2709: order in which they were set.
2711: Level: beginner
2713: .keywords: PetscOptions, set, monitor
2715: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorCancel()
2716: @*/
2717: PetscErrorCode PetscOptionsMonitorSet(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void**))
2718: {
2719: PetscOptions options = defaultoptions;
2722: if (options->numbermonitors >= MAXOPTIONSMONITORS) SETERRQ(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
2723: options->monitor[options->numbermonitors] = monitor;
2724: options->monitordestroy[options->numbermonitors] = monitordestroy;
2725: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
2726: return(0);
2727: }
2729: /*@
2730: PetscOptionsMonitorCancel - Clears all monitors for a PetscOptions object.
2732: Not collective
2734: Options Database Key:
2735: . -options_monitor_cancel - Cancels all monitors that have
2736: been hardwired into a code by calls to PetscOptionsMonitorSet(),
2737: but does not cancel those set via the options database.
2739: Level: intermediate
2741: .keywords: PetscOptions, set, monitor
2743: .seealso: PetscOptionsMonitorDefault(), PetscOptionsMonitorSet()
2744: @*/
2745: PetscErrorCode PetscOptionsMonitorCancel(void)
2746: {
2748: PetscInt i;
2749: PetscOptions options = defaultoptions;
2752: for (i=0; i<options->numbermonitors; i++) {
2753: if (options->monitordestroy[i]) {
2754: (*options->monitordestroy[i])(&options->monitorcontext[i]);
2755: }
2756: }
2757: options->numbermonitors = 0;
2758: return(0);
2759: }
2761: #define CHKERRQI(incall,ierr) if (ierr) {incall = PETSC_FALSE; }
2763: /*@C
2764: PetscObjectViewFromOptions - Processes command line options to determine if/how a PetscObject is to be viewed.
2766: Collective on PetscObject
2768: Input Parameters:
2769: + obj - the object
2770: . bobj - optional other object that provides prefix (if NULL then the prefix in obj is used)
2771: - optionname - option to activate viewing
2773: Level: intermediate
2775: @*/
2776: PetscErrorCode PetscObjectViewFromOptions(PetscObject obj,PetscObject bobj,const char optionname[])
2777: {
2778: PetscErrorCode ierr;
2779: PetscViewer viewer;
2780: PetscBool flg;
2781: static PetscBool incall = PETSC_FALSE;
2782: PetscViewerFormat format;
2783: char *prefix;
2786: if (incall) return(0);
2787: incall = PETSC_TRUE;
2788: prefix = bobj ? bobj->prefix : obj->prefix;
2789: PetscOptionsGetViewer(PetscObjectComm((PetscObject)obj),prefix,optionname,&viewer,&format,&flg);CHKERRQI(incall,ierr);
2790: if (flg) {
2791: PetscViewerPushFormat(viewer,format);CHKERRQI(incall,ierr);
2792: PetscObjectView(obj,viewer);CHKERRQI(incall,ierr);
2793: PetscViewerPopFormat(viewer);CHKERRQI(incall,ierr);
2794: PetscViewerDestroy(&viewer);CHKERRQI(incall,ierr);
2795: }
2796: incall = PETSC_FALSE;
2797: return(0);
2798: }