Actual source code: options.c
1: /*$Id: options.c,v 1.252 2001/08/07 21:28:54 bsmith Exp $*/
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) && !defined(__cplusplus)
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 256
27: #define MAXALIASES 25
29: typedef struct {
30: int N,argc,Naliases;
31: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
32: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
33: int used[MAXOPTIONS];
34: PetscTruth namegiven;
35: char programname[PETSC_MAX_PATH_LEN]; /* HP includes entire path in name */
36: } PetscOptionsTable;
38: static PetscOptionsTable *options = 0;
42: int PetscOptionsAtoi(const char name[],int *a)
43: {
44: int i,ierr,len;
45: PetscTruth decide,tdefault,mouse;
48: PetscStrlen(name,&len);
49: if (!len) SETERRQ(1,"character string of length zero has no numerical value");
51: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
52: if (!tdefault) {
53: PetscStrcasecmp(name,"DEFAULT",&tdefault);
54: }
55: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
56: if (!decide) {
57: PetscStrcasecmp(name,"DECIDE",&decide);
58: }
59: PetscStrcasecmp(name,"mouse",&mouse);
61: if (tdefault) {
62: *a = PETSC_DEFAULT;
63: } else if (decide) {
64: *a = PETSC_DECIDE;
65: } else if (mouse) {
66: *a = -1;
67: } else {
68: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
69: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
70: }
71: for (i=1; i<len; i++) {
72: if (name[i] < '0' || name[i] > '9') {
73: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
74: }
75: }
76: *a = atoi(name);
77: }
78: return(0);
79: }
83: int PetscOptionsAtod(const char name[],PetscReal *a)
84: {
85: int ierr,len;
86: PetscTruth decide,tdefault;
89: PetscStrlen(name,&len);
90: if (!len) SETERRQ(1,"character string of length zero has no numerical value");
92: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
93: if (!tdefault) {
94: PetscStrcasecmp(name,"DEFAULT",&tdefault);
95: }
96: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
97: if (!decide) {
98: PetscStrcasecmp(name,"DECIDE",&decide);
99: }
101: if (tdefault) {
102: *a = PETSC_DEFAULT;
103: } else if (decide) {
104: *a = PETSC_DECIDE;
105: } else {
106: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
107: SETERRQ1(1,"Input string %s has no numeric value ",name);
108: }
109: *a = atof(name);
110: }
111: return(0);
112: }
116: /*@C
117: PetscGetProgramName - Gets the name of the running program.
119: Not Collective
121: Input Parameter:
122: . len - length of the string name
124: Output Parameter:
125: . name - the name of the running program
127: Level: advanced
129: Notes:
130: The name of the program is copied into the user-provided character
131: array of length len. On some machines the program name includes
132: its entire path, so one should generally set len >= PETSC_MAX_PATH_LEN.
133: @*/
134: int PetscGetProgramName(char name[],int len)
135: {
139: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
140: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
141: PetscStrncpy(name,options->programname,len);
142: return(0);
143: }
147: int PetscSetProgramName(const char name[])
148: {
152: options->namegiven = PETSC_TRUE;
153: PetscStrncpy(options->programname,name,PETSC_MAX_PATH_LEN);
154: return(0);
155: }
159: /*@C
160: PetscOptionsInsertString - Inserts options into the database from a string
162: Not collective: but only processes that call this routine will set the options
163: included in the file
165: Input Parameter:
166: . in_str - string that contains options seperated by blanks
169: Level: intermediate
171: Contributed by Boyana Norris
173: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
174: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
175: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
176: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
177: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
178: PetscOptionsList(), PetscOptionsEList(), PetscOptionsInsertFile()
180: @*/
181: int PetscOptionsInsertString(const char in_str[])
182: {
183: char *str,*first,*second,*third,*final;
184: int len,ierr;
185: PetscToken *token;
188: PetscStrlen(in_str,&len);
189: PetscMalloc(len,&str);
190: PetscStrcpy(str, in_str);
192: PetscTokenCreate(str,' ',&token);
193: PetscTokenFind(token,&first);
194: PetscTokenFind(token,&second);
195: if (first && first[0] == '-') {
196: if (second) {final = second;} else {final = first;}
197: PetscStrlen(final,&len);
198: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
199: len--; final[len] = 0;
200: }
201: PetscOptionsSetValue(first,second);
202: } else if (first) {
203: PetscTruth match;
204:
205: PetscStrcmp(first,"alias",&match);
206: if (match) {
207: PetscTokenFind(token,&third);
208: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options string:alias missing (%s)",second);
209: PetscStrlen(third,&len);
210: if (third[len-1] == 'n') third[len-1] = 0;
211: PetscOptionsSetAlias(second,third);
212: }
213: }
214: PetscTokenDestroy(token);
215: PetscFree(str);
216:
217: return(0);
218: }
222: /*@C
223: PetscOptionsInsertFile - Inserts options into the database from a file.
225: Not collective: but only processes that call this routine will set the options
226: included in the file
228: Input Parameter:
229: . file - name of file
232: Level: intermediate
234: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
235: PetscOptionsGetReal(), PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
236: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
237: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
238: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
239: PetscOptionsList(), PetscOptionsEList()
241: @*/
242: int PetscOptionsInsertFile(const char file[])
243: {
244: char string[128],fname[PETSC_MAX_PATH_LEN],*first,*second,*third,*final;
245: int len,ierr,i,startIndex;
246: FILE *fd;
247: PetscToken *token;
250: PetscFixFilename(file,fname);
251: fd = fopen(fname,"r");
252: if (fd) {
253: while (fgets(string,128,fd)) {
254: /* Comments are indicated by #, ! or % in the first column */
255: if (string[0] == '#') continue;
256: if (string[0] == '!') continue;
257: if (string[0] == '%') continue;
259: PetscStrlen(string,&len);
261: /* replace tabs, ^M with " " */
262: for (i=0; i<len; i++) {
263: if (string[i] == '\t' || string[i] == '\r') {
264: string[i] = ' ';
265: }
266: }
267: for(startIndex = 0; startIndex < len-1; startIndex++) {
268: if (string[startIndex] != ' ') break;
269: }
270: PetscTokenCreate(&string[startIndex],' ',&token);
271: PetscTokenFind(token,&first);
272: PetscTokenFind(token,&second);
273: if (first && first[0] == '-') {
274: if (second) {final = second;} else {final = first;}
275: PetscStrlen(final,&len);
276: while (len > 0 && (final[len-1] == ' ' || final[len-1] == '\n')) {
277: len--; final[len] = 0;
278: }
279: PetscOptionsSetValue(first,second);
280: } else if (first) {
281: PetscTruth match;
283: PetscStrcmp(first,"alias",&match);
284: if (match) {
285: PetscTokenFind(token,&third);
286: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
287: PetscStrlen(third,&len);
288: if (third[len-1] == '\n') third[len-1] = 0;
289: PetscOptionsSetAlias(second,third);
290: }
291: }
292: PetscTokenDestroy(token);
293: }
294: fclose(fd);
295: }
296: return(0);
297: }
301: /*@C
302: PetscOptionsInsert - Inserts into the options database from the command line,
303: the environmental variable and a file.
305: Input Parameters:
306: + argc - count of number of command line arguments
307: . args - the command line arguments
308: - file - optional filename, defaults to ~username/.petscrc
310: Note:
311: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
312: the user does not typically need to call this routine. PetscOptionsInsert()
313: can be called several times, adding additional entries into the database.
315: Level: advanced
317: Concepts: options database^adding
319: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
320: @*/
321: int PetscOptionsInsert(int *argc,char ***args,const char file[])
322: {
323: int ierr,rank;
324: char pfile[PETSC_MAX_PATH_LEN];
325: PetscToken *token;
328: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
330: options->argc = (argc) ? *argc : 0;
331: options->args = (args) ? *args : 0;
333: if (file) {
334: PetscOptionsInsertFile(file);
335: } else {
336: PetscGetHomeDirectory(pfile,240);
337: PetscStrcat(pfile,"/.petscrc");
338: PetscOptionsInsertFile(pfile);
339: }
341: /* insert environmental options */
342: {
343: char *eoptions = 0,*second,*first;
344: int len=0;
345: if (!rank) {
346: eoptions = (char*)getenv("PETSC_OPTIONS");
347: PetscStrlen(eoptions,&len);
348: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
349: } else {
350: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
351: if (len) {
352: PetscMalloc((len+1)*sizeof(char*),&eoptions);
353: }
354: }
355: if (len) {
356: MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
357: eoptions[len] = 0;
358: PetscTokenCreate(eoptions,' ',&token);
359: PetscTokenFind(token,&first);
360: while (first) {
361: if (first[0] != '-') {PetscTokenFind(token,&first); continue;}
362: PetscTokenFind(token,&second);
363: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
364: PetscOptionsSetValue(first,(char *)0);
365: first = second;
366: } else {
367: PetscOptionsSetValue(first,second);
368: PetscTokenFind(token,&first);
369: }
370: }
371: PetscTokenDestroy(token);
372: if (rank) {PetscFree(eoptions);}
373: }
374: }
376: /* insert command line options */
377: if (argc && args && *argc) {
378: int left = *argc - 1;
379: char **eargs = *args + 1;
380: PetscTruth isoptions_file,isp4,tisp4,isp4yourname,isp4rmrank;
382: while (left) {
383: PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
384: PetscStrcmp(eargs[0],"-p4pg",&isp4);
385: PetscStrcmp(eargs[0],"-p4yourname",&isp4yourname);
386: PetscStrcmp(eargs[0],"-p4rmrank",&isp4rmrank);
387: PetscStrcmp(eargs[0],"-p4wd",&tisp4);
388: isp4 = (PetscTruth) (isp4 || tisp4);
389: PetscStrcmp(eargs[0],"-np",&tisp4);
390: isp4 = (PetscTruth) (isp4 || tisp4);
391: PetscStrcmp(eargs[0],"-p4amslave",&tisp4);
393: if (eargs[0][0] != '-') {
394: eargs++; left--;
395: } else if (isoptions_file) {
396: PetscOptionsInsertFile(eargs[1]);
397: eargs += 2; left -= 2;
399: /*
400: These are "bad" options that MPICH, etc put on the command line
401: we strip them out here.
402: */
403: } else if (tisp4 || isp4rmrank) {
404: eargs += 1; left -= 1;
405: } else if (isp4 || isp4yourname) {
406: eargs += 2; left -= 2;
407: } else if ((left < 2) || ((eargs[1][0] == '-') &&
408: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
409: PetscOptionsSetValue(eargs[0],PETSC_NULL);
410: eargs++; left--;
411: } else {
412: PetscOptionsSetValue(eargs[0],eargs[1]);
413: eargs += 2; left -= 2;
414: }
415: }
416: }
417: return(0);
418: }
422: /*@C
423: PetscOptionsPrint - Prints the options that have been loaded. This is
424: useful for debugging purposes.
426: Collective on PETSC_COMM_WORLD
428: Input Parameter:
429: . FILE fd - location to print options (usually stdout or stderr)
431: Options Database Key:
432: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
434: Level: advanced
436: Concepts: options database^printing
438: .seealso: PetscOptionsAllUsed()
439: @*/
440: int PetscOptionsPrint(FILE *fd)
441: {
442: int i,ierr;
445: if (!fd) fd = stdout;
446: if (!options) {PetscOptionsInsert(0,0,0);}
447: for (i=0; i<options->N; i++) {
448: if (options->values[i]) {
449: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %s\n",options->names[i],options->values[i]);
450: } else {
451: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s\n",options->names[i]);
452: }
453: }
454: return(0);
455: }
459: /*@C
460: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
462: Not Collective
464: Output Parameter:
465: . copts - pointer where string pointer is stored
467: Level: advanced
469: Concepts: options database^listing
471: .seealso: PetscOptionsAllUsed(), PetscOptionsPrint()
472: @*/
473: int PetscOptionsGetAll(char *copts[])
474: {
475: int i,ierr,len = 1,lent;
476: char *coptions;
479: if (!options) {PetscOptionsInsert(0,0,0);}
481: /* count the length of the required string */
482: for (i=0; i<options->N; i++) {
483: PetscStrlen(options->names[i],&lent);
484: len += 2 + lent;
485: if (options->values[i]) {
486: PetscStrlen(options->values[i],&lent);
487: len += 1 + lent;
488: }
489: }
490: PetscMalloc(len*sizeof(char),&coptions);
491: coptions[0] = 0;
492: for (i=0; i<options->N; i++) {
493: PetscStrcat(coptions,"-");
494: PetscStrcat(coptions,options->names[i]);
495: PetscStrcat(coptions," ");
496: if (options->values[i]) {
497: PetscStrcat(coptions,options->values[i]);
498: PetscStrcat(coptions," ");
499: }
500: }
501: *copts = coptions;
502: return(0);
503: }
507: /*@C
508: PetscOptionsDestroy - Destroys the option database.
510: Note:
511: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
512: typically does not need to call this routine.
514: Level: developer
516: .seealso: PetscOptionsInsert()
517: @*/
518: int PetscOptionsDestroy(void)
519: {
520: int i;
523: if (!options) return(0);
524: for (i=0; i<options->N; i++) {
525: if (options->names[i]) free(options->names[i]);
526: if (options->values[i]) free(options->values[i]);
527: }
528: for (i=0; i<options->Naliases; i++) {
529: free(options->aliases1[i]);
530: free(options->aliases2[i]);
531: }
532: free(options);
533: options = 0;
534: return(0);
535: }
539: /*@C
540: PetscOptionsSetValue - Sets an option name-value pair in the options
541: database, overriding whatever is already present.
543: Not collective, but setting values on certain processors could cause problems
544: for parallel objects looking for options.
546: Input Parameters:
547: + name - name of option, this SHOULD have the - prepended
548: - value - the option value (not used for all options)
550: Level: intermediate
552: Note:
553: Only some options have values associated with them, such as
554: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
556: Concepts: options database^adding option
558: .seealso: PetscOptionsInsert()
559: @*/
560: int PetscOptionsSetValue(const char iname[],const char value[])
561: {
562: int len,N,n,i,ierr;
563: char **names;
564: const char *name = (char*)iname;
565: PetscTruth gt,match;
568: if (!options) {PetscOptionsInsert(0,0,0);}
570: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
571: PetscStrcmp(name,"-h",&match);
572: if (match) name = "-help";
574: name++;
575: /* first check against aliases */
576: N = options->Naliases;
577: for (i=0; i<N; i++) {
578: PetscStrcmp(options->aliases1[i],name,&match);
579: if (match) {
580: name = options->aliases2[i];
581: break;
582: }
583: }
585: N = options->N;
586: n = N;
587: names = options->names;
588:
589: for (i=0; i<N; i++) {
590: PetscStrcmp(names[i],name,&match);
591: PetscStrgrt(names[i],name,>);
592: if (match) {
593: if (options->values[i]) free(options->values[i]);
594: PetscStrlen(value,&len);
595: if (len) {
596: options->values[i] = (char*)malloc((len+1)*sizeof(char));
597: PetscStrcpy(options->values[i],value);
598: } else { options->values[i] = 0;}
599: return(0);
600: } else if (gt) {
601: n = i;
602: break;
603: }
604: }
605: if (N >= MAXOPTIONS) {
606: SETERRQ1(1,"No more room in option table, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXOPTIONS\n",MAXOPTIONS);
607: }
608: /* shift remaining values down 1 */
609: for (i=N; i>n; i--) {
610: names[i] = names[i-1];
611: options->values[i] = options->values[i-1];
612: options->used[i] = options->used[i-1];
613: }
614: /* insert new name and value */
615: PetscStrlen(name,&len);
616: names[n] = (char*)malloc((len+1)*sizeof(char));
617: PetscStrcpy(names[n],name);
618: if (value) {
619: PetscStrlen(value,&len);
620: options->values[n] = (char*)malloc((len+1)*sizeof(char));
621: PetscStrcpy(options->values[n],value);
622: } else {options->values[n] = 0;}
623: options->used[n] = 0;
624: options->N++;
625: return(0);
626: }
630: /*@C
631: PetscOptionsClearValue - Clears an option name-value pair in the options
632: database, overriding whatever is already present.
634: Not Collective, but setting values on certain processors could cause problems
635: for parallel objects looking for options.
637: Input Parameter:
638: . name - name of option, this SHOULD have the - prepended
640: Level: intermediate
642: Concepts: options database^removing option
643: .seealso: PetscOptionsInsert()
644: @*/
645: int PetscOptionsClearValue(const char iname[])
646: {
647: int N,n,i,ierr;
648: char **names,*name=(char*)iname;
649: PetscTruth gt,match;
652: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
653: if (!options) {PetscOptionsInsert(0,0,0);}
655: name++;
657: N = options->N; n = 0;
658: names = options->names;
659:
660: for (i=0; i<N; i++) {
661: PetscStrcmp(names[i],name,&match);
662: PetscStrgrt(names[i],name,>);
663: if (match) {
664: if (options->values[i]) free(options->values[i]);
665: break;
666: } else if (gt) {
667: return(0); /* it was not listed */
668: }
669: n++;
670: }
671: if (n == N) return(0); /* it was not listed */
673: /* shift remaining values down 1 */
674: for (i=n; i<N-1; i++) {
675: names[i] = names[i+1];
676: options->values[i] = options->values[i+1];
677: options->used[i] = options->used[i+1];
678: }
679: options->N--;
680: return(0);
681: }
685: /*@C
686: PetscOptionsReject - Generates an error if a certain option is given.
688: Not Collective, but setting values on certain processors could cause problems
689: for parallel objects looking for options.
691: Input Parameters:
692: + name - the option one is seeking
693: - mess - error message (may be PETSC_NULL)
695: Level: advanced
697: Concepts: options database^rejecting option
699: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
700: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
701: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
702: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
703: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
704: PetscOptionsList(), PetscOptionsEList()
705: @*/
706: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
707: {
708: int ierr,len,n = options->Naliases;
709: char *newname = (char *)inewname,*oldname = (char*)ioldname;
712: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
713: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
714: if (n >= MAXALIASES) {
715: SETERRQ1(PETSC_ERR_MEM,"You have defined to many PETSc options aliases, limit %d recompile \n src/sys/src/objects/options.c with larger value for MAXALIASES",MAXALIASES);
716: }
718: newname++; oldname++;
719: PetscStrlen(newname,&len);
720: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
721: PetscStrcpy(options->aliases1[n],newname);
722: PetscStrlen(oldname,&len);
723: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
724: PetscStrcpy(options->aliases2[n],oldname);
725: options->Naliases++;
726: return(0);
727: }
731: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
732: {
733: int i,N,ierr,len;
734: char **names,tmp[256];
735: PetscTruth match;
738: if (!options) {PetscOptionsInsert(0,0,0);}
739: N = options->N;
740: names = options->names;
742: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
744: /* append prefix to name */
745: if (pre) {
746: PetscStrncpy(tmp,pre,256);
747: PetscStrlen(tmp,&len);
748: PetscStrncat(tmp,name+1,256-len-1);
749: } else {
750: PetscStrncpy(tmp,name+1,256);
751: }
753: /* slow search */
754: *flg = PETSC_FALSE;
755: for (i=0; i<N; i++) {
756: PetscStrcmp(names[i],tmp,&match);
757: if (match) {
758: *value = options->values[i];
759: options->used[i]++;
760: *flg = PETSC_TRUE;
761: break;
762: }
763: }
764: return(0);
765: }
769: /*@C
770: PetscOptionsReject - Generates an error if a certain option is given.
772: Not Collective, but setting values on certain processors could cause problems
773: for parallel objects looking for options.
775: Input Parameters:
776: + name - the option one is seeking
777: - mess - error message (may be PETSC_NULL)
779: Level: advanced
781: Concepts: options database^rejecting option
783: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),OptionsHasName(),
784: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
785: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
786: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
787: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
788: PetscOptionsList(), PetscOptionsEList()
789: @*/
790: int PetscOptionsReject(const char name[],const char mess[])
791: {
792: int ierr;
793: PetscTruth flag;
796: PetscOptionsHasName(PETSC_NULL,name,&flag);
797: if (flag) {
798: if (mess) {
799: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
800: } else {
801: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
802: }
803: }
804: return(0);
805: }
809: /*@C
810: PetscOptionsHasName - Determines whether a certain option is given in the database.
812: Not Collective
814: Input Parameters:
815: + name - the option one is seeking
816: - pre - string to prepend to the name or PETSC_NULL
818: Output Parameters:
819: . flg - PETSC_TRUE if found else PETSC_FALSE.
821: Level: beginner
823: Concepts: options database^has option name
825: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
826: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
827: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
828: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
829: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
830: PetscOptionsList(), PetscOptionsEList()
831: @*/
832: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
833: {
834: char *value;
835: int ierr;
836: PetscTruth isfalse,flag;
839: PetscOptionsFindPair_Private(pre,name,&value,&flag);
841: /* remove if turned off */
842: if (flag) {
843: PetscStrcmp(value,"FALSE",&isfalse);
844: if (isfalse) flag = PETSC_FALSE;
845: PetscStrcmp(value,"NO",&isfalse);
846: if (isfalse) flag = PETSC_FALSE;
847: PetscStrcmp(value,"0",&isfalse);
848: if (isfalse) flag = PETSC_FALSE;
849: PetscStrcmp(value,"false",&isfalse);
850: if (isfalse) flag = PETSC_FALSE;
851: PetscStrcmp(value,"no",&isfalse);
852: }
853: if (flg) *flg = flag;
855: return(0);
856: }
860: /*@C
861: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
863: Not Collective
865: Input Parameters:
866: + pre - the string to prepend to the name or PETSC_NULL
867: - name - the option one is seeking
869: Output Parameter:
870: + ivalue - the integer value to return
871: - flg - PETSC_TRUE if found, else PETSC_FALSE
873: Level: beginner
875: Concepts: options database^has int
877: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
878: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical()
879: PetscOptionsInt(), PetscOptionsString(), PetscOptionsReal(), PetscOptionsLogical(),
880: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
881: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
882: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
883: PetscOptionsList(), PetscOptionsEList()
884: @*/
885: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
886: {
887: char *value;
888: int ierr;
889: PetscTruth flag;
894: PetscOptionsFindPair_Private(pre,name,&value,&flag);
895: if (flag) {
896: if (!value) {if (flg) *flg = PETSC_FALSE;}
897: else {
898: if (flg) *flg = PETSC_TRUE;
899: PetscOptionsAtoi(value,ivalue);
900: }
901: } else {
902: if (flg) *flg = PETSC_FALSE;
903: }
904: return(0);
905: }
909: /*@C
910: PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular
911: option in the database.
913: Not Collective
915: Input Parameters:
916: + pre - the string to prepend to the name or PETSC_NULL
917: - name - the option one is seeking
919: Output Parameter:
920: + ivalue - the logical value to return
921: - flg - PETSC_TRUE if found, else PETSC_FALSE
923: Level: beginner
925: Notes:
926: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
927: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
929: Concepts: options database^has logical
931: .seealso: PetscOptionsGetReal(), PetscOptionsHasName(), PetscOptionsGetString(),
932: PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsGetInt(), PetscOptionsLogical(),
933: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
934: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
935: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
936: PetscOptionsList(), PetscOptionsEList()
937: @*/
938: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
939: {
940: char *value;
941: PetscTruth flag,istrue,isfalse;
942: int ierr;
947: PetscOptionsFindPair_Private(pre,name,&value,&flag);
948: if (flag) {
949: if (flg) *flg = PETSC_TRUE;
950: if (!value) {
951: *ivalue = PETSC_TRUE;
952: } else {
953: *ivalue = PETSC_TRUE;
954: PetscStrcmp(value,"TRUE",&istrue);
955: if (istrue) return(0);
956: PetscStrcmp(value,"YES",&istrue);
957: if (istrue) return(0);
958: PetscStrcmp(value,"YES",&istrue);
959: if (istrue) return(0);
960: PetscStrcmp(value,"1",&istrue);
961: if (istrue) return(0);
962: PetscStrcmp(value,"true",&istrue);
963: if (istrue) return(0);
964: PetscStrcmp(value,"yes",&istrue);
965: if (istrue) return(0);
966: PetscStrcmp(value,"on",&istrue);
967: if (istrue) return(0);
969: *ivalue = PETSC_FALSE;
970: PetscStrcmp(value,"FALSE",&isfalse);
971: if (isfalse) return(0);
972: PetscStrcmp(value,"NO",&isfalse);
973: if (isfalse) return(0);
974: PetscStrcmp(value,"0",&isfalse);
975: if (isfalse) return(0);
976: PetscStrcmp(value,"false",&isfalse);
977: if (isfalse) return(0);
978: PetscStrcmp(value,"no",&isfalse);
979: if (isfalse) return(0);
980: PetscStrcmp(value,"off",&isfalse);
981: if (isfalse) return(0);
983: SETERRQ1(1,"Unknown logical value: %s",value);
984: }
985: } else {
986: if (flg) *flg = PETSC_FALSE;
987: }
988: return(0);
989: }
993: /*@C
994: PetscOptionsGetReal - Gets the double precision value for a particular
995: option in the database.
997: Not Collective
999: Input Parameters:
1000: + pre - string to prepend to each name or PETSC_NULL
1001: - name - the option one is seeking
1003: Output Parameter:
1004: + dvalue - the double value to return
1005: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
1007: Level: beginner
1009: Concepts: options database^has double
1011: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1012: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(),PetscOptionsLogical(),
1013: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1014: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1015: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1016: PetscOptionsList(), PetscOptionsEList()
1017: @*/
1018: int PetscOptionsGetReal(const char pre[],const char name[],PetscReal *dvalue,PetscTruth *flg)
1019: {
1020: char *value;
1021: int ierr;
1022: PetscTruth flag;
1027: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1028: if (flag) {
1029: if (!value) {if (flg) *flg = PETSC_FALSE;}
1030: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
1031: } else {
1032: if (flg) *flg = PETSC_FALSE;
1033: }
1034: return(0);
1035: }
1039: /*@C
1040: PetscOptionsGetScalar - Gets the scalar value for a particular
1041: option in the database.
1043: Not Collective
1045: Input Parameters:
1046: + pre - string to prepend to each name or PETSC_NULL
1047: - name - the option one is seeking
1049: Output Parameter:
1050: + dvalue - the double value to return
1051: - flg - PETSC_TRUE if found, else PETSC_FALSE
1053: Level: beginner
1055: Usage:
1056: A complex number 2+3i can be specified as 2,3 at the command line.
1057: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
1059: Concepts: options database^has scalar
1061: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1062: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1063: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1064: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1065: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1066: PetscOptionsList(), PetscOptionsEList()
1067: @*/
1068: int PetscOptionsGetScalar(const char pre[],const char name[],PetscScalar *dvalue,PetscTruth *flg)
1069: {
1070: char *value;
1071: PetscTruth flag;
1072: int ierr;
1077: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1078: if (flag) {
1079: if (!value) {
1080: if (flg) *flg = PETSC_FALSE;
1081: } else {
1082: #if !defined(PETSC_USE_COMPLEX)
1083: PetscOptionsAtod(value,dvalue);
1084: #else
1085: PetscReal re=0.0,im=0.0;
1086: PetscToken *token;
1087: char *tvalue = 0;
1089: PetscTokenCreate(value,',',&token);
1090: PetscTokenFind(token,&tvalue);
1091: if (!tvalue) { SETERRQ(1,"unknown string specified\n"); }
1092: PetscOptionsAtod(tvalue,&re);
1093: PetscTokenFind(token,&tvalue);
1094: if (!tvalue) { /* Unknown separator used. using only real value */
1095: *dvalue = re;
1096: } else {
1097: PetscOptionsAtod(tvalue,&im);
1098: *dvalue = re + PETSC_i*im;
1099: }
1100: PetscTokenDestroy(token);
1101: #endif
1102: if (flg) *flg = PETSC_TRUE;
1103: }
1104: } else { /* flag */
1105: if (flg) *flg = PETSC_FALSE;
1106: }
1107: return(0);
1108: }
1112: /*@C
1113: PetscOptionsGetRealArray - Gets an array of double precision values for a
1114: particular option in the database. The values must be separated with
1115: commas with no intervening spaces.
1117: Not Collective
1119: Input Parameters:
1120: + pre - string to prepend to each name or PETSC_NULL
1121: . name - the option one is seeking
1122: - nmax - maximum number of values to retrieve
1124: Output Parameters:
1125: + dvalue - the double value to return
1126: . nmax - actual number of values retreived
1127: - flg - PETSC_TRUE if found, else PETSC_FALSE
1129: Level: beginner
1131: Concepts: options database^array of doubles
1133: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1134: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsLogical(),
1135: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1136: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1137: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1138: PetscOptionsList(), PetscOptionsEList()
1139: @*/
1140: int PetscOptionsGetRealArray(const char pre[],const char name[],PetscReal dvalue[],int *nmax,PetscTruth *flg)
1141: {
1142: char *value;
1143: int n = 0,ierr;
1144: PetscTruth flag;
1145: PetscToken *token;
1150: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1151: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1152: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1154: if (flg) *flg = PETSC_TRUE;
1156: PetscTokenCreate(value,',',&token);
1157: PetscTokenFind(token,&value);
1158: while (n < *nmax) {
1159: if (!value) break;
1160: PetscOptionsAtod(value,dvalue++);
1161: PetscTokenFind(token,&value);
1162: n++;
1163: }
1164: PetscTokenDestroy(token);
1165: *nmax = n;
1166: return(0);
1167: }
1171: /*@C
1172: PetscOptionsGetIntArray - Gets an array of integer values for a particular
1173: option in the database. The values must be separated with commas with
1174: no intervening spaces.
1176: Not Collective
1178: Input Parameters:
1179: + pre - string to prepend to each name or PETSC_NULL
1180: . name - the option one is seeking
1181: - nmax - maximum number of values to retrieve
1183: Output Parameter:
1184: + dvalue - the integer values to return
1185: . nmax - actual number of values retreived
1186: - flg - PETSC_TRUE if found, else PETSC_FALSE
1188: Level: beginner
1190: Concepts: options database^array of ints
1192: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1193: PetscOptionsGetString(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1194: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1195: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1196: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1197: PetscOptionsList(), PetscOptionsEList()
1198: @*/
1199: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1200: {
1201: char *value;
1202: int n = 0,ierr;
1203: PetscTruth flag;
1204: PetscToken *token;
1209: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1210: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1211: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1213: if (flg) *flg = PETSC_TRUE;
1215: PetscTokenCreate(value,',',&token);
1216: PetscTokenFind(token,&value);
1217: while (n < *nmax) {
1218: if (!value) break;
1219: PetscOptionsAtoi(value,dvalue);
1220: dvalue++;
1221: PetscTokenFind(token,&value);
1222: n++;
1223: }
1224: PetscTokenDestroy(token);
1225: *nmax = n;
1226: return(0);
1227: }
1231: /*@C
1232: PetscOptionsGetString - Gets the string value for a particular option in
1233: the database.
1235: Not Collective
1237: Input Parameters:
1238: + pre - string to prepend to name or PETSC_NULL
1239: . name - the option one is seeking
1240: - len - maximum string length
1242: Output Parameters:
1243: + string - location to copy string
1244: - flg - PETSC_TRUE if found, else PETSC_FALSE
1246: Level: beginner
1248: Fortran Note:
1249: The Fortran interface is slightly different from the C/C++
1250: interface (len is not used). Sample usage in Fortran follows
1251: .vb
1252: character *20 string
1253: integer flg, ierr
1254: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1255: .ve
1257: Concepts: options database^string
1259: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1260: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1261: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1262: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1263: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1264: PetscOptionsList(), PetscOptionsEList()
1265: @*/
1266: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1267: {
1268: char *value;
1269: int ierr;
1270: PetscTruth flag;
1275: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1276: if (!flag) {
1277: if (flg) *flg = PETSC_FALSE;
1278: } else {
1279: if (flg) *flg = PETSC_TRUE;
1280: if (value) {
1281: PetscStrncpy(string,value,len);
1282: } else {
1283: PetscMemzero(string,len);
1284: }
1285: }
1286: return(0);
1287: }
1291: /*@C
1292: PetscOptionsGetStringArray - Gets an array of string values for a particular
1293: option in the database. The values must be separated with commas with
1294: no intervening spaces.
1296: Not Collective
1298: Input Parameters:
1299: + pre - string to prepend to name or PETSC_NULL
1300: . name - the option one is seeking
1301: - nmax - maximum number of strings
1303: Output Parameter:
1304: + strings - location to copy strings
1305: - flg - PETSC_TRUE if found, else PETSC_FALSE
1307: Level: beginner
1309: Notes:
1310: The user should pass in an array of pointers to char, to hold all the
1311: strings returned by this function.
1313: The user is responsible for deallocating the strings that are
1314: returned. The Fortran interface for this routine is not supported.
1316: Contributed by Matthew Knepley.
1318: Concepts: options database^array of strings
1320: .seealso: PetscOptionsGetInt(), PetscOptionsGetReal(),
1321: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetRealArray(), PetscOptionsLogical(),
1322: PetscOptionsName(), PetscOptionsBegin(), PetscOptionsEnd(), PetscOptionsHead(),
1323: PetscOptionsStringArray(),PetscOptionsRealArray(), PetscOptionsScalar(),
1324: PetscOptionsLogicalGroupBegin(), PetscOptionsLogicalGroup(), PetscOptionsLogicalGroupEnd(),
1325: PetscOptionsList(), PetscOptionsEList()
1326: @*/
1327: int PetscOptionsGetStringArray(const char pre[],const char name[],char *strings[],int *nmax,PetscTruth *flg)
1328: {
1329: char *value;
1330: int len,n,ierr;
1331: PetscTruth flag;
1332: PetscToken *token;
1333:
1337: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1338: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1339: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1340: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1341: if (flg) *flg = PETSC_TRUE;
1343: PetscTokenCreate(value,',',&token);
1344: PetscTokenFind(token,&value);
1345: n = 0;
1346: while (n < *nmax) {
1347: if (!value) break;
1348: PetscStrlen(value,&len);
1349: PetscMalloc((len+1)*sizeof(char),&strings[n]);
1350: PetscStrcpy(strings[n],value);
1351: PetscTokenFind(token,&value);
1352: n++;
1353: }
1354: PetscTokenDestroy(token);
1355: *nmax = n;
1356: return(0);
1357: }
1361: /*@C
1362: PetscOptionsAllUsed - Returns a count of the number of options in the
1363: database that have never been selected.
1365: Not Collective
1367: Output Parameter:
1368: . N - count of options not used
1370: Level: advanced
1372: .seealso: PetscOptionsPrint()
1373: @*/
1374: int PetscOptionsAllUsed(int *N)
1375: {
1376: int i,n = 0;
1379: for (i=0; i<options->N; i++) {
1380: if (!options->used[i]) { n++; }
1381: }
1382: *N = n;
1383: return(0);
1384: }
1388: /*@
1389: PetscOptionsLeft - Prints to screen any options that were set and never used.
1391: Not collective
1393: Options Database Key:
1394: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1396: Level: advanced
1398: .seealso: PetscOptionsAllUsed()
1399: @*/
1400: int PetscOptionsLeft(void)
1401: {
1402: int i,ierr;
1405: for (i=0; i<options->N; i++) {
1406: if (!options->used[i]) {
1407: if (options->values[i]) {
1408: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %s\n",options->names[i],options->values[i]);
1409: } else {
1410: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value \n",options->names[i]);
1411: }
1412: }
1413: }
1414: return(0);
1415: }
1417: /*
1418: PetscOptionsCreate - Creates the empty options database.
1420: */
1423: int PetscOptionsCreate(void)
1424: {
1428: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1429: PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1430: options->namegiven = PETSC_FALSE;
1431: options->N = 0;
1432: options->Naliases = 0;
1433: return(0);
1434: }