Actual source code: options.c
1: #define PETSC_DLL
2: /*
3: These routines simplify the use of command line, file options, etc.,
4: and are used to manipulate the options database.
6: This file uses regular malloc and free because it cannot know
7: what malloc is being used until it has already processed the input.
8: */
10: #include petsc.h
11: #include petscsys.h
12: #if defined(PETSC_HAVE_STDLIB_H)
13: #include <stdlib.h>
14: #endif
15: #if defined(PETSC_HAVE_MALLOC_H)
16: #include <malloc.h>
17: #endif
18: #if defined(PETSC_HAVE_SYS_PARAM_H)
19: #include "sys/param.h"
20: #endif
21: #include "petscfix.h"
23: /*
24: For simplicity, we use a static size database
25: */
26: #define MAXOPTIONS 512
27: #define MAXALIASES 25
28: #define MAXOPTIONSMONITORS 5
30: typedef struct {
31: int N,argc,Naliases;
32: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
33: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
34: PetscTruth used[MAXOPTIONS];
35: PetscTruth namegiven;
36: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
38: /* --------User (or default) routines (most return -1 on error) --------*/
39: PetscErrorCode (*monitor[MAXOPTIONSMONITORS])(const char[], const char[], void*); /* returns control to user after */
40: PetscErrorCode (*monitordestroy[MAXOPTIONSMONITORS])(void*); /* */
41: void *monitorcontext[MAXOPTIONSMONITORS]; /* to pass arbitrary user data into monitor */
42: PetscInt numbermonitors; /* to, for instance, detect options being set */
44: } PetscOptionsTable;
47: static PetscOptionsTable *options = 0;
49: /*
50: Options events monitor
51: */
52: #define PetscOptionsMonitor(name,value) \
53: { PetscErrorCode _ierr; PetscInt _i,_im = options->numbermonitors; \
54: for (_i=0; _i<_im; _i++) {\
55: _(*options->monitor[_i])(name, value, options->monitorcontext[_i]);CHKERRQ(_ierr); \
56: } \
57: }
61: PetscErrorCode PetscOptionsAtoi(const char name[],PetscInt *a)
62: {
64: size_t i,len;
65: PetscTruth decide,tdefault,mouse;
68: PetscStrlen(name,&len);
69: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
71: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
72: if (!tdefault) {
73: PetscStrcasecmp(name,"DEFAULT",&tdefault);
74: }
75: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
76: if (!decide) {
77: PetscStrcasecmp(name,"DECIDE",&decide);
78: }
79: PetscStrcasecmp(name,"mouse",&mouse);
81: if (tdefault) {
82: *a = PETSC_DEFAULT;
83: } else if (decide) {
84: *a = PETSC_DECIDE;
85: } else if (mouse) {
86: *a = -1;
87: } else {
88: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
89: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
90: }
91: for (i=1; i<len; i++) {
92: if (name[i] < '0' || name[i] > '9') {
93: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no integer value (do not include . in it)",name);
94: }
95: }
96: *a = atoi(name);
97: }
98: return(0);
99: }
103: PetscErrorCode PetscOptionsAtod(const char name[],PetscReal *a)
104: {
106: size_t len;
107: PetscTruth decide,tdefault;
110: PetscStrlen(name,&len);
111: if (!len) SETERRQ(PETSC_ERR_ARG_WRONG,"character string of length zero has no numerical value");
113: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
114: if (!tdefault) {
115: PetscStrcasecmp(name,"DEFAULT",&tdefault);
116: }
117: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
118: if (!decide) {
119: PetscStrcasecmp(name,"DECIDE",&decide);
120: }
122: if (tdefault) {
123: *a = PETSC_DEFAULT;
124: } else if (decide) {
125: *a = PETSC_DECIDE;
126: } else {
127: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
128: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Input string %s has no numeric value ",name);
129: }
130: *a = atof(name);
131: }
132: return(0);
133: }
137: /*@C
138: PetscGetProgramName - Gets the name of the running program.
140: Not Collective
142: Input Parameter:
143: . len - length of the string name
145: Output Parameter:
146: . name - the name of the running program
148: Level: advanced
150: Notes:
151: The name of the program is copied into the user-provided character
152: array of length len. On some machines the program name includes
153: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
154: @*/
155: PetscErrorCode PetscGetProgramName(char name[],size_t len)
156: {
160: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
161: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
162: PetscStrncpy(name,options->programname,len);
163: return(0);
164: }
168: PetscErrorCode PetscSetProgramName(const char name[])
169: {
173: options->namegiven = PETSC_TRUE;
174: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
175: return(0);
176: }
180: /*@C
181: PetscOptionsInsertString - Inserts options into the database from a string
183: Not collective: but only processes that call this routine will set the options
184: included in the file
186: Input Parameter:
187: . in_str - string that contains options separated by blanks
190: Level: intermediate
192: Contributed by Boyana Norris
194: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
195: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
196: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
197: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
198: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
199: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
201: @*/
202: PetscErrorCode PetscOptionsInsertString(const char in_str[])
203: {
204: char *str,*first,*second,*third,*final;
205: size_t len;
207: PetscToken *token;
210: PetscStrallocpy(in_str, &str);
211: PetscTokenCreate(str,' ',&token);
212: PetscTokenFind(token,&first);
213: PetscTokenFind(token,&second);
214: if (first && first[0] == '-') {
215: if (second) {final = second;} else {final = first;}
216: PetscStrlen(final,&len);
217: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
218: len--; final[len] = 0;
219: }
220: PetscOptionsSetValue(first,second);
221: } else if (first) {
222: PetscTruth match;
223:
224: PetscStrcasecmp(first,"alias",&match);
225: if (match) {
226: PetscTokenFind(token,&third);
227: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
228: PetscStrlen(third,&len);
229: if (third[len-1] == 'n') third[len-1] = 0;
230: PetscOptionsSetAlias(second,third);
231: }
232: }
233: PetscTokenDestroy(token);
234: PetscFree(str);
235:
236: return(0);
237: }
241: /*@C
242: PetscOptionsInsertFile - Inserts options into the database from a file.
244: Not collective: but only processes that call this routine will set the options
245: included in the file
247: Input Parameter:
248: . file - name of file
251: Level: intermediate
253: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
254: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
255: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
256: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
257: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
258: PetscOptionsList(), PetscOptionsEList()
260: @*/
261: PetscErrorCode PetscOptionsInsertFile(const char file[])
262: {
263: char string[PETSC_MAX_PATH_LEN],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
265: size_t i,len,startIndex;
266: FILE *fd;
267: PetscToken *token;
270: PetscFixFilename(file,fname);
271: fd = fopen(fname,"r");
272: if (fd) {
273: while (fgets(string,128,fd)) {
274: /* Comments are indicated by #, ! or % in the first column */
275: if (string[0] == '#') continue;
276: if (string[0] == '!') continue;
277: if (string[0] == '%') continue;
279: PetscStrlen(string,&len);
281: /* replace tabs, ^M with " " */
282: for (i=0; i<len; i++) {
283: if (string[i] == '\t' || string[i] == '\r') {
284: string[i] = ' ';
285: }
286: }
287: for(startIndex = 0; startIndex < len-1; startIndex++) {
288: if (string[startIndex] != ' ') break;
289: }
290: PetscTokenCreate(&string[startIndex],' ',&token);
291: PetscTokenFind(token,&first);
292: PetscTokenFind(token,&second);
293: if (first && first[0] == '-') {
294: if (second) {final = second;} else {final = first;}
295: PetscStrlen(final,&len);
296: while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
297: len--; final[len] = 0;
298: }
299: PetscOptionsSetValue(first,second);
300: } else if (first) {
301: PetscTruth match;
303: PetscStrcasecmp(first,"alias",&match);
304: if (match) {
305: PetscTokenFind(token,&third);
306: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
307: PetscStrlen(third,&len);
308: if (third[len-1] == '\n') third[len-1] = 0;
309: PetscOptionsSetAlias(second,third);
310: }
311: }
312: PetscTokenDestroy(token);
313: }
314: fclose(fd);
315: } else {
316: SETERRQ1(PETSC_ERR_USER,"Unable to open Options File %s",fname);
317: }
318: return(0);
319: }
323: /*@C
324: PetscOptionsInsert - Inserts into the options database from the command line,
325: the environmental variable and a file.
327: Input Parameters:
328: + argc - count of number of command line arguments
329: . args - the command line arguments
330: - file - optional filename, defaults to ~username/.petscrc
332: Note:
333: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
334: the user does not typically need to call this routine. PetscOptionsInsert()
335: can be called several times, adding additional entries into the database.
337: Options Database Keys:
338: + -options_monitor <optional filename> - print options names and values as they are set
340: Level: advanced
342: Concepts: options database^adding
344: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
345: @*/
346: PetscErrorCode PetscOptionsInsert(int *argc,char ***args,const char file[])
347: {
349: PetscMPIInt rank;
350: char pfile[PETSC_MAX_PATH_LEN];
351: PetscToken *token;
354: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
356: options->argc = (argc) ? *argc : 0;
357: options->args = (args) ? *args : 0;
359: if (file) {
360: PetscOptionsInsertFile(file);
361: } else {
362: PetscGetHomeDirectory(pfile,PETSC_MAX_PATH_LEN-16);
363: if (pfile[0]) {
364: PetscTruth flag;
365: PetscStrcat(pfile,"/.petscrc");
366: PetscTestFile(pfile,'r',&flag);
367: if (flag) {
368: PetscOptionsInsertFile(pfile);
369: }
370: } else {
371: PetscInfo(0,"Unable to determine home directory; skipping loading ~/.petscrc\n");
372: }
374: }
376: /* insert environmental options */
377: {
378: char *eoptions = 0,*second,*first;
379: size_t len = 0;
380: if (!rank) {
381: eoptions = (char*)getenv("PETSC_OPTIONS");
382: PetscStrlen(eoptions,&len);
383: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
384: } else {
385: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
386: if (len) {
387: PetscMalloc((len+1)*sizeof(char*),&eoptions);
388: }
389: }
390: if (len) {
391: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
392: eoptions[len] = 0;
393: PetscTokenCreate(eoptions,' ',&token);
394: PetscTokenFind(token,&first);
395: while (first) {
396: if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
397: PetscTokenFind(token,&second);
398: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
399: PetscOptionsSetValue(first,(char *)0);
400: first = second;
401: } else {
402: PetscOptionsSetValue(first,second);
403: PetscTokenFind(token,&first);
404: }
405: }
406: PetscTokenDestroy(token);
407: if (rank) {PetscFree(eoptions);}
408: }
409: }
411: /* insert command line options */
412: if (argc && args && *argc) {
413: int left = *argc - 1;
414: char **eargs = *args + 1;
415: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
417: while (left) {
418: PetscStrcasecmp(eargs[0],"-options_file",&isoptions_file);
419: PetscStrcasecmp(eargs[0],"-p4pg",&isp4);
420: PetscStrcasecmp(eargs[0],"-p4yourname",&isp4yourname);
421: PetscStrcasecmp(eargs[0],"-p4rmrank",&isp4rmrank);
422: PetscStrcasecmp(eargs[0],"-p4wd",&tisp4);
423: isp4 = (PetscTruth) (isp4 || tisp4);
424: PetscStrcasecmp(eargs[0],"-np",&tisp4);
425: isp4 = (PetscTruth) (isp4 || tisp4);
426: PetscStrcasecmp(eargs[0],"-p4amslave",&tisp4);
428: if (eargs[0][0] != '-') {
429: eargs++; left--;
430: } else if (isoptions_file) {
431: if (left <= 1) SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
432: if (eargs[1][0] == '-') SETERRQ(PETSC_ERR_USER,"Missing filename for -options_file filename option");
433: PetscOptionsInsertFile(eargs[1]);
434: eargs += 2; left -= 2;
436: /*
437: These are "bad" options that MPICH, etc put on the command line
438: we strip them out here.
439: */
440: } else if (tisp4 || isp4rmrank) {
441: eargs += 1; left -= 1;
442: } else if (isp4 || isp4yourname) {
443: eargs += 2; left -= 2;
444: } else if ((left < 2) || ((eargs[1][0] == '-') &&
445: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
446: PetscOptionsSetValue(eargs[0],PETSC_NULL);
447: eargs++; left--;
448: } else {
449: PetscOptionsSetValue(eargs[0],eargs[1]);
450: eargs += 2; left -= 2;
451: }
452: }
453: }
454:
455: return(0);
456: }
460: /*@C
461: PetscOptionsPrint - Prints the options that have been loaded. This is
462: useful for debugging purposes.
464: Collective on PETSC_COMM_WORLD
466: Input Parameter:
467: . FILE fd - location to print options (usually stdout or stderr)
469: Options Database Key:
470: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
472: Level: advanced
474: Concepts: options database^printing
476: .seealso: PetscOptionsAllUsed()
477: @*/
478: PetscErrorCode PetscOptionsPrint(FILE *fd)
479: {
481: PetscInt i;
484: if (!fd) fd = stdout;
485: if (!options) {PetscOptionsInsert(0,0,0);}
486: for (i=0; i<options->N; i++) {
487: if (options->values[i]) {
488: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
489: } else {
490: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
491: }
492: }
493: return(0);
494: }
498: /*@C
499: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
501: Not Collective
503: Output Parameter:
504: . copts - pointer where string pointer is stored
506: Level: advanced
508: Concepts: options database^listing
510: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
511: @*/
512: PetscErrorCode PetscOptionsGetAll(char *copts[])
513: {
515: PetscInt i;
516: size_t len = 1,lent;
517: char *coptions;
520: if (!options) {PetscOptionsInsert(0,0,0);}
522: /* count the length of the required string */
523: for (i=0; i<options->N; i++) {
524: PetscStrlen(options->names[i],&lent);
525: len += 2 + lent;
526: if (options->values[i]) {
527: PetscStrlen(options->values[i],&lent);
528: len += 1 + lent;
529: }
530: }
531: PetscMalloc(len*sizeof(char),&coptions);
532: coptions[0] = 0;
533: for (i=0; i<options->N; i++) {
534: PetscStrcat(coptions,"-");
535: PetscStrcat(coptions,options->names[i]);
536: PetscStrcat(coptions," ");
537: if (options->values[i]) {
538: PetscStrcat(coptions,options->values[i]);
539: PetscStrcat(coptions," ");
540: }
541: }
542: *copts = coptions;
543: return(0);
544: }
548: /*@C
549: PetscOptionsDestroy - Destroys the option database.
551: Note:
552: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
553: typically does not need to call this routine.
555: Level: developer
557: .seealso: PetscOptionsInsert()
558: @*/
559: PetscErrorCode PetscOptionsDestroy(void)
560: {
561: PetscInt i;
564: if (!options) return(0);
565: for (i=0; i<options->N; i++) {
566: if (options->names[i]) free(options->names[i]);
567: if (options->values[i]) free(options->values[i]);
568: }
569: for (i=0; i<options->Naliases; i++) {
570: free(options->aliases1[i]);
571: free(options->aliases2[i]);
572: }
573: free(options);
574: options = 0;
575: return(0);
576: }
580: /*@C
581: PetscOptionsSetValue - Sets an option name-value pair in the options
582: database, overriding whatever is already present.
584: Not collective, but setting values on certain processors could cause problems
585: for parallel objects looking for options.
587: Input Parameters:
588: + name - name of option, this SHOULD have the - prepended
589: - value - the option value (not used for all options)
591: Level: intermediate
593: Note:
594: Only some options have values associated with them, such as
595: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
597: Concepts: options database^adding option
599: .seealso: PetscOptionsInsert()
600: @*/
601: PetscErrorCode PetscOptionsSetValue(const char iname[],const char value[])
602: {
603: size_t len;
605: PetscInt N,n,i;
606: char **names;
607: const char *name = (char*)iname;
608: PetscTruth gt,match;
611: if (!options) {PetscOptionsInsert(0,0,0);}
613: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
614: PetscStrcasecmp(name,"-h",&match);
615: if (match) name = "-help";
617: name++;
618: /* first check against aliases */
619: N = options->Naliases;
620: for (i=0; i<N; i++) {
621: PetscStrcasecmp(options->aliases1[i],name,&match);
622: if (match) {
623: name = options->aliases2[i];
624: break;
625: }
626: }
628: N = options->N;
629: n = N;
630: names = options->names;
631:
632: for (i=0; i<N; i++) {
633: PetscStrcasecmp(names[i],name,&match);
634: PetscStrgrt(names[i],name,>);
635: if (match) {
636: if (options->values[i]) free(options->values[i]);
637: PetscStrlen(value,&len);
638: if (len) {
639: options->values[i] = (char*)malloc((len+1)*sizeof(char));
640: PetscStrcpy(options->values[i],value);
641: } else { options->values[i] = 0;}
642: return(0);
643: } else if (gt) {
644: n = i;
645: break;
646: }
647: }
648: if (N >= MAXOPTIONS) {
649: SETERRQ1(PETSC_ERR_PLIB,"No more room in option table, limit %d recompile \n src/sys/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
650: }
651: /* shift remaining values down 1 */
652: for (i=N; i>n; i--) {
653: names[i] = names[i-1];
654: options->values[i] = options->values[i-1];
655: options->used[i] = options->used[i-1];
656: }
657: /* insert new name and value */
658: PetscStrlen(name,&len);
659: names[n] = (char*)malloc((len+1)*sizeof(char));
660: PetscStrcpy(names[n],name);
661: if (value) {
662: PetscStrlen(value,&len);
663: options->values[n] = (char*)malloc((len+1)*sizeof(char));
664: PetscStrcpy(options->values[n],value);
665: } else {options->values[n] = 0;}
666: options->used[n] = PETSC_FALSE;
667: options->N++;
668: PetscOptionsMonitor(name,value);
669: return(0);
670: }
674: /*@C
675: PetscOptionsClearValue - Clears an option name-value pair in the options
676: database, overriding whatever is already present.
678: Not Collective, but setting values on certain processors could cause problems
679: for parallel objects looking for options.
681: Input Parameter:
682: . name - name of option, this SHOULD have the - prepended
684: Level: intermediate
686: Concepts: options database^removing option
687: .seealso: PetscOptionsInsert()
688: @*/
689: PetscErrorCode PetscOptionsClearValue(const char iname[])
690: {
692: PetscInt N,n,i;
693: char **names,*name=(char*)iname;
694: PetscTruth gt,match;
697: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
698: if (!options) {PetscOptionsInsert(0,0,0);}
700: name++;
702: N = options->N; n = 0;
703: names = options->names;
704:
705: for (i=0; i<N; i++) {
706: PetscStrcasecmp(names[i],name,&match);
707: PetscStrgrt(names[i],name,>);
708: if (match) {
709: if (options->values[i]) free(options->values[i]);
710: PetscOptionsMonitor(name,"");
711: break;
712: } else if (gt) {
713: return(0); /* it was not listed */
714: }
715: n++;
716: }
717: if (n == N) return(0); /* it was not listed */
719: /* shift remaining values down 1 */
720: for (i=n; i<N-1; i++) {
721: names[i] = names[i+1];
722: options->values[i] = options->values[i+1];
723: options->used[i] = options->used[i+1];
724: }
725: options->N--;
726: return(0);
727: }
731: /*@C
732: PetscOptionsReject - Generates an error if a certain option is given.
734: Not Collective, but setting values on certain processors could cause problems
735: for parallel objects looking for options.
737: Input Parameters:
738: + name - the option one is seeking
739: - mess - error message (may be PETSC_NULL)
741: Level: advanced
743: Concepts: options database^rejecting option
745: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
746: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
747: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
748: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
749: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
750: PetscOptionsList(), PetscOptionsEList()
751: @*/
752: PetscErrorCode PetscOptionsSetAlias(const char inewname[],const char ioldname[])
753: {
755: PetscInt n = options->Naliases;
756: size_t len;
757: char *newname = (char *)inewname,*oldname = (char*)ioldname;
760: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
761: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
762: if (n >= MAXALIASES) {
763: SETERRQ1(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);
764: }
766: newname++; oldname++;
767: PetscStrlen(newname,&len);
768: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
769: PetscStrcpy(options->aliases1[n],newname);
770: PetscStrlen(oldname,&len);
771: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
772: PetscStrcpy(options->aliases2[n],oldname);
773: options->Naliases++;
774: return(0);
775: }
779: static PetscErrorCode PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
780: {
782: PetscInt i,N;
783: size_t len;
784: char **names,tmp[256];
785: PetscTruth match;
788: if (!options) {PetscOptionsInsert(0,0,0);}
789: N = options->N;
790: names = options->names;
792: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
794: /* append prefix to name */
795: if (pre) {
796: if (pre[0] == '-') SETERRQ(PETSC_ERR_ARG_WRONG,"Prefix should not begin with a -");
797: PetscStrncpy(tmp,pre,256);
798: PetscStrlen(tmp,&len);
799: PetscStrncat(tmp,name+1,256-len-1);
800: } else {
801: PetscStrncpy(tmp,name+1,256);
802: }
804: /* slow search */
805: *flg = PETSC_FALSE;
806: for (i=0; i<N; i++) {
807: PetscStrcasecmp(names[i],tmp,&match);
808: if (match) {
809: *value = options->values[i];
810: options->used[i] = PETSC_TRUE;
811: *flg = PETSC_TRUE;
812: break;
813: }
814: }
815: if (!*flg) {
816: PetscInt j,cnt = 0,locs[16],loce[16];
817: size_t n;
818: PetscStrlen(tmp,&n);
819: /* determine the location and number of all _%d_ in the key */
820: for (i=0; i< (PetscInt)n; i++) {
821: if (tmp[i] == '_') {
822: for (j=i+1; j< (PetscInt)n; j++) {
823: if (tmp[j] >= '0' && tmp[j] <= '9') continue;
824: if (tmp[j] == '_' && j > i+1) { /* found a number */
825: locs[cnt] = i+1;
826: loce[cnt++] = j+1;
827: }
828: break;
829: }
830: }
831: }
832: if (cnt) {
833: char tmp2[256];
834: for (i=0; i<cnt; i++) {
835: PetscStrcpy(tmp2,"-");
836: PetscStrncat(tmp2,tmp,locs[i]);
837: PetscStrcat(tmp2,tmp+loce[i]);
838: PetscOptionsFindPair_Private(PETSC_NULL,tmp2,value,flg);
839: if (*flg) break;
840: }
841: }
842: }
843: return(0);
844: }
848: /*@C
849: PetscOptionsReject - Generates an error if a certain option is given.
851: Not Collective, but setting values on certain processors could cause problems
852: for parallel objects looking for options.
854: Input Parameters:
855: + name - the option one is seeking
856: - mess - error message (may be PETSC_NULL)
858: Level: advanced
860: Concepts: options database^rejecting option
862: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
863: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
864: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
865: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
866: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
867: PetscOptionsList(), PetscOptionsEList()
868: @*/
869: PetscErrorCode PetscOptionsReject(const char name[],const char mess[])
870: {
872: PetscTruth flag;
875: PetscOptionsHasName(PETSC_NULL,name,&flag);
876: if (flag) {
877: if (mess) {
878: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
879: } else {
880: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
881: }
882: }
883: return(0);
884: }
888: /*@C
889: PetscOptionsHasName - Determines whether a certain option is given in the database.
891: Not Collective
893: Input Parameters:
894: + name - the option one is seeking
895: - pre - string to prepend to the name or PETSC_NULL
897: Output Parameters:
898: . flg - PETSC_TRUE if found else PETSC_FALSE.
900: Level: beginner
902: Concepts: options database^has option name
904: Notes: Name cannot be simply -h
906: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
907: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
908: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
909: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
910: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
911: PetscOptionsList(), PetscOptionsEList()
912: @*/
913: PetscErrorCode PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
914: {
915: char *value;
917: PetscTruth isfalse,flag;
920: PetscOptionsFindPair_Private(pre,name,&value,&flag);
922: /* remove if turned off */
923: if (flag) {
924: PetscStrcasecmp(value,"FALSE",&isfalse);
925: if (isfalse) flag = PETSC_FALSE;
926: PetscStrcasecmp(value,"NO",&isfalse);
927: if (isfalse) flag = PETSC_FALSE;
928: PetscStrcasecmp(value,"0",&isfalse);
929: if (isfalse) flag = PETSC_FALSE;
930: }
931: if (flg) *flg = flag;
932: return(0);
933: }
937: /*@C
938: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
940: Not Collective
942: Input Parameters:
943: + pre - the string to prepend to the name or PETSC_NULL
944: - name - the option one is seeking
946: Output Parameter:
947: + ivalue - the integer value to return
948: - flg - PETSC_TRUE if found, else PETSC_FALSE
950: Level: beginner
952: Concepts: options database^has int
954: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
955: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
956: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
957: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
958: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
959: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
960: PetscOptionsList(), PetscOptionsEList()
961: @*/
962: PetscErrorCode PetscOptionsGetInt(const char pre[],const char name[],PetscInt *ivalue,PetscTruth *flg)
963: {
964: char *value;
966: PetscTruth flag;
971: PetscOptionsFindPair_Private(pre,name,&value,&flag);
972: if (flag) {
973: if (!value) {if (flg) *flg = PETSC_FALSE;}
974: else {
975: if (flg) *flg = PETSC_TRUE;
976: PetscOptionsAtoi(value,ivalue);
977: }
978: } else {
979: if (flg) *flg = PETSC_FALSE;
980: }
981: return(0);
982: }
986: /*@C
987: PetscOptionsGetEList - Puts a list of option values that a single one may be selected from
989: Not Collective
991: Input Parameters:
992: + pre - the string to prepend to the name or PETSC_NULL
993: . opt - option name
994: . list - the possible choices
995: . ntext - number of choices
997: Output Parameter:
998: + value - the index of the value to return
999: - set - PETSC_TRUE if found, else PETSC_FALSE
1000:
1001: Level: intermediate
1003: See PetscOptionsList() for when the choices are given in a PetscFList()
1005: Concepts: options database^list
1007: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1008: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1009: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1010: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1011: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1012: PetscOptionsList(), PetscOptionsEList()
1013: @*/
1014: PetscErrorCode PetscOptionsGetEList(const char pre[],const char opt[],const char **list,PetscInt ntext,PetscInt *value,PetscTruth *set)
1015: {
1017: size_t alen,len = 0;
1018: char *svalue;
1019: PetscTruth aset,flg = PETSC_FALSE;
1020: PetscInt i;
1023: for ( i=0; i<ntext; i++) {
1024: PetscStrlen(list[i],&alen);
1025: if (alen > len) len = alen;
1026: }
1027: len += 5; /* a little extra space for user mistypes */
1028: PetscMalloc(len*sizeof(char),&svalue);
1029: PetscOptionsGetString(pre,opt,svalue,len,&aset);
1030: if (aset) {
1031: if (set) *set = PETSC_TRUE;
1032: for (i=0; i<ntext; i++) {
1033: PetscStrcasecmp(svalue,list[i],&flg);
1034: if (flg) {
1035: *value = i;
1036: break;
1037: }
1038: }
1039: if (!flg) SETERRQ3(PETSC_ERR_USER,"Unknown option %s for -%s%s",svalue,pre?pre:"",opt+1);
1040: } else if (set) {
1041: *set = PETSC_FALSE;
1042: }
1043: PetscFree(svalue);
1044: return(0);
1045: }
1049: /*@C
1050: PetscOptionsGetEnum - Gets the enum value for a particular option in the database.
1052: Not Collective
1054: Input Parameters:
1055: + pre - option prefix or PETSC_NULL
1056: . opt - option name
1057: . list - array containing the list of choices, followed by the enum name, followed by the enum prefix, followed by a null
1058: - defaultv - the default (current) value
1060: Output Parameter:
1061: + value - the value to return
1062: - flg - PETSC_TRUE if found, else PETSC_FALSE
1064: Level: beginner
1066: Concepts: options database
1068: Notes: Must be between a PetscOptionsBegin() and a PetscOptionsEnd()
1070: list is usually something like PCASMTypes or some other predefined list of enum names
1072: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(), PetscOptionsGetInt(),
1073: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth()
1074: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsTruth(),
1075: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1076: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1077: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1078: PetscOptionsList(), PetscOptionsEList(), PetscOptionsGetEList(), PetscOptionsEnum()
1079: @*/
1080: PetscErrorCode PetscOptionsGetEnum(const char pre[],const char opt[],const char **list,PetscEnum *value,PetscTruth *set)
1081: {
1083: PetscInt ntext = 0;
1086: while (list[ntext++]) {
1087: if (ntext > 50) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument appears to be wrong or have more than 50 entries");
1088: }
1089: if (ntext < 3) SETERRQ(PETSC_ERR_ARG_WRONG,"List argument must have at least two entries: typename and type prefix");
1090: ntext -= 3;
1091: PetscOptionsGetEList(pre,opt,list,ntext,(PetscInt*)value,set);
1092: return(0);
1093: }
1097: /*@C
1098: PetscOptionsGetTruth - Gets the Logical (true or false) value for a particular
1099: option in the database.
1101: Not Collective
1103: Input Parameters:
1104: + pre - the string to prepend to the name or PETSC_NULL
1105: - name - the option one is seeking
1107: Output Parameter:
1108: + ivalue - the logical value to return
1109: - flg - PETSC_TRUE if found, else PETSC_FALSE
1111: Level: beginner
1113: Notes:
1114: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
1115: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
1117: Concepts: options database^has logical
1119: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
1120: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsTruth(),
1121: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1122: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1123: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1124: PetscOptionsList(), PetscOptionsEList()
1125: @*/
1126: PetscErrorCode PetscOptionsGetTruth(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
1127: {
1128: char *value;
1129: PetscTruth flag,istrue,isfalse;
1135: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1136: if (flag) {
1137: if (flg) *flg = PETSC_TRUE;
1138: if (!value) {
1139: *ivalue = PETSC_TRUE;
1140: } else {
1141: *ivalue = PETSC_TRUE;
1142: PetscStrcasecmp(value,"TRUE",&istrue);
1143: if (istrue) return(0);
1144: PetscStrcasecmp(value,"YES",&istrue);
1145: if (istrue) return(0);
1146: PetscStrcasecmp(value,"1",&istrue);
1147: if (istrue) return(0);
1148: PetscStrcasecmp(value,"on",&istrue);
1149: if (istrue) return(0);
1151: *ivalue = PETSC_FALSE;
1152: PetscStrcasecmp(value,"FALSE",&isfalse);
1153: if (isfalse) return(0);
1154: PetscStrcasecmp(value,"NO",&isfalse);
1155: if (isfalse) return(0);
1156: PetscStrcasecmp(value,"0",&isfalse);
1157: if (isfalse) return(0);
1158: PetscStrcasecmp(value,"off",&isfalse);
1159: if (isfalse) return(0);
1161: SETERRQ1(PETSC_ERR_ARG_WRONG,"Unknown logical value: %s",value);
1162: }
1163: } else {
1164: if (flg) *flg = PETSC_FALSE;
1165: }
1166: return(0);
1167: }
1171: /*@C
1172: PetscOptionsGetReal - Gets the double precision value for a particular
1173: option in the database.
1175: Not Collective
1177: Input Parameters:
1178: + pre - string to prepend to each name or PETSC_NULL
1179: - name - the option one is seeking
1181: Output Parameter:
1182: + dvalue - the double value to return
1183: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1185: Level: beginner
1187: Concepts: options database^has double
1189: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1190: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsTruth(),
1191: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1192: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1193: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1194: PetscOptionsList(), PetscOptionsEList()
1195: @*/
1196: PetscErrorCode PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1197: {
1198: char *value;
1200: PetscTruth flag;
1205: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1206: if (flag) {
1207: if (!value) {if (flg) *flg = PETSC_FALSE;}
1208: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1209: } else {
1210: if (flg) *flg = PETSC_FALSE;
1211: }
1212: return(0);
1213: }
1217: /*@C
1218: PetscOptionsGetScalar - Gets the scalar value for a particular
1219: option in the database.
1221: Not Collective
1223: Input Parameters:
1224: + pre - string to prepend to each name or PETSC_NULL
1225: - name - the option one is seeking
1227: Output Parameter:
1228: + dvalue - the double value to return
1229: - flg - PETSC_TRUE if found, else PETSC_FALSE
1231: Level: beginner
1233: Usage:
1234: A complex number 2+3i can be specified as 2,3 at the command line.
1235: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1237: Concepts: options database^has scalar
1239: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1240: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1241: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1242: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1243: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1244: PetscOptionsList(), PetscOptionsEList()
1245: @*/
1246: PetscErrorCode PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1247: {
1248: char *value;
1249: PetscTruth flag;
1255: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1256: if (flag) {
1257: if (!value) {
1258: if (flg) *flg = PETSC_FALSE;
1259: } else {
1260: #if !defined(PETSC_USE_COMPLEX)
1261: PetscOptionsAtod(value,dvalue);
1262: #else
1263: PetscReal re=0.0,im=0.0;
1264: PetscToken *token;
1265: char *tvalue = 0;
1267: PetscTokenCreate(value,',',&token);
1268: PetscTokenFind(token,&tvalue);
1269: if (!tvalue) { SETERRQ(PETSC_ERR_ARG_WRONG,"unknown string specified\n"); }
1270: PetscOptionsAtod(tvalue,&re);
1271: PetscTokenFind(token,&tvalue);
1272: if (!tvalue) { /* Unknown separator used. using only real value */
1273: *dvalue = re;
1274: } else {
1275: PetscOptionsAtod(tvalue,&im);
1276: *dvalue = re + PETSC_i*im;
1277: }
1278: PetscTokenDestroy(token);
1279: #endif
1280: if (flg) *flg = PETSC_TRUE;
1281: }
1282: } else { /* flag */
1283: if (flg) *flg = PETSC_FALSE;
1284: }
1285: return(0);
1286: }
1290: /*@C
1291: PetscOptionsGetRealArray - Gets an array of double precision values for a
1292: particular option in the database. The values must be separated with
1293: commas with no intervening spaces.
1295: Not Collective
1297: Input Parameters:
1298: + pre - string to prepend to each name or PETSC_NULL
1299: . name - the option one is seeking
1300: - nmax - maximum number of values to retrieve
1302: Output Parameters:
1303: + dvalue - the double value to return
1304: . nmax - actual number of values retreived
1305: - flg - PETSC_TRUE if found, else PETSC_FALSE
1307: Level: beginner
1309: Concepts: options database^array of doubles
1311: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1312: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsTruth(),
1313: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1314: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1315: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1316: PetscOptionsList(), PetscOptionsEList()
1317: @*/
1318: PetscErrorCode PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],PetscInt *nmax,PetscTruth *flg)
1319: {
1320: char *value;
1322: PetscInt n = 0;
1323: PetscTruth flag;
1324: PetscToken *token;
1329: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1330: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1331: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1333: if (flg) *flg = PETSC_TRUE;
1335: PetscTokenCreate(value,',',&token);
1336: PetscTokenFind(token,&value);
1337: while (n < *nmax) {
1338: if (!value) break;
1339: PetscOptionsAtod(value,dvalue++);
1340: PetscTokenFind(token,&value);
1341: n++;
1342: }
1343: PetscTokenDestroy(token);
1344: *nmax = n;
1345: return(0);
1346: }
1350: /*@C
1351: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1352: option in the database. The values must be separated with commas with
1353: no intervening spaces.
1355: Not Collective
1357: Input Parameters:
1358: + pre - string to prepend to each name or PETSC_NULL
1359: . name - the option one is seeking
1360: - nmax - maximum number of values to retrieve
1362: Output Parameter:
1363: + dvalue - the integer values to return
1364: . nmax - actual number of values retreived
1365: - flg - PETSC_TRUE if found, else PETSC_FALSE
1367: Level: beginner
1369: Concepts: options database^array of ints
1371: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1372: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1373: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1374: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1375: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1376: PetscOptionsList(), PetscOptionsEList()
1377: @*/
1378: PetscErrorCode PetscOptionsGetIntArray(const char pre[],const char name[],PetscInt dvalue[],PetscInt *nmax,PetscTruth *flg)
1379: {
1380: char *value;
1382: PetscInt n = 0;
1383: PetscTruth flag;
1384: PetscToken *token;
1389: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1390: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1391: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1393: if (flg) *flg = PETSC_TRUE;
1395: PetscTokenCreate(value,',',&token);
1396: PetscTokenFind(token,&value);
1397: while (n < *nmax) {
1398: if (!value) break;
1399: PetscOptionsAtoi(value,dvalue);
1400: dvalue++;
1401: PetscTokenFind(token,&value);
1402: n++;
1403: }
1404: PetscTokenDestroy(token);
1405: *nmax = n;
1406: return(0);
1407: }
1411: /*@C
1412: PetscOptionsGetString - Gets the string value for a particular option in
1413: the database.
1415: Not Collective
1417: Input Parameters:
1418: + pre - string to prepend to name or PETSC_NULL
1419: . name - the option one is seeking
1420: - len - maximum string length
1422: Output Parameters:
1423: + string - location to copy string
1424: - flg - PETSC_TRUE if found, else PETSC_FALSE
1426: Level: beginner
1428: Fortran Note:
1429: The Fortran interface is slightly different from the C/C++
1430: interface (len is not used). Sample usage in Fortran follows
1431: .vb
1432: character *20 string
1433: integer flg, ierr
1434: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1435: .ve
1437: Concepts: options database^string
1439: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1440: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1441: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1442: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1443: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1444: PetscOptionsList(), PetscOptionsEList()
1445: @*/
1446: PetscErrorCode PetscOptionsGetString(const char pre[],const char name[],char string[],size_t len,PetscTruth *flg)
1447: {
1448: char *value;
1450: PetscTruth flag;
1455: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1456: if (!flag) {
1457: if (flg) *flg = PETSC_FALSE;
1458: } else {
1459: if (flg) *flg = PETSC_TRUE;
1460: if (value) {
1461: PetscStrncpy(string,value,len);
1462: } else {
1463: PetscMemzero(string,len);
1464: }
1465: }
1466: return(0);
1467: }
1471: /*@C
1472: PetscOptionsGetStringArray - Gets an array of string values for a particular
1473: option in the database. The values must be separated with commas with
1474: no intervening spaces.
1476: Not Collective
1478: Input Parameters:
1479: + pre - string to prepend to name or PETSC_NULL
1480: . name - the option one is seeking
1481: - nmax - maximum number of strings
1483: Output Parameter:
1484: + strings - location to copy strings
1485: - flg - PETSC_TRUE if found, else PETSC_FALSE
1487: Level: beginner
1489: Notes:
1490: The user should pass in an array of pointers to char, to hold all the
1491: strings returned by this function.
1493: The user is responsible for deallocating the strings that are
1494: returned. The Fortran interface for this routine is not supported.
1496: Contributed by Matthew Knepley.
1498: Concepts: options database^array of strings
1500: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1501: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsTruth(),
1502: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1503: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1504: PetscOptionsTruthGroupBegin(), PetscOptionsTruthGroup(), PetscOptionsTruthGroupEnd(),
1505: PetscOptionsList(), PetscOptionsEList()
1506: @*/
1507: PetscErrorCode PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],PetscInt *nmax,PetscTruth *flg)
1508: {
1509: char *value;
1511: PetscInt n;
1512: PetscTruth flag;
1513: PetscToken *token;
1514:
1518: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1519: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1520: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1521: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1522: if (flg) *flg = PETSC_TRUE;
1524: PetscTokenCreate(value,',',&token);
1525: PetscTokenFind(token,&value);
1526: n = 0;
1527: while (n < *nmax) {
1528: if (!value) break;
1529: PetscStrallocpy(value,&strings[n]);
1530: PetscTokenFind(token,&value);
1531: n++;
1532: }
1533: PetscTokenDestroy(token);
1534: *nmax = n;
1535: return(0);
1536: }
1540: /*@C
1541: PetscOptionsAllUsed - Returns a count of the number of options in the
1542: database that have never been selected.
1544: Not Collective
1546: Output Parameter:
1547: . N - count of options not used
1549: Level: advanced
1551: .seealso: PetscOptionsPrint()
1552: @*/
1553: PetscErrorCode PetscOptionsAllUsed(int *N)
1554: {
1555: PetscInt i,n = 0;
1558: for (i=0; i<options->N; i++) {
1559: if (!options->used[i]) { n++; }
1560: }
1561: *N = n;
1562: return(0);
1563: }
1567: /*@
1568: PetscOptionsLeft - Prints to screen any options that were set and never used.
1570: Not collective
1572: Options Database Key:
1573: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1575: Level: advanced
1577: .seealso: PetscOptionsAllUsed()
1578: @*/
1579: PetscErrorCode PetscOptionsLeft(void)
1580: {
1582: PetscInt i;
1585: for (i=0; i<options->N; i++) {
1586: if (!options->used[i]) {
1587: if (options->values[i]) {
1588: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1589: } else {
1590: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1591: }
1592: }
1593: }
1594: return(0);
1595: }
1598: /*
1599: PetscOptionsCreate - Creates the empty options database.
1601: */
1604: PetscErrorCode PetscOptionsCreate(void)
1605: {
1609: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1610: PetscMemzero(options->used,MAXOPTIONS*sizeof(PetscTruth));
1611: options->namegiven = PETSC_FALSE;
1612: options->N = 0;
1613: options->Naliases = 0;
1614: options->numbermonitors = 0;
1615:
1616: return(0);
1617: }
1621: /*@
1622: PetscOptionsSetFromOptions - Sets various SNES and KSP parameters from user options.
1624: Collective on PETSC_COMM_WORLD
1626: Options Database Keys:
1627: + -options_monitor <optional filename> - prints the names and values of all
1628: runtime options as they are set. The monitor functionality is not
1629: available for options set through a file, environment variable, or on
1630: the command line. Only options set after PetscInitialize completes will
1631: be monitored.
1632: . -options_cancelmonitors - cancel all options database monitors
1634: Notes:
1635: To see all options, run your program with the -help option or consult
1636: the users manual.
1638: Level: intermediate
1640: .keywords: set, options, database
1641: @*/
1642: PetscErrorCode PetscOptionsSetFromOptions()
1643: {
1644: PetscTruth flg;
1645: PetscErrorCode ierr;
1646: char monfilename[PETSC_MAX_PATH_LEN];
1647: PetscViewer monviewer;
1651: PetscOptionsBegin(PETSC_COMM_WORLD,"","Options database options","PetscOptions");
1652: PetscOptionsString("-options_monitor","Monitor options database","PetscOptionsSetMonitor","stdout",monfilename,PETSC_MAX_PATH_LEN,&flg);
1653: if (flg && (!options->numbermonitors)) {
1654: PetscViewerASCIIOpen(PETSC_COMM_WORLD,monfilename,&monviewer);
1655: PetscOptionsSetMonitor(PetscOptionsDefaultMonitor,monviewer,(PetscErrorCode (*)(void*))PetscViewerDestroy);
1656: }
1657:
1658: PetscOptionsName("-options_cancelmonitors","Cancel all options database monitors","PetscOptionsClearMonitor",&flg);
1659: if (flg) { PetscOptionsClearMonitor(); }
1660:
1661: PetscOptionsEnd();
1663: return(0);
1664: }
1669: /*@C
1670: PetscOptionsDefaultMonitor - Print all options set value events.
1672: Collective on PETSC_COMM_WORLD
1674: Input Parameters:
1675: + name - option name string
1676: . value - option value string
1677: - dummy - unused monitor context
1679: Level: intermediate
1681: .keywords: PetscOptions, default, monitor
1683: .seealso: PetscOptionsSetMonitor()
1684: @*/
1685: PetscErrorCode PetscOptionsDefaultMonitor(const char name[], const char value[], void *dummy)
1686: {
1688: PetscViewer viewer = (PetscViewer) dummy;
1691: if (!viewer) viewer = PETSC_VIEWER_STDOUT_(PETSC_COMM_WORLD);
1692: PetscViewerASCIIPrintf(viewer,"Setting option: %s = %s\n",name,value);
1693: return(0);
1694: }
1698: /*@C
1699: PetscOptionsSetMonitor - Sets an ADDITIONAL function to be called at every method that
1700: modified the PETSc options database.
1701:
1702: Not collective
1704: Input Parameters:
1705: + monitor - pointer to function (if this is PETSC_NULL, it turns off monitoring
1706: . mctx - [optional] context for private data for the
1707: monitor routine (use PETSC_NULL if no context is desired)
1708: - monitordestroy - [optional] routine that frees monitor context
1709: (may be PETSC_NULL)
1711: Calling Sequence of monitor:
1712: $ monitor (const char name[], const char value[], void *mctx)
1714: + name - option name string
1715: . value - option value string
1716: - mctx - optional monitoring context, as set by PetscOptionsSetMonitor()
1718: Options Database Keys:
1719: + -options_monitor - sets PetscOptionsDefaultMonitor()
1720: - -options_cancelmonitors - cancels all monitors that have
1721: been hardwired into a code by
1722: calls to PetscOptionsSetMonitor(), but
1723: does not cancel those set via
1724: the options database.
1726: Notes:
1727: The default is to do nothing. To print the name and value of options
1728: being inserted into the database, use PetscOptionsDefaultMonitor() as the monitoring routine,
1729: with a null monitoring context.
1731: Several different monitoring routines may be set by calling
1732: PetscOptionsSetMonitor() multiple times; all will be called in the
1733: order in which they were set.
1735: Level: beginner
1737: .keywords: PetscOptions, set, monitor
1739: .seealso: PetscOptionsDefaultMonitor(), PetscOptionsClearMonitor()
1740: @*/
1741: PetscErrorCode PetscOptionsSetMonitor(PetscErrorCode (*monitor)(const char name[], const char value[], void*),void *mctx,PetscErrorCode (*monitordestroy)(void*))
1742: {
1744: if (options->numbermonitors >= MAXOPTIONSMONITORS) {
1745: SETERRQ(PETSC_ERR_ARG_OUTOFRANGE,"Too many PetscOptions monitors set");
1746: }
1747: options->monitor[options->numbermonitors] = monitor;
1748: options->monitordestroy[options->numbermonitors] = monitordestroy;
1749: options->monitorcontext[options->numbermonitors++] = (void*)mctx;
1750: return(0);
1751: }
1755: /*@
1756: PetscOptionsClearMonitor - Clears all monitors for a PetscOptions object.
1758: Not collective
1760: Options Database Key:
1761: . -options_cancelmonitors - Cancels all monitors that have
1762: been hardwired into a code by calls to PetscOptionsSetMonitor(),
1763: but does not cancel those set via the options database.
1765: Level: intermediate
1767: .keywords: PetscOptions, set, monitor
1769: .seealso: PetscOptionsDefaultMonitor(), PetscOptionsSetMonitor()
1770: @*/
1771: PetscErrorCode PetscOptionsClearMonitor()
1772: {
1774: PetscInt i;
1777: for (i=0; i<options->numbermonitors; i++) {
1778: if (options->monitordestroy[i]) {
1779: (*options->monitordestroy[i])(options->monitorcontext[i]);
1780: }
1781: }
1782: options->numbermonitors = 0;
1783: return(0);
1784: }