Actual source code: options.c
1: /*$Id: options.c,v 1.246 2001/03/23 23:20:38 balay 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" /*I "petsc.h" I*/
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: #include "petscfix.h"
20: /*
21: For simplicity, we use a static size database
22: */
23: #define MAXOPTIONS 256
24: #define MAXALIASES 25
26: typedef struct {
27: int N,argc,Naliases;
28: char **args,*names[MAXOPTIONS],*values[MAXOPTIONS];
29: char *aliases1[MAXALIASES],*aliases2[MAXALIASES];
30: int used[MAXOPTIONS];
31: PetscTruth namegiven;
32: char programname[256]; /* HP includes entire path in name */
33: } PetscOptionsTable;
35: static PetscOptionsTable *options = 0;
37: int PetscOptionsAtoi(const char name[],int *a)
38: {
39: int i,ierr,len;
40: PetscTruth decide,tdefault,mouse;
43: PetscStrlen(name,&len);
44: if (!len) SETERRQ(1,"charactor string of length zero has no numerical value");
46: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
47: if (!tdefault) {
48: PetscStrcasecmp(name,"DEFAULT",&tdefault);
49: }
50: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
51: if (!decide) {
52: PetscStrcasecmp(name,"DECIDE",&decide);
53: }
54: PetscStrcasecmp(name,"mouse",&mouse);
56: if (tdefault) {
57: *a = PETSC_DEFAULT;
58: } else if (decide) {
59: *a = PETSC_DECIDE;
60: } else if (mouse) {
61: *a = -1;
62: } else {
63: if (name[0] != '+' && name[0] != '-' && name[0] < '0' && name[0] > '9') {
64: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
65: }
66: for (i=1; i<len; i++) {
67: if (name[i] < '0' || name[i] > '9') {
68: SETERRQ1(1,"Input string %s has no integer value (do not include . in it)",name);
69: }
70: }
71: *a = atoi(name);
72: }
73: return(0);
74: }
76: int PetscOptionsAtod(const char name[],PetscReal *a)
77: {
78: int ierr,len;
79: PetscTruth decide,tdefault;
82: PetscStrlen(name,&len);
83: if (!len) SETERRQ(1,"charactor string of length zero has no numerical value");
85: PetscStrcasecmp(name,"PETSC_DEFAULT",&tdefault);
86: if (!tdefault) {
87: PetscStrcasecmp(name,"DEFAULT",&tdefault);
88: }
89: PetscStrcasecmp(name,"PETSC_DECIDE",&decide);
90: if (!decide) {
91: PetscStrcasecmp(name,"DECIDE",&decide);
92: }
94: if (tdefault) {
95: *a = PETSC_DEFAULT;
96: } else if (decide) {
97: *a = PETSC_DECIDE;
98: } else {
99: if (name[0] != '+' && name[0] != '-' && name[0] != '.' && name[0] < '0' && name[0] > '9') {
100: SETERRQ1(1,"Input string %s has no numeric value ",name);
101: }
102: *a = atof(name);
103: }
104: return(0);
105: }
107: /*@C
108: PetscGetProgramName - Gets the name of the running program.
110: Not Collective
112: Input Parameter:
113: . len - length of the string name
115: Output Parameter:
116: . name - the name of the running program
118: Level: advanced
120: Notes:
121: The name of the program is copied into the user-provided character
122: array of length len. On some machines the program name includes
123: its entire path, so one should generally set len >= 256.
124: @*/
125: int PetscGetProgramName(char name[],int len)
126: {
130: if (!options) SETERRQ(PETSC_ERR_ARG_WRONGSTATE,"Must call PetscInitialize() first");
131: if (!options->namegiven) SETERRQ(PETSC_ERR_PLIB,"Unable to determine program name");
132: PetscStrncpy(name,options->programname,len);
133: return(0);
134: }
136: int PetscSetProgramName(const char name[])
137: {
138: char *sname = 0;
139: int ierr;
142: options->namegiven = PETSC_TRUE;
143: /* Now strip away the path, if absulute path is specified */
144: PetscStrrchr(name,'/',&sname);
145: ierr = PetscStrncpy(options->programname,sname,256);
146: return(0);
147: }
149: /*@C
150: PetscOptionsInsertFile - Inserts options into the database from a file.
152: Not collective: but only processes that call this routine will set the options
153: included in the file
155: Input Parameter:
156: . file - name of file
159: Level: intermediate
161: .seealso: PetscOptionsSetValue(), PetscOptionsPrint(), PetscOptionsHasName(), PetscOptionsGetInt(),
162: PetscOptionsGetDouble(), PetscOptionsGetString(), PetscOptionsGetIntArray()
164: @*/
165: int PetscOptionsInsertFile(const char file[])
166: {
167: char string[128],fname[256],*first,*second,*third,*final;
168: int len,ierr,i;
169: FILE *fd;
172: PetscFixFilename(file,fname);
173: fd = fopen(fname,"r");
174: if (fd) {
175: while (fgets(string,128,fd)) {
176: /* Comments are indicated by #, ! or % in the first column */
177: if (string[0] == '#') continue;
178: if (string[0] == '!') continue;
179: if (string[0] == '%') continue;
180: /* replace tabs with " " */
181: PetscStrlen(string,&len);
182: for (i=0; i<len; i++) {
183: if (string[i] == 't') {
184: string[i] = ' ';
185: }
186: }
187: PetscStrtok(string," ",&first);
188: PetscStrtok(0," ",&second);
189: if (first && first[0] == '-') {
190: if (second) {final = second;} else {final = first;}
191: PetscStrlen(final,&len);
192: while (len > 0 && (final[len-1] == ' ' || final[len-1] == 'n')) {
193: len--; final[len] = 0;
194: }
195: PetscOptionsSetValue(first,second);
196: } else if (first) {
197: PetscTruth match;
199: PetscStrcmp(first,"alias",&match);
200: if (match) {
201: PetscStrtok(0," ",&third);
202: if (!third) SETERRQ1(PETSC_ERR_ARG_WRONG,"Error in options file:alias missing (%s)",second);
203: PetscStrlen(third,&len);
204: if (third[len-1] == 'n') third[len-1] = 0;
205: PetscOptionsSetAlias(second,third);
206: }
207: }
208: }
209: fclose(fd);
210: }
211: return(0);
212: }
214: /*@C
215: PetscOptionsInsert - Inserts into the options database from the command line,
216: the environmental variable and a file.
218: Input Parameters:
219: + argc - count of number of command line arguments
220: . args - the command line arguments
221: - file - optional filename, defaults to ~username/.petscrc
223: Note:
224: Since PetscOptionsInsert() is automatically called by PetscInitialize(),
225: the user does not typically need to call this routine. PetscOptionsInsert()
226: can be called several times, adding additional entries into the database.
228: Level: advanced
230: Concepts: options database^adding
232: .seealso: PetscOptionsDestroy_Private(), PetscOptionsPrint()
233: @*/
234: int PetscOptionsInsert(int *argc,char ***args,const char file[])
235: {
236: int ierr,rank;
237: char pfile[256];
240: MPI_Comm_rank(PETSC_COMM_WORLD,&rank);
242: options->argc = (argc) ? *argc : 0;
243: options->args = (args) ? *args : 0;
245: if (file) {
246: PetscOptionsInsertFile(file);
247: } else {
248: PetscGetHomeDirectory(pfile,240);
249: PetscStrcat(pfile,"/.petscrc");
250: PetscOptionsInsertFile(pfile);
251: }
253: /* insert environmental options */
254: {
255: char *eoptions = 0,*second,*first;
256: int len;
257: if (!rank) {
258: eoptions = (char*)getenv("PETSC_OPTIONS");
259: ierr = PetscStrlen(eoptions,&len);
260: ierr = MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
261: } else {
262: MPI_Bcast(&len,1,MPI_INT,0,PETSC_COMM_WORLD);
263: if (len) {
264: PetscMalloc((len+1)*sizeof(char*),&eoptions);
265: }
266: }
267: if (len) {
268: ierr = MPI_Bcast(eoptions,len,MPI_CHAR,0,PETSC_COMM_WORLD);
269: eoptions[len] = 0;
270: ierr = PetscStrtok(eoptions," ",&first);
271: while (first) {
272: if (first[0] != '-') {PetscStrtok(0," ",&first); continue;}
273: PetscStrtok(0," ",&second);
274: if ((!second) || ((second[0] == '-') && (second[1] > '9'))) {
275: PetscOptionsSetValue(first,(char *)0);
276: first = second;
277: } else {
278: PetscOptionsSetValue(first,second);
279: PetscStrtok(0," ",&first);
280: }
281: }
282: if (rank) {PetscFree(eoptions);}
283: }
284: }
286: /* insert command line options */
287: if (argc && args && *argc) {
288: int left = *argc - 1;
289: char **eargs = *args + 1;
290: PetscTruth isoptions_file,isp4,tisp4;
292: while (left) {
293: PetscStrcmp(eargs[0],"-options_file",&isoptions_file);
294: PetscStrcmp(eargs[0],"-p4pg",&isp4);
295: PetscStrcmp(eargs[0],"-p4wd",&tisp4);
296: isp4 = (PetscTruth) (isp4 || tisp4);
297: PetscStrcmp(eargs[0],"-np",&tisp4);
298: isp4 = (PetscTruth) (isp4 || tisp4);
299: PetscStrcmp(eargs[0],"-p4amslave",&tisp4);
301: if (eargs[0][0] != '-') {
302: eargs++; left--;
303: } else if (isoptions_file) {
304: PetscOptionsInsertFile(eargs[1]);
305: eargs += 2; left -= 2;
307: /*
308: These are "bad" options that MPICH, etc put on the command line
309: we strip them out here.
310: */
311: } else if (tisp4) {
312: eargs += 1; left -= 1;
313: } else if (isp4) {
314: eargs += 2; left -= 2;
315: } else if ((left < 2) || ((eargs[1][0] == '-') &&
316: ((eargs[1][1] > '9') || (eargs[1][1] < '0')))) {
317: PetscOptionsSetValue(eargs[0],PETSC_NULL);
318: eargs++; left--;
319: } else {
320: PetscOptionsSetValue(eargs[0],eargs[1]);
321: eargs += 2; left -= 2;
322: }
323: }
324: }
325: return(0);
326: }
328: /*@C
329: PetscOptionsPrint - Prints the options that have been loaded. This is
330: useful for debugging purposes.
332: Collective on PETSC_COMM_WORLD
334: Input Parameter:
335: . FILE fd - location to print options (usually stdout or stderr)
337: Options Database Key:
338: . -optionstable - Activates PetscOptionsPrint() within PetscFinalize()
340: Level: advanced
342: Concepts: options database^printing
344: .seealso: PetscOptionsAllUsed()
345: @*/
346: int PetscOptionsPrint(FILE *fd)
347: {
348: int i,ierr;
351: if (!fd) fd = stdout;
352: if (!options) {PetscOptionsInsert(0,0,0);}
353: for (i=0; i<options->N; i++) {
354: if (options->values[i]) {
355: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%s %sn",options->names[i],options->values[i]);
356: } else {
357: PetscFPrintf(PETSC_COMM_WORLD,fd,"OptionTable: -%sn",options->names[i]);
358: }
359: }
360: return(0);
361: }
363: /*@C
364: PetscOptionsGetAll - Lists all the options the program was run with in a single string.
366: Not Collective
368: Output Parameter:
369: . copts - pointer where string pointer is stored
371: Level: advanced
373: Concepts: options database^listing
375: .seealso: PetscOptionsAllUsed(), PetscOptionsPrintf()
376: @*/
377: int PetscOptionsGetAll(char *copts[])
378: {
379: int i,ierr,len = 1,lent;
380: char *coptions;
383: if (!options) {PetscOptionsInsert(0,0,0);}
385: /* count the length of the required string */
386: for (i=0; i<options->N; i++) {
387: PetscStrlen(options->names[i],&lent);
388: len += 1 + lent;
389: if (options->values[i]) {
390: PetscStrlen(options->values[i],&lent);
391: len += 1 + lent;
392: }
393: }
394: PetscMalloc(len*sizeof(char),&coptions);
395: coptions[0] = 0;
396: for (i=0; i<options->N; i++) {
397: PetscStrcat(coptions,"-");
398: PetscStrcat(coptions,options->names[i]);
399: PetscStrcat(coptions," ");
400: if (options->values[i]) {
401: PetscStrcat(coptions,options->values[i]);
402: PetscStrcat(coptions," ");
403: }
404: }
405: *copts = coptions;
406: return(0);
407: }
409: /*@C
410: PetscOptionsDestroy - Destroys the option database.
412: Note:
413: Since PetscOptionsDestroy() is called by PetscFinalize(), the user
414: typically does not need to call this routine.
416: Level: developer
418: .seealso: PetscOptionsInsert()
419: @*/
420: int PetscOptionsDestroy(void)
421: {
422: int i;
425: if (!options) return(0);
426: for (i=0; i<options->N; i++) {
427: if (options->names[i]) free(options->names[i]);
428: if (options->values[i]) free(options->values[i]);
429: }
430: for (i=0; i<options->Naliases; i++) {
431: free(options->aliases1[i]);
432: free(options->aliases2[i]);
433: }
434: free(options);
435: options = 0;
436: return(0);
437: }
439: /*@C
440: PetscOptionsSetValue - Sets an option name-value pair in the options
441: database, overriding whatever is already present.
443: Not collective, but setting values on certain processors could cause problems
444: for parallel objects looking for options.
446: Input Parameters:
447: + name - name of option, this SHOULD have the - prepended
448: - value - the option value (not used for all options)
450: Level: intermediate
452: Note:
453: Only some options have values associated with them, such as
454: -ksp_rtol tol. Other options stand alone, such as -ksp_monitor.
456: Concepts: options database^adding option
458: .seealso: PetscOptionsInsert()
459: @*/
460: int PetscOptionsSetValue(const char iname[],const char value[])
461: {
462: int len,N,n,i,ierr;
463: char **names,*name = (char*)iname;
464: PetscTruth gt,match;
467: if (!options) {PetscOptionsInsert(0,0,0);}
469: /* this is so that -h and -help are equivalent (p4 does not like -help)*/
470: PetscStrcmp(name,"-h",&match);
471: if (match) name = "-help";
473: name++;
474: /* first check against aliases */
475: N = options->Naliases;
476: for (i=0; i<N; i++) {
477: PetscStrcmp(options->aliases1[i],name,&match);
478: if (match) {
479: name = options->aliases2[i];
480: break;
481: }
482: }
484: N = options->N;
485: n = N;
486: names = options->names;
487:
488: for (i=0; i<N; i++) {
489: PetscStrcmp(names[i],name,&match);
490: ierr = PetscStrgrt(names[i],name,>);
491: if (match) {
492: if (options->values[i]) free(options->values[i]);
493: PetscStrlen(value,&len);
494: if (len) {
495: options->values[i] = (char*)malloc((len+1)*sizeof(char));
496: PetscStrcpy(options->values[i],value);
497: } else { options->values[i] = 0;}
498: return(0);
499: } else if (gt) {
500: n = i;
501: break;
502: }
503: }
504: if (N >= MAXOPTIONS) {
505: SETERRQ1(1,"No more room in option table, limit %d recompile n src/sys/src/objects/options.c with larger value for MAXOPTIONSn",MAXOPTIONS);
506: }
507: /* shift remaining values down 1 */
508: for (i=N; i>n; i--) {
509: names[i] = names[i-1];
510: options->values[i] = options->values[i-1];
511: options->used[i] = options->used[i-1];
512: }
513: /* insert new name and value */
514: PetscStrlen(name,&len);
515: names[n] = (char*)malloc((len+1)*sizeof(char));
516: PetscStrcpy(names[n],name);
517: if (value) {
518: PetscStrlen(value,&len);
519: options->values[n] = (char*)malloc((len+1)*sizeof(char));
520: PetscStrcpy(options->values[n],value);
521: } else {options->values[n] = 0;}
522: options->used[n] = 0;
523: options->N++;
524: return(0);
525: }
527: /*@C
528: PetscOptionsClearValue - Clears an option name-value pair in the options
529: database, overriding whatever is already present.
531: Not Collective, but setting values on certain processors could cause problems
532: for parallel objects looking for options.
534: Input Parameter:
535: . name - name of option, this SHOULD have the - prepended
537: Level: intermediate
539: Concepts: options database^removing option
540: .seealso: PetscOptionsInsert()
541: @*/
542: int PetscOptionsClearValue(const char iname[])
543: {
544: int N,n,i,ierr;
545: char **names,*name=(char*)iname;
546: PetscTruth gt,match;
549: if (!options) {PetscOptionsInsert(0,0,0);}
551: name++;
553: N = options->N; n = 0;
554: names = options->names;
555:
556: for (i=0; i<N; i++) {
557: PetscStrcmp(names[i],name,&match);
558: ierr = PetscStrgrt(names[i],name,>);
559: if (match) {
560: if (options->values[i]) free(options->values[i]);
561: break;
562: } else if (gt) {
563: return(0); /* it was not listed */
564: }
565: n++;
566: }
567: /* shift remaining values down 1 */
568: for (i=n; i<N-1; i++) {
569: names[i] = names[i+1];
570: options->values[i] = options->values[i+1];
571: options->used[i] = options->used[i+1];
572: }
573: options->N--;
574: return(0);
575: }
577: /*@C
578: PetscOptionsReject - Generates an error if a certain option is given.
580: Not Collective, but setting values on certain processors could cause problems
581: for parallel objects looking for options.
583: Input Parameters:
584: + name - the option one is seeking
585: - mess - error message (may be PETSC_NULL)
587: Level: advanced
589: Concepts: options database^rejecting option
591: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),OptionsHasName(),
592: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
593: @*/
594: int PetscOptionsSetAlias(const char inewname[],const char ioldname[])
595: {
596: int ierr,len,n = options->Naliases;
597: char *newname = (char *)inewname,*oldname = (char*)ioldname;
600: if (newname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliased must have -: Instead %s",newname);
601: if (oldname[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"aliasee must have -: Instead %s",oldname);
602: if (n >= MAXALIASES) {
603: 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);
604: }
606: newname++; oldname++;
607: PetscStrlen(newname,&len);
608: options->aliases1[n] = (char*)malloc((len+1)*sizeof(char));
609: PetscStrcpy(options->aliases1[n],newname);
610: PetscStrlen(oldname,&len);
611: options->aliases2[n] = (char*)malloc((len+1)*sizeof(char));
612: PetscStrcpy(options->aliases2[n],oldname);
613: options->Naliases++;
614: return(0);
615: }
617: static int PetscOptionsFindPair_Private(const char pre[],const char name[],char *value[],PetscTruth *flg)
618: {
619: int i,N,ierr,len;
620: char **names,tmp[256];
621: PetscTruth match;
624: if (!options) {PetscOptionsInsert(0,0,0);}
625: N = options->N;
626: names = options->names;
628: if (name[0] != '-') SETERRQ1(PETSC_ERR_ARG_WRONG,"Name must begin with -: Instead %s",name);
630: /* append prefix to name */
631: if (pre) {
632: PetscStrncpy(tmp,pre,256);
633: PetscStrlen(tmp,&len);
634: PetscStrncat(tmp,name+1,256-len-1);
635: } else {
636: PetscStrncpy(tmp,name+1,256);
637: }
639: /* slow search */
640: *flg = PETSC_FALSE;
641: for (i=0; i<N; i++) {
642: PetscStrcmp(names[i],tmp,&match);
643: if (match) {
644: *value = options->values[i];
645: options->used[i]++;
646: *flg = PETSC_TRUE;
647: break;
648: }
649: }
650: return(0);
651: }
653: /*@C
654: PetscOptionsReject - Generates an error if a certain option is given.
656: Not Collective, but setting values on certain processors could cause problems
657: for parallel objects looking for options.
659: Input Parameters:
660: + name - the option one is seeking
661: - mess - error message (may be PETSC_NULL)
663: Level: advanced
665: Concepts: options database^rejecting option
667: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),OptionsHasName(),
668: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
669: @*/
670: int PetscOptionsReject(const char name[],const char mess[])
671: {
672: int ierr;
673: PetscTruth flag;
676: PetscOptionsHasName(PETSC_NULL,name,&flag);
677: if (flag) {
678: if (mess) {
679: SETERRQ2(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s with %s",name,mess);
680: } else {
681: SETERRQ1(PETSC_ERR_ARG_OUTOFRANGE,"Program has disabled option: %s",name);
682: }
683: }
684: return(0);
685: }
687: /*@C
688: PetscOptionsHasName - Determines whether a certain option is given in the database.
690: Not Collective
692: Input Parameters:
693: + name - the option one is seeking
694: - pre - string to prepend to the name or PETSC_NULL
696: Output Parameters:
697: . flg - PETSC_TRUE if found else PETSC_FALSE.
699: Level: beginner
701: Concepts: options database^has option name
703: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
704: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
705: @*/
706: int PetscOptionsHasName(const char pre[],const char name[],PetscTruth *flg)
707: {
708: char *value;
709: int ierr;
710: PetscTruth isfalse,flag;
713: PetscOptionsFindPair_Private(pre,name,&value,&flag);
715: /* remove if turned off */
716: if (flag) {
717: PetscStrcmp(value,"FALSE",&isfalse);
718: if (isfalse) flag = PETSC_FALSE;
719: PetscStrcmp(value,"NO",&isfalse);
720: if (isfalse) flag = PETSC_FALSE;
721: PetscStrcmp(value,"0",&isfalse);
722: if (isfalse) flag = PETSC_FALSE;
723: PetscStrcmp(value,"false",&isfalse);
724: if (isfalse) flag = PETSC_FALSE;
725: PetscStrcmp(value,"no",&isfalse);
726: }
727: if (flg) *flg = flag;
729: return(0);
730: }
732: /*@C
733: PetscOptionsGetInt - Gets the integer value for a particular option in the database.
735: Not Collective
737: Input Parameters:
738: + pre - the string to prepend to the name or PETSC_NULL
739: - name - the option one is seeking
741: Output Parameter:
742: + ivalue - the integer value to return
743: - flg - PETSC_TRUE if found, else PETSC_FALSE
745: Level: beginner
747: Concepts: options database^has int
749: .seealso: PetscOptionsGetDouble(), PetscOptionsHasName(), PetscOptionsGetString(),
750: PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
751: @*/
752: int PetscOptionsGetInt(const char pre[],const char name[],int *ivalue,PetscTruth *flg)
753: {
754: char *value;
755: int ierr;
756: PetscTruth flag;
759: PetscOptionsFindPair_Private(pre,name,&value,&flag);
760: if (flag) {
761: if (!value) {if (flg) *flg = PETSC_FALSE; *ivalue = 0;}
762: else {
763: if (flg) *flg = PETSC_TRUE;
764: PetscOptionsAtoi(value,ivalue);
765: }
766: } else {
767: if (flg) *flg = PETSC_FALSE;
768: }
769: return(0);
770: }
772: /*@C
773: PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular
774: option in the database.
776: Not Collective
778: Input Parameters:
779: + pre - the string to prepend to the name or PETSC_NULL
780: - name - the option one is seeking
782: Output Parameter:
783: + ivalue - the logical value to return
784: - flg - PETSC_TRUE if found, else PETSC_FALSE
786: Level: beginner
788: Notes:
789: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
790: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
792: Concepts: options database^has logical
794: .seealso: PetscOptionsGetDouble(), PetscOptionsHasName(), PetscOptionsGetString(),
795: PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray(), PetscOptionsGetInt()
796: @*/
797: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
798: {
799: char *value;
800: PetscTruth flag,istrue,isfalse;
801: int ierr;
804: PetscOptionsFindPair_Private(pre,name,&value,&flag);
805: if (flag) {
806: if (flg) *flg = PETSC_TRUE;
807: if (!value) {
808: *ivalue = PETSC_TRUE;
809: } else {
810: *ivalue = PETSC_TRUE;
811: PetscStrcmp(value,"TRUE",&istrue);
812: if (istrue) return(0);
813: PetscStrcmp(value,"YES",&istrue);
814: if (istrue) return(0);
815: PetscStrcmp(value,"YES",&istrue);
816: if (istrue) return(0);
817: PetscStrcmp(value,"1",&istrue);
818: if (istrue) return(0);
819: PetscStrcmp(value,"true",&istrue);
820: if (istrue) return(0);
821: PetscStrcmp(value,"yes",&istrue);
822: if (istrue) return(0);
824: *ivalue = PETSC_FALSE;
825: PetscStrcmp(value,"FALSE",&isfalse);
826: if (isfalse) return(0);
827: PetscStrcmp(value,"NO",&isfalse);
828: if (isfalse) return(0);
829: PetscStrcmp(value,"0",&isfalse);
830: if (isfalse) return(0);
831: PetscStrcmp(value,"false",&isfalse);
832: if (isfalse) return(0);
833: PetscStrcmp(value,"no",&isfalse);
834: if (isfalse) return(0);
836: SETERRQ1(1,"Unknown logical value: %s",value);
837: }
838: } else {
839: if (flg) *flg = PETSC_FALSE;
840: }
841: return(0);
842: }
844: /*@C
845: PetscOptionsGetDouble - Gets the double precision value for a particular
846: option in the database.
848: Not Collective
850: Input Parameters:
851: + pre - string to prepend to each name or PETSC_NULL
852: - name - the option one is seeking
854: Output Parameter:
855: + dvalue - the double value to return
856: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
858: Level: beginner
860: Concepts: options database^has double
862: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
863: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
864: @*/
865: int PetscOptionsGetDouble(const char pre[],const char name[],double *dvalue,PetscTruth *flg)
866: {
867: char *value;
868: int ierr;
869: PetscTruth flag;
872: PetscOptionsFindPair_Private(pre,name,&value,&flag);
873: if (flag) {
874: if (!value) {if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;}
875: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
876: } else {
877: if (flg) *flg = PETSC_FALSE;
878: }
879: return(0);
880: }
882: /*@C
883: PetscOptionsGetScalar - Gets the scalar value for a particular
884: option in the database.
886: Not Collective
888: Input Parameters:
889: + pre - string to prepend to each name or PETSC_NULL
890: - name - the option one is seeking
892: Output Parameter:
893: + dvalue - the double value to return
894: - flg - PETSC_TRUE if found, else PETSC_FALSE
896: Level: beginner
898: Usage:
899: A complex number 2+3i can be specified as 2,3 at the command line.
900: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
902: Concepts: options database^has scalar
904: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
905: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
906: @*/
907: int PetscOptionsGetScalar(const char pre[],const char name[],Scalar *dvalue,PetscTruth *flg)
908: {
909: char *value;
910: PetscTruth flag;
911: int ierr;
912:
914: PetscOptionsFindPair_Private(pre,name,&value,&flag);
915: if (flag) {
916: if (!value) {
917: if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;
918: } else {
919: #if !defined(PETSC_USE_COMPLEX)
920: PetscOptionsAtod(value,dvalue);
921: #else
922: double re=0.0,im=0.0;
923: char *tvalue = 0;
925: PetscStrtok(value,",",&tvalue);
926: if (!tvalue) { SETERRQ(1,"unknown string specifiedn"); }
927: ierr = PetscOptionsAtod(tvalue,&re);
928: ierr = PetscStrtok(0,",",&tvalue);
929: if (!tvalue) { /* Unknown separator used. using only real value */
930: *dvalue = re;
931: } else {
932: ierr = PetscOptionsAtod(tvalue,&im);
933: *dvalue = re + PETSC_i*im;
934: }
935: #endif
936: if (flg) *flg = PETSC_TRUE;
937: }
938: } else { /* flag */
939: if (flg) *flg = PETSC_FALSE;
940: }
941: return(0);
942: }
944: /*@C
945: PetscOptionsGetDoubleArray - Gets an array of double precision values for a
946: particular option in the database. The values must be separated with
947: commas with no intervening spaces.
949: Not Collective
951: Input Parameters:
952: + pre - string to prepend to each name or PETSC_NULL
953: . name - the option one is seeking
954: - nmax - maximum number of values to retrieve
956: Output Parameters:
957: + dvalue - the double value to return
958: . nmax - actual number of values retreived
959: - flg - PETSC_TRUE if found, else PETSC_FALSE
961: Level: beginner
963: Concepts: options database^array of doubles
965: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
966: PetscOptionsGetString(), PetscOptionsGetIntArray()
967: @*/
968: int PetscOptionsGetDoubleArray(const char pre[],const char name[],double dvalue[],int *nmax,PetscTruth *flg)
969: {
970: char *value,*cpy;
971: int n = 0,ierr;
972: PetscTruth flag;
975: PetscOptionsFindPair_Private(pre,name,&value,&flag);
976: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
977: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
979: if (flg) *flg = PETSC_TRUE;
980: /* make a copy of the values, otherwise we destroy the old values */
981: ierr = PetscStrallocpy(value,&cpy);
982: value = cpy;
984: PetscStrtok(value,",",&value);
985: while (n < *nmax) {
986: if (!value) break;
987: PetscOptionsAtod(value,dvalue++);
988: PetscStrtok(0,",",&value);
989: n++;
990: }
991: *nmax = n;
992: PetscFree(cpy);
993: return(0);
994: }
996: /*@C
997: PetscOptionsGetIntArray - Gets an array of integer values for a particular
998: option in the database. The values must be separated with commas with
999: no intervening spaces.
1001: Not Collective
1003: Input Parameters:
1004: + pre - string to prepend to each name or PETSC_NULL
1005: . name - the option one is seeking
1006: - nmax - maximum number of values to retrieve
1008: Output Parameter:
1009: + dvalue - the integer values to return
1010: . nmax - actual number of values retreived
1011: - flg - PETSC_TRUE if found, else PETSC_FALSE
1013: Level: beginner
1015: Concepts: options database^array of ints
1017: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1018: PetscOptionsGetString(), PetscOptionsGetDoubleArray()
1019: @*/
1020: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1021: {
1022: char *value,*cpy;
1023: int n = 0,ierr;
1024: PetscTruth flag;
1027: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1028: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1029: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1031: if (flg) *flg = PETSC_TRUE;
1032: /* make a copy of the values, otherwise we destroy the old values */
1033: ierr = PetscStrallocpy(value,&cpy);
1034: value = cpy;
1036: PetscStrtok(value,",",&value);
1037: while (n < *nmax) {
1038: if (!value) break;
1039: ierr = PetscOptionsAtoi(value,dvalue);
1040: dvalue++;
1041: ierr = PetscStrtok(0,",",&value);
1042: n++;
1043: }
1044: *nmax = n;
1045: PetscFree(cpy);
1046: return(0);
1047: }
1049: /*@C
1050: PetscOptionsGetString - Gets the string value for a particular option in
1051: the database.
1053: Not Collective
1055: Input Parameters:
1056: + pre - string to prepend to name or PETSC_NULL
1057: . name - the option one is seeking
1058: - len - maximum string length
1060: Output Parameters:
1061: + string - location to copy string
1062: - flg - PETSC_TRUE if found, else PETSC_FALSE
1064: Level: beginner
1066: Fortran Note:
1067: The Fortran interface is slightly different from the C/C++
1068: interface (len is not used). Sample usage in Fortran follows
1069: .vb
1070: character *20 string
1071: integer flg, ierr
1072: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1073: .ve
1075: Concepts: options database^string
1077: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
1078: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1079: @*/
1080: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1081: {
1082: char *value;
1083: int ierr;
1084: PetscTruth flag;
1087: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1088: if (!flag) {
1089: if (flg) *flg = PETSC_FALSE;
1090: } else {
1091: if (flg) *flg = PETSC_TRUE;
1092: if (value) {
1093: PetscStrncpy(string,value,len);
1094: } else {
1095: PetscMemzero(string,len);
1096: }
1097: }
1098: return(0);
1099: }
1101: /*@C
1102: PetscOptionsGetStringArray - Gets an array of string values for a particular
1103: option in the database. The values must be separated with commas with
1104: no intervening spaces.
1106: Not Collective
1108: Input Parameters:
1109: + pre - string to prepend to name or PETSC_NULL
1110: . name - the option one is seeking
1111: - nmax - maximum number of strings
1113: Output Parameter:
1114: + strings - location to copy strings
1115: - flg - PETSC_TRUE if found, else PETSC_FALSE
1117: Level: beginner
1119: Notes:
1120: The user should pass in an array of pointers to char, to hold all the
1121: strings returned by this function.
1123: The user is responsible for deallocating the strings that are
1124: returned. The Fortran interface for this routine is not supported.
1126: Contributed by Matthew Knepley.
1128: Concepts: options database^array of strings
1130: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
1131: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1132: @*/
1133: int PetscOptionsGetStringArray(const char pre[],const char name[],char **strings,int *nmax,PetscTruth *flg)
1134: {
1135: char *value,*cpy;
1136: int len,n,ierr;
1137: PetscTruth flag;
1140: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1141: if (!flag) {*nmax = 0; if (flg) *flg = PETSC_FALSE; return(0);}
1142: if (!value) {*nmax = 0; if (flg) *flg = PETSC_FALSE;return(0);}
1143: if (!*nmax) {if (flg) *flg = PETSC_FALSE;return(0);}
1144: if (flg) *flg = PETSC_TRUE;
1146: /* make a copy of the values, otherwise we destroy the old values */
1147: ierr = PetscStrallocpy(value,&cpy);
1148: value = cpy;
1150: PetscStrtok(value,",",&value);
1151: n = 0;
1152: while (n < *nmax) {
1153: if (!value) break;
1154: PetscStrlen(value,&len);
1155: PetscMalloc((len+1)*sizeof(char),&strings[n]);
1156: PetscStrcpy(strings[n],value);
1157: PetscStrtok(0,",",&value);
1158: n++;
1159: }
1160: *nmax = n;
1161: PetscFree(cpy);
1162: return(0);
1163: }
1165: /*@C
1166: PetscOptionsAllUsed - Returns a count of the number of options in the
1167: database that have never been selected.
1169: Not Collective
1171: Output Parameter:
1172: . N - count of options not used
1174: Level: advanced
1176: .seealso: PetscOptionsPrint()
1177: @*/
1178: int PetscOptionsAllUsed(int *N)
1179: {
1180: int i,n = 0;
1183: for (i=0; i<options->N; i++) {
1184: if (!options->used[i]) { n++; }
1185: }
1186: *N = n;
1187: return(0);
1188: }
1190: /*@
1191: PetscOptionsLeft - Prints to screen any options that were set and never used.
1193: Not collective
1195: Options Database Key:
1196: . -optionsleft - Activates OptionsAllUsed() within PetscFinalize()
1198: Level: advanced
1200: .seealso: PetscOptionsAllUsed()
1201: @*/
1202: int PetscOptionsLeft(void)
1203: {
1204: int i,ierr;
1207: for (i=0; i<options->N; i++) {
1208: if (!options->used[i]) {
1209: if (options->values[i]) {
1210: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %sn",options->names[i],options->values[i]);
1211: } else {
1212: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value n",options->names[i]);
1213: }
1214: }
1215: }
1216: return(0);
1217: }
1219: /*
1220: PetscOptionsCreate - Creates the empty options database.
1222: */
1223: int PetscOptionsCreate(void)
1224: {
1228: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1229: ierr = PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1230: options->namegiven = PETSC_FALSE;
1231: options->N = 0;
1232: options->Naliases = 0;
1233: return(0);
1234: }