Actual source code: options.c
1: /*$Id: options.c,v 1.248 2001/04/13 15:06:15 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: #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;
760: PetscOptionsFindPair_Private(pre,name,&value,&flag);
761: if (flag) {
762: if (!value) {if (flg) *flg = PETSC_FALSE; *ivalue = 0;}
763: else {
764: if (flg) *flg = PETSC_TRUE;
765: PetscOptionsAtoi(value,ivalue);
766: }
767: } else {
768: if (flg) *flg = PETSC_FALSE;
769: }
770: return(0);
771: }
773: /*@C
774: PetscOptionsGetLogical - Gets the Logical (true or false) value for a particular
775: option in the database.
777: Not Collective
779: Input Parameters:
780: + pre - the string to prepend to the name or PETSC_NULL
781: - name - the option one is seeking
783: Output Parameter:
784: + ivalue - the logical value to return
785: - flg - PETSC_TRUE if found, else PETSC_FALSE
787: Level: beginner
789: Notes:
790: TRUE, true, YES, yes, nostring, and 1 all translate to PETSC_TRUE
791: FALSE, false, NO, no, and 0 all translate to PETSC_FALSE
793: Concepts: options database^has logical
795: .seealso: PetscOptionsGetDouble(), PetscOptionsHasName(), PetscOptionsGetString(),
796: PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray(), PetscOptionsGetInt()
797: @*/
798: int PetscOptionsGetLogical(const char pre[],const char name[],PetscTruth *ivalue,PetscTruth *flg)
799: {
800: char *value;
801: PetscTruth flag,istrue,isfalse;
802: int ierr;
806: PetscOptionsFindPair_Private(pre,name,&value,&flag);
807: if (flag) {
808: if (flg) *flg = PETSC_TRUE;
809: if (!value) {
810: *ivalue = PETSC_TRUE;
811: } else {
812: *ivalue = PETSC_TRUE;
813: PetscStrcmp(value,"TRUE",&istrue);
814: if (istrue) return(0);
815: PetscStrcmp(value,"YES",&istrue);
816: if (istrue) return(0);
817: PetscStrcmp(value,"YES",&istrue);
818: if (istrue) return(0);
819: PetscStrcmp(value,"1",&istrue);
820: if (istrue) return(0);
821: PetscStrcmp(value,"true",&istrue);
822: if (istrue) return(0);
823: PetscStrcmp(value,"yes",&istrue);
824: if (istrue) return(0);
826: *ivalue = PETSC_FALSE;
827: PetscStrcmp(value,"FALSE",&isfalse);
828: if (isfalse) return(0);
829: PetscStrcmp(value,"NO",&isfalse);
830: if (isfalse) return(0);
831: PetscStrcmp(value,"0",&isfalse);
832: if (isfalse) return(0);
833: PetscStrcmp(value,"false",&isfalse);
834: if (isfalse) return(0);
835: PetscStrcmp(value,"no",&isfalse);
836: if (isfalse) return(0);
838: SETERRQ1(1,"Unknown logical value: %s",value);
839: }
840: } else {
841: if (flg) *flg = PETSC_FALSE;
842: }
843: return(0);
844: }
846: /*@C
847: PetscOptionsGetDouble - Gets the double precision value for a particular
848: option in the database.
850: Not Collective
852: Input Parameters:
853: + pre - string to prepend to each name or PETSC_NULL
854: - name - the option one is seeking
856: Output Parameter:
857: + dvalue - the double value to return
858: - flg - PETSC_TRUE if found, PETSC_FALSE if not found
860: Level: beginner
862: Concepts: options database^has double
864: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
865: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
866: @*/
867: int PetscOptionsGetDouble(const char pre[],const char name[],double *dvalue,PetscTruth *flg)
868: {
869: char *value;
870: int ierr;
871: PetscTruth flag;
875: PetscOptionsFindPair_Private(pre,name,&value,&flag);
876: if (flag) {
877: if (!value) {if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;}
878: else {if (flg) *flg = PETSC_TRUE; PetscOptionsAtod(value,dvalue);}
879: } else {
880: if (flg) *flg = PETSC_FALSE;
881: }
882: return(0);
883: }
885: /*@C
886: PetscOptionsGetScalar - Gets the scalar value for a particular
887: option in the database.
889: Not Collective
891: Input Parameters:
892: + pre - string to prepend to each name or PETSC_NULL
893: - name - the option one is seeking
895: Output Parameter:
896: + dvalue - the double value to return
897: - flg - PETSC_TRUE if found, else PETSC_FALSE
899: Level: beginner
901: Usage:
902: A complex number 2+3i can be specified as 2,3 at the command line.
903: or a number 2.0e-10 - 3.3e-20 i can be specified as 2.0e-10,3.3e-20
905: Concepts: options database^has scalar
907: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
908: PetscOptionsGetString(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
909: @*/
910: int PetscOptionsGetScalar(const char pre[],const char name[],Scalar *dvalue,PetscTruth *flg)
911: {
912: char *value;
913: PetscTruth flag;
914: int ierr;
915:
918: PetscOptionsFindPair_Private(pre,name,&value,&flag);
919: if (flag) {
920: if (!value) {
921: if (flg) *flg = PETSC_FALSE; *dvalue = 0.0;
922: } else {
923: #if !defined(PETSC_USE_COMPLEX)
924: PetscOptionsAtod(value,dvalue);
925: #else
926: double re=0.0,im=0.0;
927: char *tvalue = 0;
929: PetscStrtok(value,",",&tvalue);
930: if (!tvalue) { SETERRQ(1,"unknown string specifiedn"); }
931: ierr = PetscOptionsAtod(tvalue,&re);
932: ierr = PetscStrtok(0,",",&tvalue);
933: if (!tvalue) { /* Unknown separator used. using only real value */
934: *dvalue = re;
935: } else {
936: ierr = PetscOptionsAtod(tvalue,&im);
937: *dvalue = re + PETSC_i*im;
938: }
939: #endif
940: if (flg) *flg = PETSC_TRUE;
941: }
942: } else { /* flag */
943: if (flg) *flg = PETSC_FALSE;
944: }
945: return(0);
946: }
948: /*@C
949: PetscOptionsGetDoubleArray - Gets an array of double precision values for a
950: particular option in the database. The values must be separated with
951: commas with no intervening spaces.
953: Not Collective
955: Input Parameters:
956: + pre - string to prepend to each name or PETSC_NULL
957: . name - the option one is seeking
958: - nmax - maximum number of values to retrieve
960: Output Parameters:
961: + dvalue - the double value to return
962: . nmax - actual number of values retreived
963: - flg - PETSC_TRUE if found, else PETSC_FALSE
965: Level: beginner
967: Concepts: options database^array of doubles
969: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
970: PetscOptionsGetString(), PetscOptionsGetIntArray()
971: @*/
972: int PetscOptionsGetDoubleArray(const char pre[],const char name[],double dvalue[],int *nmax,PetscTruth *flg)
973: {
974: char *value;
975: int n = 0,ierr;
976: PetscTruth flag;
980: PetscOptionsFindPair_Private(pre,name,&value,&flag);
981: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
982: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
984: if (flg) *flg = PETSC_TRUE;
986: PetscStrtok(value,",",&value);
987: while (n < *nmax) {
988: if (!value) break;
989: PetscOptionsAtod(value,dvalue++);
990: PetscStrtok(0,",",&value);
991: n++;
992: }
993: *nmax = n;
994: return(0);
995: }
997: /*@C
998: PetscOptionsGetIntArray - Gets an array of integer values for a particular
999: option in the database. The values must be separated with commas with
1000: no intervening spaces.
1002: Not Collective
1004: Input Parameters:
1005: + pre - string to prepend to each name or PETSC_NULL
1006: . name - the option one is seeking
1007: - nmax - maximum number of values to retrieve
1009: Output Parameter:
1010: + dvalue - the integer values to return
1011: . nmax - actual number of values retreived
1012: - flg - PETSC_TRUE if found, else PETSC_FALSE
1014: Level: beginner
1016: Concepts: options database^array of ints
1018: .seealso: PetscOptionsGetInt(), PetscOptionsHasName(),
1019: PetscOptionsGetString(), PetscOptionsGetDoubleArray()
1020: @*/
1021: int PetscOptionsGetIntArray(const char pre[],const char name[],int dvalue[],int *nmax,PetscTruth *flg)
1022: {
1023: char *value;
1024: int n = 0,ierr;
1025: PetscTruth flag;
1029: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1030: if (!flag) {if (flg) *flg = PETSC_FALSE; *nmax = 0; return(0);}
1031: if (!value) {if (flg) *flg = PETSC_TRUE; *nmax = 0; return(0);}
1033: if (flg) *flg = PETSC_TRUE;
1035: PetscStrtok(value,",",&value);
1036: while (n < *nmax) {
1037: if (!value) break;
1038: ierr = PetscOptionsAtoi(value,dvalue);
1039: dvalue++;
1040: ierr = PetscStrtok(0,",",&value);
1041: n++;
1042: }
1043: *nmax = n;
1044: return(0);
1045: }
1047: /*@C
1048: PetscOptionsGetString - Gets the string value for a particular option in
1049: the database.
1051: Not Collective
1053: Input Parameters:
1054: + pre - string to prepend to name or PETSC_NULL
1055: . name - the option one is seeking
1056: - len - maximum string length
1058: Output Parameters:
1059: + string - location to copy string
1060: - flg - PETSC_TRUE if found, else PETSC_FALSE
1062: Level: beginner
1064: Fortran Note:
1065: The Fortran interface is slightly different from the C/C++
1066: interface (len is not used). Sample usage in Fortran follows
1067: .vb
1068: character *20 string
1069: integer flg, ierr
1070: call PetscOptionsGetString(PETSC_NULL_CHARACTER,'-s',string,flg,ierr)
1071: .ve
1073: Concepts: options database^string
1075: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
1076: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1077: @*/
1078: int PetscOptionsGetString(const char pre[],const char name[],char string[],int len,PetscTruth *flg)
1079: {
1080: char *value;
1081: int ierr;
1082: PetscTruth flag;
1086: PetscOptionsFindPair_Private(pre,name,&value,&flag);
1087: if (!flag) {
1088: if (flg) *flg = PETSC_FALSE;
1089: } else {
1090: if (flg) *flg = PETSC_TRUE;
1091: if (value) {
1092: PetscStrncpy(string,value,len);
1093: } else {
1094: PetscMemzero(string,len);
1095: }
1096: }
1097: return(0);
1098: }
1100: /*@C
1101: PetscOptionsGetStringArray - Gets an array of string values for a particular
1102: option in the database. The values must be separated with commas with
1103: no intervening spaces.
1105: Not Collective
1107: Input Parameters:
1108: + pre - string to prepend to name or PETSC_NULL
1109: . name - the option one is seeking
1110: - nmax - maximum number of strings
1112: Output Parameter:
1113: + strings - location to copy strings
1114: - flg - PETSC_TRUE if found, else PETSC_FALSE
1116: Level: beginner
1118: Notes:
1119: The user should pass in an array of pointers to char, to hold all the
1120: strings returned by this function.
1122: The user is responsible for deallocating the strings that are
1123: returned. The Fortran interface for this routine is not supported.
1125: Contributed by Matthew Knepley.
1127: Concepts: options database^array of strings
1129: .seealso: PetscOptionsGetInt(), PetscOptionsGetDouble(),
1130: PetscOptionsHasName(), PetscOptionsGetIntArray(), PetscOptionsGetDoubleArray()
1131: @*/
1132: int PetscOptionsGetStringArray(const char pre[],const char name[],char **strings,int *nmax,PetscTruth *flg)
1133: {
1134: char *value;
1135: int len,n,ierr;
1136: 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: PetscStrtok(value,",",&value);
1147: n = 0;
1148: while (n < *nmax) {
1149: if (!value) break;
1150: PetscStrlen(value,&len);
1151: PetscMalloc((len+1)*sizeof(char),&strings[n]);
1152: PetscStrcpy(strings[n],value);
1153: PetscStrtok(0,",",&value);
1154: n++;
1155: }
1156: *nmax = n;
1157: return(0);
1158: }
1160: /*@C
1161: PetscOptionsAllUsed - Returns a count of the number of options in the
1162: database that have never been selected.
1164: Not Collective
1166: Output Parameter:
1167: . N - count of options not used
1169: Level: advanced
1171: .seealso: PetscOptionsPrint()
1172: @*/
1173: int PetscOptionsAllUsed(int *N)
1174: {
1175: int i,n = 0;
1178: for (i=0; i<options->N; i++) {
1179: if (!options->used[i]) { n++; }
1180: }
1181: *N = n;
1182: return(0);
1183: }
1185: /*@
1186: PetscOptionsLeft - Prints to screen any options that were set and never used.
1188: Not collective
1190: Options Database Key:
1191: . -options_left - Activates OptionsAllUsed() within PetscFinalize()
1193: Level: advanced
1195: .seealso: PetscOptionsAllUsed()
1196: @*/
1197: int PetscOptionsLeft(void)
1198: {
1199: int i,ierr;
1202: for (i=0; i<options->N; i++) {
1203: if (!options->used[i]) {
1204: if (options->values[i]) {
1205: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s value: %sn",options->names[i],options->values[i]);
1206: } else {
1207: PetscPrintf(PETSC_COMM_WORLD,"Option left: name:-%s no value n",options->names[i]);
1208: }
1209: }
1210: }
1211: return(0);
1212: }
1214: /*
1215: PetscOptionsCreate - Creates the empty options database.
1217: */
1218: int PetscOptionsCreate(void)
1219: {
1223: options = (PetscOptionsTable*)malloc(sizeof(PetscOptionsTable));
1224: ierr = PetscMemzero(options->used,MAXOPTIONS*sizeof(int));
1225: options->namegiven = PETSC_FALSE;
1226: options->N = 0;
1227: options->Naliases = 0;
1228: return(0);
1229: }